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 C<AUG_SAVE_BACKUP> = 1
114 Keep the original file with a C<.augsave> extension.
116 =item C<AUG_SAVE_NEWFILE> = 2
118 Save changes into a file with extension C<.augnew>, and
119 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
121 =item C<AUG_TYPE_CHECK> = 4
123 Typecheck lenses (can be expensive).
125 =item C<AUG_NO_STDINC> = 8
127 Do not use standard load path for modules.
129 =item C<AUG_SAVE_NOOP> = 16
131 Make save a no-op, just record what would have been changed.
133 =item C<AUG_NO_LOAD> = 32
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_ls
175 char **guestfs_aug_ls (guestfs_h *handle,
178 This is just a shortcut for listing C<guestfs_aug_match>
179 C<path/*> and sorting the resulting nodes into alphabetical order.
181 This function returns a NULL-terminated array of strings
182 (like L<environ(3)>), or NULL if there was an error.
183 I<The caller must free the strings and the array after use>.
185 =head2 guestfs_aug_match
187 char **guestfs_aug_match (guestfs_h *handle,
190 Returns a list of paths which match the path expression C<path>.
191 The returned paths are sufficiently qualified so that they match
192 exactly one node in the current tree.
194 This function returns a NULL-terminated array of strings
195 (like L<environ(3)>), or NULL if there was an error.
196 I<The caller must free the strings and the array after use>.
198 =head2 guestfs_aug_mv
200 int guestfs_aug_mv (guestfs_h *handle,
204 Move the node C<src> to C<dest>. C<src> must match exactly
205 one node. C<dest> is overwritten if it exists.
207 This function returns 0 on success or -1 on error.
209 =head2 guestfs_aug_rm
211 int guestfs_aug_rm (guestfs_h *handle,
214 Remove C<path> and all of its children.
216 On success this returns the number of entries which were removed.
218 On error this function returns -1.
220 =head2 guestfs_aug_save
222 int guestfs_aug_save (guestfs_h *handle);
224 This writes all pending changes to disk.
226 The flags which were passed to C<guestfs_aug_init> affect exactly
229 This function returns 0 on success or -1 on error.
231 =head2 guestfs_aug_set
233 int guestfs_aug_set (guestfs_h *handle,
237 Set the value associated with C<path> to C<value>.
239 This function returns 0 on success or -1 on error.
243 char *guestfs_cat (guestfs_h *handle,
246 Return the contents of the file named C<path>.
248 Note that this function cannot correctly handle binary files
249 (specifically, files containing C<\0> character which is treated
250 as end of string). For those you need to use the C<guestfs_read_file>
251 function which has a more complex interface.
253 This function returns a string or NULL on error.
254 I<The caller must free the returned string after use>.
256 Because of the message protocol, there is a transfer limit
257 of somewhere between 2MB and 4MB. To transfer large files you should use
262 int guestfs_chmod (guestfs_h *handle,
266 Change the mode (permissions) of C<path> to C<mode>. Only
267 numeric modes are supported.
269 This function returns 0 on success or -1 on error.
273 int guestfs_chown (guestfs_h *handle,
278 Change the file owner to C<owner> and group to C<group>.
280 Only numeric uid and gid are supported. If you want to use
281 names, you will need to locate and parse the password file
282 yourself (Augeas support makes this relatively easy).
284 This function returns 0 on success or -1 on error.
286 =head2 guestfs_config
288 int guestfs_config (guestfs_h *handle,
289 const char *qemuparam,
290 const char *qemuvalue);
292 This can be used to add arbitrary qemu command line parameters
293 of the form C<-param value>. Actually it's not quite arbitrary - we
294 prevent you from setting some parameters which would interfere with
295 parameters that we use.
297 The first character of C<param> string must be a C<-> (dash).
299 C<value> can be NULL.
301 This function returns 0 on success or -1 on error.
303 =head2 guestfs_exists
305 int guestfs_exists (guestfs_h *handle,
308 This returns C<true> if and only if there is a file, directory
309 (or anything) with the given C<path> name.
311 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
313 This function returns a C truth value on success or -1 on error.
317 char *guestfs_file (guestfs_h *handle,
320 This call uses the standard L<file(1)> command to determine
321 the type or contents of the file. This also works on devices,
322 for example to find out whether a partition contains a filesystem.
324 The exact command which runs is C<file -bsL path>. Note in
325 particular that the filename is not prepended to the output
328 This function returns a string or NULL on error.
329 I<The caller must free the returned string after use>.
331 =head2 guestfs_get_autosync
333 int guestfs_get_autosync (guestfs_h *handle);
335 Get the autosync flag.
337 This function returns a C truth value on success or -1 on error.
339 =head2 guestfs_get_path
341 const char *guestfs_get_path (guestfs_h *handle);
343 Return the current search path.
345 This is always non-NULL. If it wasn't set already, then this will
346 return the default path.
348 This function returns a string or NULL on error.
349 The string is owned by the guest handle and must I<not> be freed.
351 =head2 guestfs_get_verbose
353 int guestfs_get_verbose (guestfs_h *handle);
355 This returns the verbose messages flag.
357 This function returns a C truth value on success or -1 on error.
359 =head2 guestfs_is_dir
361 int guestfs_is_dir (guestfs_h *handle,
364 This returns C<true> if and only if there is a directory
365 with the given C<path> name. Note that it returns false for
366 other objects like files.
368 See also C<guestfs_stat>.
370 This function returns a C truth value on success or -1 on error.
372 =head2 guestfs_is_file
374 int guestfs_is_file (guestfs_h *handle,
377 This returns C<true> if and only if there is a file
378 with the given C<path> name. Note that it returns false for
379 other objects like directories.
381 See also C<guestfs_stat>.
383 This function returns a C truth value on success or -1 on error.
385 =head2 guestfs_kill_subprocess
387 int guestfs_kill_subprocess (guestfs_h *handle);
389 This kills the qemu subprocess. You should never need to call this.
391 This function returns 0 on success or -1 on error.
393 =head2 guestfs_launch
395 int guestfs_launch (guestfs_h *handle);
397 Internally libguestfs is implemented by running a virtual machine
400 You should call this after configuring the handle
401 (eg. adding drives) but before performing any actions.
403 This function returns 0 on success or -1 on error.
405 =head2 guestfs_list_devices
407 char **guestfs_list_devices (guestfs_h *handle);
409 List all the block devices.
411 The full block device names are returned, eg. C</dev/sda>
413 This function returns a NULL-terminated array of strings
414 (like L<environ(3)>), or NULL if there was an error.
415 I<The caller must free the strings and the array after use>.
417 =head2 guestfs_list_partitions
419 char **guestfs_list_partitions (guestfs_h *handle);
421 List all the partitions detected on all block devices.
423 The full partition device names are returned, eg. C</dev/sda1>
425 This does not return logical volumes. For that you will need to
428 This function returns a NULL-terminated array of strings
429 (like L<environ(3)>), or NULL if there was an error.
430 I<The caller must free the strings and the array after use>.
434 char *guestfs_ll (guestfs_h *handle,
435 const char *directory);
437 List the files in C<directory> (relative to the root directory,
438 there is no cwd) in the format of 'ls -la'.
440 This command is mostly useful for interactive sessions. It
441 is I<not> intended that you try to parse the output string.
443 This function returns a string or NULL on error.
444 I<The caller must free the returned string after use>.
448 char **guestfs_ls (guestfs_h *handle,
449 const char *directory);
451 List the files in C<directory> (relative to the root directory,
452 there is no cwd). The '.' and '..' entries are not returned, but
453 hidden files are shown.
455 This command is mostly useful for interactive sessions. Programs
456 should probably use C<guestfs_readdir> instead.
458 This function returns a NULL-terminated array of strings
459 (like L<environ(3)>), or NULL if there was an error.
460 I<The caller must free the strings and the array after use>.
462 =head2 guestfs_lvcreate
464 int guestfs_lvcreate (guestfs_h *handle,
466 const char *volgroup,
469 This creates an LVM volume group called C<logvol>
470 on the volume group C<volgroup>, with C<size> megabytes.
472 This function returns 0 on success or -1 on error.
474 =head2 guestfs_lvm_remove_all
476 int guestfs_lvm_remove_all (guestfs_h *handle);
478 This command removes all LVM logical volumes, volume groups
479 and physical volumes.
481 This function returns 0 on success or -1 on error.
483 B<This command is dangerous. Without careful use you
484 can easily destroy all your data>.
488 char **guestfs_lvs (guestfs_h *handle);
490 List all the logical volumes detected. This is the equivalent
491 of the L<lvs(8)> command.
493 This returns a list of the logical volume device names
494 (eg. C</dev/VolGroup00/LogVol00>).
496 See also C<guestfs_lvs_full>.
498 This function returns a NULL-terminated array of strings
499 (like L<environ(3)>), or NULL if there was an error.
500 I<The caller must free the strings and the array after use>.
502 =head2 guestfs_lvs_full
504 struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
506 List all the logical volumes detected. This is the equivalent
507 of the L<lvs(8)> command. The "full" version includes all fields.
509 This function returns a C<struct guestfs_lvm_lv_list *>.
510 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
514 int guestfs_mkdir (guestfs_h *handle,
517 Create a directory named C<path>.
519 This function returns 0 on success or -1 on error.
521 =head2 guestfs_mkdir_p
523 int guestfs_mkdir_p (guestfs_h *handle,
526 Create a directory named C<path>, creating any parent directories
527 as necessary. This is like the C<mkdir -p> shell command.
529 This function returns 0 on success or -1 on error.
533 int guestfs_mkfs (guestfs_h *handle,
537 This creates a filesystem on C<device> (usually a partition
538 of LVM logical volume). The filesystem type is C<fstype>, for
541 This function returns 0 on success or -1 on error.
545 int guestfs_mount (guestfs_h *handle,
547 const char *mountpoint);
549 Mount a guest disk at a position in the filesystem. Block devices
550 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
551 the guest. If those block devices contain partitions, they will have
552 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
555 The rules are the same as for L<mount(2)>: A filesystem must
556 first be mounted on C</> before others can be mounted. Other
557 filesystems can only be mounted on directories which already
560 The mounted filesystem is writable, if we have sufficient permissions
561 on the underlying device.
563 The filesystem options C<sync> and C<noatime> are set with this
564 call, in order to improve reliability.
566 This function returns 0 on success or -1 on error.
568 =head2 guestfs_mounts
570 char **guestfs_mounts (guestfs_h *handle);
572 This returns the list of currently mounted filesystems. It returns
573 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
575 Some internal mounts are not shown.
577 This function returns a NULL-terminated array of strings
578 (like L<environ(3)>), or NULL if there was an error.
579 I<The caller must free the strings and the array after use>.
581 =head2 guestfs_pvcreate
583 int guestfs_pvcreate (guestfs_h *handle,
586 This creates an LVM physical volume on the named C<device>,
587 where C<device> should usually be a partition name such
590 This function returns 0 on success or -1 on error.
594 char **guestfs_pvs (guestfs_h *handle);
596 List all the physical volumes detected. This is the equivalent
597 of the L<pvs(8)> command.
599 This returns a list of just the device names that contain
600 PVs (eg. C</dev/sda2>).
602 See also C<guestfs_pvs_full>.
604 This function returns a NULL-terminated array of strings
605 (like L<environ(3)>), or NULL if there was an error.
606 I<The caller must free the strings and the array after use>.
608 =head2 guestfs_pvs_full
610 struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
612 List all the physical volumes detected. This is the equivalent
613 of the L<pvs(8)> command. The "full" version includes all fields.
615 This function returns a C<struct guestfs_lvm_pv_list *>.
616 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
618 =head2 guestfs_read_lines
620 char **guestfs_read_lines (guestfs_h *handle,
623 Return the contents of the file named C<path>.
625 The file contents are returned as a list of lines. Trailing
626 C<LF> and C<CRLF> character sequences are I<not> returned.
628 Note that this function cannot correctly handle binary files
629 (specifically, files containing C<\0> character which is treated
630 as end of line). For those you need to use the C<guestfs_read_file>
631 function which has a more complex interface.
633 This function returns a NULL-terminated array of strings
634 (like L<environ(3)>), or NULL if there was an error.
635 I<The caller must free the strings and the array after use>.
639 int guestfs_rm (guestfs_h *handle,
642 Remove the single file C<path>.
644 This function returns 0 on success or -1 on error.
648 int guestfs_rm_rf (guestfs_h *handle,
651 Remove the file or directory C<path>, recursively removing the
652 contents if its a directory. This is like the C<rm -rf> shell
655 This function returns 0 on success or -1 on error.
659 int guestfs_rmdir (guestfs_h *handle,
662 Remove the single directory C<path>.
664 This function returns 0 on success or -1 on error.
666 =head2 guestfs_set_autosync
668 int guestfs_set_autosync (guestfs_h *handle,
671 If C<autosync> is true, this enables autosync. Libguestfs will make a
672 best effort attempt to run C<guestfs_sync> when the handle is closed
673 (also if the program exits without closing handles).
675 This function returns 0 on success or -1 on error.
677 =head2 guestfs_set_path
679 int guestfs_set_path (guestfs_h *handle,
682 Set the path that libguestfs searches for kernel and initrd.img.
684 The default is C<$libdir/guestfs> unless overridden by setting
685 C<LIBGUESTFS_PATH> environment variable.
687 The string C<path> is stashed in the libguestfs handle, so the caller
688 must make sure it remains valid for the lifetime of the handle.
690 Setting C<path> to C<NULL> restores the default path.
692 This function returns 0 on success or -1 on error.
694 =head2 guestfs_set_verbose
696 int guestfs_set_verbose (guestfs_h *handle,
699 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
701 Verbose messages are disabled unless the environment variable
702 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
704 This function returns 0 on success or -1 on error.
706 =head2 guestfs_sfdisk
708 int guestfs_sfdisk (guestfs_h *handle,
713 char * const* const lines);
715 This is a direct interface to the L<sfdisk(8)> program for creating
716 partitions on block devices.
718 C<device> should be a block device, for example C</dev/sda>.
720 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
721 and sectors on the device, which are passed directly to sfdisk as
722 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
723 of these, then the corresponding parameter is omitted. Usually for
724 'large' disks, you can just pass C<0> for these, but for small
725 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
726 out the right geometry and you will need to tell it.
728 C<lines> is a list of lines that we feed to C<sfdisk>. For more
729 information refer to the L<sfdisk(8)> manpage.
731 To create a single partition occupying the whole disk, you would
732 pass C<lines> as a single element list, when the single element being
733 the string C<,> (comma).
735 This function returns 0 on success or -1 on error.
737 B<This command is dangerous. Without careful use you
738 can easily destroy all your data>.
742 int guestfs_sync (guestfs_h *handle);
744 This syncs the disk, so that any writes are flushed through to the
745 underlying disk image.
747 You should always call this if you have modified a disk image, before
750 This function returns 0 on success or -1 on error.
754 int guestfs_touch (guestfs_h *handle,
757 Touch acts like the L<touch(1)> command. It can be used to
758 update the timestamps on a file, or, if the file does not exist,
759 to create a new zero-length file.
761 This function returns 0 on success or -1 on error.
763 =head2 guestfs_umount
765 int guestfs_umount (guestfs_h *handle,
766 const char *pathordevice);
768 This unmounts the given filesystem. The filesystem may be
769 specified either by its mountpoint (path) or the device which
770 contains the filesystem.
772 This function returns 0 on success or -1 on error.
774 =head2 guestfs_umount_all
776 int guestfs_umount_all (guestfs_h *handle);
778 This unmounts all mounted filesystems.
780 Some internal mounts are not unmounted by this call.
782 This function returns 0 on success or -1 on error.
784 =head2 guestfs_vgcreate
786 int guestfs_vgcreate (guestfs_h *handle,
787 const char *volgroup,
788 char * const* const physvols);
790 This creates an LVM volume group called C<volgroup>
791 from the non-empty list of physical volumes C<physvols>.
793 This function returns 0 on success or -1 on error.
797 char **guestfs_vgs (guestfs_h *handle);
799 List all the volumes groups detected. This is the equivalent
800 of the L<vgs(8)> command.
802 This returns a list of just the volume group names that were
803 detected (eg. C<VolGroup00>).
805 See also C<guestfs_vgs_full>.
807 This function returns a NULL-terminated array of strings
808 (like L<environ(3)>), or NULL if there was an error.
809 I<The caller must free the strings and the array after use>.
811 =head2 guestfs_vgs_full
813 struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
815 List all the volumes groups detected. This is the equivalent
816 of the L<vgs(8)> command. The "full" version includes all fields.
818 This function returns a C<struct guestfs_lvm_vg_list *>.
819 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
821 =head2 guestfs_wait_ready
823 int guestfs_wait_ready (guestfs_h *handle);
825 Internally libguestfs is implemented by running a virtual machine
828 You should call this after C<guestfs_launch> to wait for the launch
831 This function returns 0 on success or -1 on error.
833 =head2 guestfs_write_file
835 int guestfs_write_file (guestfs_h *handle,
840 This call creates a file called C<path>. The contents of the
841 file is the string C<content> (which can contain any 8 bit data),
844 As a special case, if C<size> is C<0>
845 then the length is calculated using C<strlen> (so in this case
846 the content cannot contain embedded ASCII NULs).
848 This function returns 0 on success or -1 on error.
850 Because of the message protocol, there is a transfer limit
851 of somewhere between 2MB and 4MB. To transfer large files you should use