1 =head2 guestfs_add_cdrom
3 int guestfs_add_cdrom (guestfs_h *handle,
6 This function adds a virtual CD-ROM disk image to the guest.
8 This is equivalent to the qemu parameter C<-cdrom filename>.
10 This function returns 0 on success or -1 on error.
12 =head2 guestfs_add_drive
14 int guestfs_add_drive (guestfs_h *handle,
15 const char *filename);
17 This function adds a virtual machine disk image C<filename> to the
18 guest. The first time you call this function, the disk appears as IDE
19 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
22 You don't necessarily need to be root when using libguestfs. However
23 you obviously do need sufficient permissions to access the filename
24 for whatever operations you want to perform (ie. read access if you
25 just want to read the image or write access if you want to modify the
28 This is equivalent to the qemu parameter C<-drive file=filename>.
30 This function returns 0 on success or -1 on error.
32 =head2 guestfs_aug_close
34 int guestfs_aug_close (guestfs_h *handle);
36 Close the current Augeas handle and free up any resources
37 used by it. After calling this, you have to call
38 C<guestfs_aug_init> again before you can use any other
41 This function returns 0 on success or -1 on error.
43 =head2 guestfs_aug_defnode
45 struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *handle,
50 Defines a variable C<name> whose value is the result of
53 If C<expr> evaluates to an empty nodeset, a node is created,
54 equivalent to calling C<guestfs_aug_set> C<expr>, C<value>.
55 C<name> will be the nodeset containing that single node.
57 On success this returns a pair containing the
58 number of nodes in the nodeset, and a boolean flag
59 if a node was created.
61 This function returns a C<struct guestfs_int_bool *>.
62 I<The caller must call C<guestfs_free_int_bool> after use.>.
64 =head2 guestfs_aug_defvar
66 int guestfs_aug_defvar (guestfs_h *handle,
70 Defines an Augeas variable C<name> whose value is the result
71 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
74 On success this returns the number of nodes in C<expr>, or
75 C<0> if C<expr> evaluates to something which is not a nodeset.
77 On error this function returns -1.
79 =head2 guestfs_aug_get
81 char *guestfs_aug_get (guestfs_h *handle,
84 Look up the value associated with C<path>. If C<path>
85 matches exactly one node, the C<value> is returned.
87 This function returns a string or NULL on error.
88 I<The caller must free the returned string after use>.
90 =head2 guestfs_aug_init
92 int guestfs_aug_init (guestfs_h *handle,
96 Create a new Augeas handle for editing configuration files.
97 If there was any previous Augeas handle associated with this
98 guestfs session, then it is closed.
100 You must call this before using any other C<guestfs_aug_*>
103 C<root> is the filesystem root. C<root> must not be NULL,
106 The flags are the same as the flags defined in
107 E<lt>augeas.hE<gt>, the logical I<or> of the following
112 =item 1 C<AUG_SAVE_BACKUP>
114 Keep the original file with a C<.augsave> extension.
116 =item 2 C<AUG_SAVE_NEWFILE>
118 Save changes into a file with extension C<.augnew>, and
119 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
121 =item 4 C<AUG_TYPE_CHECK>
123 Typecheck lenses (can be expensive).
125 =item 8 C<AUG_NO_STDINC>
127 Do not use standard load path for modules.
129 =item 16 C<AUG_SAVE_NOOP>
131 Make save a no-op, just record what would have been changed.
133 =item 32 C<AUG_NO_LOAD>
135 Do not load the tree in C<guestfs_aug_init>.
139 To close the handle, you can call C<guestfs_aug_close>.
141 To find out more about Augeas, see L<http://augeas.net/>.
143 This function returns 0 on success or -1 on error.
145 =head2 guestfs_aug_insert
147 int guestfs_aug_insert (guestfs_h *handle,
152 Create a new sibling C<label> for C<path>, inserting it into
153 the tree before or after C<path> (depending on the boolean
156 C<path> must match exactly one existing node in the tree, and
157 C<label> must be a label, ie. not contain C</>, C<*> or end
158 with a bracketed index C<[N]>.
160 This function returns 0 on success or -1 on error.
162 =head2 guestfs_aug_load
164 int guestfs_aug_load (guestfs_h *handle);
166 Load files into the tree.
168 See C<aug_load> in the Augeas documentation for the full gory
171 This function returns 0 on success or -1 on error.
173 =head2 guestfs_aug_match
175 char **guestfs_aug_match (guestfs_h *handle,
178 Returns a list of paths which match the path expression C<path>.
179 The returned paths are sufficiently qualified so that they match
180 exactly one node in the current tree.
182 This function returns a NULL-terminated array of strings
183 (like L<environ(3)>), or NULL if there was an error.
184 I<The caller must free the strings and the array after use>.
186 =head2 guestfs_aug_mv
188 int guestfs_aug_mv (guestfs_h *handle,
192 Move the node C<src> to C<dest>. C<src> must match exactly
193 one node. C<dest> is overwritten if it exists.
195 This function returns 0 on success or -1 on error.
197 =head2 guestfs_aug_rm
199 int guestfs_aug_rm (guestfs_h *handle,
202 Remove C<path> and all of its children.
204 On success this returns the number of entries which were removed.
206 On error this function returns -1.
208 =head2 guestfs_aug_save
210 int guestfs_aug_save (guestfs_h *handle);
212 This writes all pending changes to disk.
214 The flags which were passed to C<guestfs_aug_init> affect exactly
217 This function returns 0 on success or -1 on error.
219 =head2 guestfs_aug_set
221 int guestfs_aug_set (guestfs_h *handle,
225 Set the value associated with C<path> to C<value>.
227 This function returns 0 on success or -1 on error.
231 char *guestfs_cat (guestfs_h *handle,
234 Return the contents of the file named C<path>.
236 Note that this function cannot correctly handle binary files
237 (specifically, files containing C<\0> character which is treated
238 as end of string). For those you need to use the C<guestfs_read_file>
239 function which has a more complex interface.
241 This function returns a string or NULL on error.
242 I<The caller must free the returned string after use>.
244 Because of the message protocol, there is a transfer limit
245 of somewhere between 2MB and 4MB. To transfer large files you should use
248 =head2 guestfs_config
250 int guestfs_config (guestfs_h *handle,
251 const char *qemuparam,
252 const char *qemuvalue);
254 This can be used to add arbitrary qemu command line parameters
255 of the form C<-param value>. Actually it's not quite arbitrary - we
256 prevent you from setting some parameters which would interfere with
257 parameters that we use.
259 The first character of C<param> string must be a C<-> (dash).
261 C<value> can be NULL.
263 This function returns 0 on success or -1 on error.
265 =head2 guestfs_get_autosync
267 int guestfs_get_autosync (guestfs_h *handle);
269 Get the autosync flag.
271 This function returns a C truth value on success or -1 on error.
273 =head2 guestfs_get_path
275 const char *guestfs_get_path (guestfs_h *handle);
277 Return the current search path.
279 This is always non-NULL. If it wasn't set already, then this will
280 return the default path.
282 This function returns a string or NULL on error.
283 The string is owned by the guest handle and must I<not> be freed.
285 =head2 guestfs_get_verbose
287 int guestfs_get_verbose (guestfs_h *handle);
289 This returns the verbose messages flag.
291 This function returns a C truth value on success or -1 on error.
293 =head2 guestfs_kill_subprocess
295 int guestfs_kill_subprocess (guestfs_h *handle);
297 This kills the qemu subprocess. You should never need to call this.
299 This function returns 0 on success or -1 on error.
301 =head2 guestfs_launch
303 int guestfs_launch (guestfs_h *handle);
305 Internally libguestfs is implemented by running a virtual machine
308 You should call this after configuring the handle
309 (eg. adding drives) but before performing any actions.
311 This function returns 0 on success or -1 on error.
313 =head2 guestfs_list_devices
315 char **guestfs_list_devices (guestfs_h *handle);
317 List all the block devices.
319 The full block device names are returned, eg. C</dev/sda>
321 This function returns a NULL-terminated array of strings
322 (like L<environ(3)>), or NULL if there was an error.
323 I<The caller must free the strings and the array after use>.
325 =head2 guestfs_list_partitions
327 char **guestfs_list_partitions (guestfs_h *handle);
329 List all the partitions detected on all block devices.
331 The full partition device names are returned, eg. C</dev/sda1>
333 This does not return logical volumes. For that you will need to
336 This function returns a NULL-terminated array of strings
337 (like L<environ(3)>), or NULL if there was an error.
338 I<The caller must free the strings and the array after use>.
342 char *guestfs_ll (guestfs_h *handle,
343 const char *directory);
345 List the files in C<directory> (relative to the root directory,
346 there is no cwd) in the format of 'ls -la'.
348 This command is mostly useful for interactive sessions. It
349 is I<not> intended that you try to parse the output string.
351 This function returns a string or NULL on error.
352 I<The caller must free the returned string after use>.
356 char **guestfs_ls (guestfs_h *handle,
357 const char *directory);
359 List the files in C<directory> (relative to the root directory,
360 there is no cwd). The '.' and '..' entries are not returned, but
361 hidden files are shown.
363 This command is mostly useful for interactive sessions. Programs
364 should probably use C<guestfs_readdir> instead.
366 This function returns a NULL-terminated array of strings
367 (like L<environ(3)>), or NULL if there was an error.
368 I<The caller must free the strings and the array after use>.
372 char **guestfs_lvs (guestfs_h *handle);
374 List all the logical volumes detected. This is the equivalent
375 of the L<lvs(8)> command.
377 This returns a list of the logical volume device names
378 (eg. C</dev/VolGroup00/LogVol00>).
380 See also C<guestfs_lvs_full>.
382 This function returns a NULL-terminated array of strings
383 (like L<environ(3)>), or NULL if there was an error.
384 I<The caller must free the strings and the array after use>.
386 =head2 guestfs_lvs_full
388 struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
390 List all the logical volumes detected. This is the equivalent
391 of the L<lvs(8)> command. The "full" version includes all fields.
393 This function returns a C<struct guestfs_lvm_lv_list *>.
394 I<The caller must call C<guestfs_free_lvm_lv_list> after use.>.
398 int guestfs_mount (guestfs_h *handle,
400 const char *mountpoint);
402 Mount a guest disk at a position in the filesystem. Block devices
403 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
404 the guest. If those block devices contain partitions, they will have
405 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
408 The rules are the same as for L<mount(2)>: A filesystem must
409 first be mounted on C</> before others can be mounted. Other
410 filesystems can only be mounted on directories which already
413 The mounted filesystem is writable, if we have sufficient permissions
414 on the underlying device.
416 The filesystem options C<sync> and C<noatime> are set with this
417 call, in order to improve reliability.
419 This function returns 0 on success or -1 on error.
423 char **guestfs_pvs (guestfs_h *handle);
425 List all the physical volumes detected. This is the equivalent
426 of the L<pvs(8)> command.
428 This returns a list of just the device names that contain
429 PVs (eg. C</dev/sda2>).
431 See also C<guestfs_pvs_full>.
433 This function returns a NULL-terminated array of strings
434 (like L<environ(3)>), or NULL if there was an error.
435 I<The caller must free the strings and the array after use>.
437 =head2 guestfs_pvs_full
439 struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
441 List all the physical volumes detected. This is the equivalent
442 of the L<pvs(8)> command. The "full" version includes all fields.
444 This function returns a C<struct guestfs_lvm_pv_list *>.
445 I<The caller must call C<guestfs_free_lvm_pv_list> after use.>.
447 =head2 guestfs_read_lines
449 char **guestfs_read_lines (guestfs_h *handle,
452 Return the contents of the file named C<path>.
454 The file contents are returned as a list of lines. Trailing
455 C<LF> and C<CRLF> character sequences are I<not> returned.
457 Note that this function cannot correctly handle binary files
458 (specifically, files containing C<\0> character which is treated
459 as end of line). For those you need to use the C<guestfs_read_file>
460 function which has a more complex interface.
462 This function returns a NULL-terminated array of strings
463 (like L<environ(3)>), or NULL if there was an error.
464 I<The caller must free the strings and the array after use>.
466 =head2 guestfs_set_autosync
468 int guestfs_set_autosync (guestfs_h *handle,
471 If C<autosync> is true, this enables autosync. Libguestfs will make a
472 best effort attempt to run C<guestfs_sync> when the handle is closed
473 (also if the program exits without closing handles).
475 This function returns 0 on success or -1 on error.
477 =head2 guestfs_set_path
479 int guestfs_set_path (guestfs_h *handle,
482 Set the path that libguestfs searches for kernel and initrd.img.
484 The default is C<$libdir/guestfs> unless overridden by setting
485 C<LIBGUESTFS_PATH> environment variable.
487 The string C<path> is stashed in the libguestfs handle, so the caller
488 must make sure it remains valid for the lifetime of the handle.
490 Setting C<path> to C<NULL> restores the default path.
492 This function returns 0 on success or -1 on error.
494 =head2 guestfs_set_verbose
496 int guestfs_set_verbose (guestfs_h *handle,
499 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
501 Verbose messages are disabled unless the environment variable
502 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
504 This function returns 0 on success or -1 on error.
508 int guestfs_sync (guestfs_h *handle);
510 This syncs the disk, so that any writes are flushed through to the
511 underlying disk image.
513 You should always call this if you have modified a disk image, before
516 This function returns 0 on success or -1 on error.
520 int guestfs_touch (guestfs_h *handle,
523 Touch acts like the L<touch(1)> command. It can be used to
524 update the timestamps on a file, or, if the file does not exist,
525 to create a new zero-length file.
527 This function returns 0 on success or -1 on error.
531 char **guestfs_vgs (guestfs_h *handle);
533 List all the volumes groups detected. This is the equivalent
534 of the L<vgs(8)> command.
536 This returns a list of just the volume group names that were
537 detected (eg. C<VolGroup00>).
539 See also C<guestfs_vgs_full>.
541 This function returns a NULL-terminated array of strings
542 (like L<environ(3)>), or NULL if there was an error.
543 I<The caller must free the strings and the array after use>.
545 =head2 guestfs_vgs_full
547 struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
549 List all the volumes groups detected. This is the equivalent
550 of the L<vgs(8)> command. The "full" version includes all fields.
552 This function returns a C<struct guestfs_lvm_vg_list *>.
553 I<The caller must call C<guestfs_free_lvm_vg_list> after use.>.
555 =head2 guestfs_wait_ready
557 int guestfs_wait_ready (guestfs_h *handle);
559 Internally libguestfs is implemented by running a virtual machine
562 You should call this after C<guestfs_launch> to wait for the launch
565 This function returns 0 on success or -1 on error.