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 or NULL if there was an error.
63 I<The caller must call C<guestfs_free_int_bool> after use>.
65 =head2 guestfs_aug_defvar
67 int guestfs_aug_defvar (guestfs_h *handle,
71 Defines an Augeas variable C<name> whose value is the result
72 of evaluating C<expr>. If C<expr> is NULL, then C<name> is
75 On success this returns the number of nodes in C<expr>, or
76 C<0> if C<expr> evaluates to something which is not a nodeset.
78 On error this function returns -1.
80 =head2 guestfs_aug_get
82 char *guestfs_aug_get (guestfs_h *handle,
85 Look up the value associated with C<path>. If C<path>
86 matches exactly one node, the C<value> is returned.
88 This function returns a string, or NULL on error.
89 I<The caller must free the returned string after use>.
91 =head2 guestfs_aug_init
93 int guestfs_aug_init (guestfs_h *handle,
97 Create a new Augeas handle for editing configuration files.
98 If there was any previous Augeas handle associated with this
99 guestfs session, then it is closed.
101 You must call this before using any other C<guestfs_aug_*>
104 C<root> is the filesystem root. C<root> must not be NULL,
107 The flags are the same as the flags defined in
108 E<lt>augeas.hE<gt>, the logical I<or> of the following
113 =item C<AUG_SAVE_BACKUP> = 1
115 Keep the original file with a C<.augsave> extension.
117 =item C<AUG_SAVE_NEWFILE> = 2
119 Save changes into a file with extension C<.augnew>, and
120 do not overwrite original. Overrides C<AUG_SAVE_BACKUP>.
122 =item C<AUG_TYPE_CHECK> = 4
124 Typecheck lenses (can be expensive).
126 =item C<AUG_NO_STDINC> = 8
128 Do not use standard load path for modules.
130 =item C<AUG_SAVE_NOOP> = 16
132 Make save a no-op, just record what would have been changed.
134 =item C<AUG_NO_LOAD> = 32
136 Do not load the tree in C<guestfs_aug_init>.
140 To close the handle, you can call C<guestfs_aug_close>.
142 To find out more about Augeas, see L<http://augeas.net/>.
144 This function returns 0 on success or -1 on error.
146 =head2 guestfs_aug_insert
148 int guestfs_aug_insert (guestfs_h *handle,
153 Create a new sibling C<label> for C<path>, inserting it into
154 the tree before or after C<path> (depending on the boolean
157 C<path> must match exactly one existing node in the tree, and
158 C<label> must be a label, ie. not contain C</>, C<*> or end
159 with a bracketed index C<[N]>.
161 This function returns 0 on success or -1 on error.
163 =head2 guestfs_aug_load
165 int guestfs_aug_load (guestfs_h *handle);
167 Load files into the tree.
169 See C<aug_load> in the Augeas documentation for the full gory
172 This function returns 0 on success or -1 on error.
174 =head2 guestfs_aug_ls
176 char **guestfs_aug_ls (guestfs_h *handle,
179 This is just a shortcut for listing C<guestfs_aug_match>
180 C<path/*> and sorting the resulting nodes into alphabetical order.
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_match
188 char **guestfs_aug_match (guestfs_h *handle,
191 Returns a list of paths which match the path expression C<path>.
192 The returned paths are sufficiently qualified so that they match
193 exactly one node in the current tree.
195 This function returns a NULL-terminated array of strings
196 (like L<environ(3)>), or NULL if there was an error.
197 I<The caller must free the strings and the array after use>.
199 =head2 guestfs_aug_mv
201 int guestfs_aug_mv (guestfs_h *handle,
205 Move the node C<src> to C<dest>. C<src> must match exactly
206 one node. C<dest> is overwritten if it exists.
208 This function returns 0 on success or -1 on error.
210 =head2 guestfs_aug_rm
212 int guestfs_aug_rm (guestfs_h *handle,
215 Remove C<path> and all of its children.
217 On success this returns the number of entries which were removed.
219 On error this function returns -1.
221 =head2 guestfs_aug_save
223 int guestfs_aug_save (guestfs_h *handle);
225 This writes all pending changes to disk.
227 The flags which were passed to C<guestfs_aug_init> affect exactly
230 This function returns 0 on success or -1 on error.
232 =head2 guestfs_aug_set
234 int guestfs_aug_set (guestfs_h *handle,
238 Set the value associated with C<path> to C<value>.
240 This function returns 0 on success or -1 on error.
242 =head2 guestfs_blockdev_flushbufs
244 int guestfs_blockdev_flushbufs (guestfs_h *handle,
247 This tells the kernel to flush internal buffers associated
250 This uses the L<blockdev(8)> command.
252 This function returns 0 on success or -1 on error.
254 =head2 guestfs_blockdev_getbsz
256 int guestfs_blockdev_getbsz (guestfs_h *handle,
259 This returns the block size of a device.
261 (Note this is different from both I<size in blocks> and
262 I<filesystem block size>).
264 This uses the L<blockdev(8)> command.
266 On error this function returns -1.
268 =head2 guestfs_blockdev_getro
270 int guestfs_blockdev_getro (guestfs_h *handle,
273 Returns a boolean indicating if the block device is read-only
274 (true if read-only, false if not).
276 This uses the L<blockdev(8)> command.
278 This function returns a C truth value on success or -1 on error.
280 =head2 guestfs_blockdev_getsize64
282 int64_t guestfs_blockdev_getsize64 (guestfs_h *handle,
285 This returns the size of the device in bytes.
287 See also C<guestfs_blockdev_getsz>.
289 This uses the L<blockdev(8)> command.
291 On error this function returns -1.
293 =head2 guestfs_blockdev_getss
295 int guestfs_blockdev_getss (guestfs_h *handle,
298 This returns the size of sectors on a block device.
299 Usually 512, but can be larger for modern devices.
301 (Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
304 This uses the L<blockdev(8)> command.
306 On error this function returns -1.
308 =head2 guestfs_blockdev_getsz
310 int64_t guestfs_blockdev_getsz (guestfs_h *handle,
313 This returns the size of the device in units of 512-byte sectors
314 (even if the sectorsize isn't 512 bytes ... weird).
316 See also C<guestfs_blockdev_getss> for the real sector size of
317 the device, and C<guestfs_blockdev_getsize64> for the more
318 useful I<size in bytes>.
320 This uses the L<blockdev(8)> command.
322 On error this function returns -1.
324 =head2 guestfs_blockdev_rereadpt
326 int guestfs_blockdev_rereadpt (guestfs_h *handle,
329 Reread the partition table on C<device>.
331 This uses the L<blockdev(8)> command.
333 This function returns 0 on success or -1 on error.
335 =head2 guestfs_blockdev_setbsz
337 int guestfs_blockdev_setbsz (guestfs_h *handle,
341 This sets the block size of a device.
343 (Note this is different from both I<size in blocks> and
344 I<filesystem block size>).
346 This uses the L<blockdev(8)> command.
348 This function returns 0 on success or -1 on error.
350 =head2 guestfs_blockdev_setro
352 int guestfs_blockdev_setro (guestfs_h *handle,
355 Sets the block device named C<device> to read-only.
357 This uses the L<blockdev(8)> command.
359 This function returns 0 on success or -1 on error.
361 =head2 guestfs_blockdev_setrw
363 int guestfs_blockdev_setrw (guestfs_h *handle,
366 Sets the block device named C<device> to read-write.
368 This uses the L<blockdev(8)> command.
370 This function returns 0 on success or -1 on error.
374 char *guestfs_cat (guestfs_h *handle,
377 Return the contents of the file named C<path>.
379 Note that this function cannot correctly handle binary files
380 (specifically, files containing C<\0> character which is treated
381 as end of string). For those you need to use the C<guestfs_download>
382 function which has a more complex interface.
384 This function returns a string, or NULL on error.
385 I<The caller must free the returned string after use>.
387 Because of the message protocol, there is a transfer limit
388 of somewhere between 2MB and 4MB. To transfer large files you should use
391 =head2 guestfs_checksum
393 char *guestfs_checksum (guestfs_h *handle,
394 const char *csumtype,
397 This call computes the MD5, SHAx or CRC checksum of the
400 The type of checksum to compute is given by the C<csumtype>
401 parameter which must have one of the following values:
407 Compute the cyclic redundancy check (CRC) specified by POSIX
408 for the C<cksum> command.
412 Compute the MD5 hash (using the C<md5sum> program).
416 Compute the SHA1 hash (using the C<sha1sum> program).
420 Compute the SHA224 hash (using the C<sha224sum> program).
424 Compute the SHA256 hash (using the C<sha256sum> program).
428 Compute the SHA384 hash (using the C<sha384sum> program).
432 Compute the SHA512 hash (using the C<sha512sum> program).
436 The checksum is returned as a printable string.
438 This function returns a string, or NULL on error.
439 I<The caller must free the returned string after use>.
443 int guestfs_chmod (guestfs_h *handle,
447 Change the mode (permissions) of C<path> to C<mode>. Only
448 numeric modes are supported.
450 This function returns 0 on success or -1 on error.
454 int guestfs_chown (guestfs_h *handle,
459 Change the file owner to C<owner> and group to C<group>.
461 Only numeric uid and gid are supported. If you want to use
462 names, you will need to locate and parse the password file
463 yourself (Augeas support makes this relatively easy).
465 This function returns 0 on success or -1 on error.
467 =head2 guestfs_command
469 char *guestfs_command (guestfs_h *handle,
470 char * const* const arguments);
472 This call runs a command from the guest filesystem. The
473 filesystem must be mounted, and must contain a compatible
474 operating system (ie. something Linux, with the same
475 or compatible processor architecture).
477 The single parameter is an argv-style list of arguments.
478 The first element is the name of the program to run.
479 Subsequent elements are parameters. The list must be
480 non-empty (ie. must contain a program name).
482 The C<$PATH> environment variable will contain at least
483 C</usr/bin> and C</bin>. If you require a program from
484 another location, you should provide the full path in the
487 Shared libraries and data files required by the program
488 must be available on filesystems which are mounted in the
489 correct places. It is the caller's responsibility to ensure
490 all filesystems that are needed are mounted at the right
493 This function returns a string, or NULL on error.
494 I<The caller must free the returned string after use>.
496 =head2 guestfs_command_lines
498 char **guestfs_command_lines (guestfs_h *handle,
499 char * const* const arguments);
501 This is the same as C<guestfs_command>, but splits the
502 result into a list of lines.
504 This function returns a NULL-terminated array of strings
505 (like L<environ(3)>), or NULL if there was an error.
506 I<The caller must free the strings and the array after use>.
508 =head2 guestfs_config
510 int guestfs_config (guestfs_h *handle,
511 const char *qemuparam,
512 const char *qemuvalue);
514 This can be used to add arbitrary qemu command line parameters
515 of the form C<-param value>. Actually it's not quite arbitrary - we
516 prevent you from setting some parameters which would interfere with
517 parameters that we use.
519 The first character of C<param> string must be a C<-> (dash).
521 C<value> can be NULL.
523 This function returns 0 on success or -1 on error.
527 int guestfs_cp (guestfs_h *handle,
531 This copies a file from C<src> to C<dest> where C<dest> is
532 either a destination filename or destination directory.
534 This function returns 0 on success or -1 on error.
538 int guestfs_cp_a (guestfs_h *handle,
542 This copies a file or directory from C<src> to C<dest>
543 recursively using the C<cp -a> command.
545 This function returns 0 on success or -1 on error.
549 char *guestfs_debug (guestfs_h *handle,
551 char * const* const extraargs);
553 The C<guestfs_debug> command exposes some internals of
554 C<guestfsd> (the guestfs daemon) that runs inside the
557 There is no comprehensive help for this command. You have
558 to look at the file C<daemon/debug.c> in the libguestfs source
559 to find out what you can do.
561 This function returns a string, or NULL on error.
562 I<The caller must free the returned string after use>.
566 char *guestfs_dmesg (guestfs_h *handle);
568 This returns the kernel messages (C<dmesg> output) from
569 the guest kernel. This is sometimes useful for extended
570 debugging of problems.
572 Another way to get the same information is to enable
573 verbose messages with C<guestfs_set_verbose> or by setting
574 the environment variable C<LIBGUESTFS_DEBUG=1> before
577 This function returns a string, or NULL on error.
578 I<The caller must free the returned string after use>.
580 =head2 guestfs_download
582 int guestfs_download (guestfs_h *handle,
583 const char *remotefilename,
584 const char *filename);
586 Download file C<remotefilename> and save it as C<filename>
587 on the local machine.
589 C<filename> can also be a named pipe.
591 See also C<guestfs_upload>, C<guestfs_cat>.
593 This function returns 0 on success or -1 on error.
595 =head2 guestfs_drop_caches
597 int guestfs_drop_caches (guestfs_h *handle,
600 This instructs the guest kernel to drop its page cache,
601 and/or dentries and inode caches. The parameter C<whattodrop>
602 tells the kernel what precisely to drop, see
603 L<http://linux-mm.org/Drop_Caches>
605 Setting C<whattodrop> to 3 should drop everything.
607 This automatically calls L<sync(2)> before the operation,
608 so that the maximum guest memory is freed.
610 This function returns 0 on success or -1 on error.
614 int guestfs_equal (guestfs_h *handle,
618 This compares the two files C<file1> and C<file2> and returns
619 true if their content is exactly equal, or false otherwise.
621 The external L<cmp(1)> program is used for the comparison.
623 This function returns a C truth value on success or -1 on error.
625 =head2 guestfs_exists
627 int guestfs_exists (guestfs_h *handle,
630 This returns C<true> if and only if there is a file, directory
631 (or anything) with the given C<path> name.
633 See also C<guestfs_is_file>, C<guestfs_is_dir>, C<guestfs_stat>.
635 This function returns a C truth value on success or -1 on error.
639 char *guestfs_file (guestfs_h *handle,
642 This call uses the standard L<file(1)> command to determine
643 the type or contents of the file. This also works on devices,
644 for example to find out whether a partition contains a filesystem.
646 The exact command which runs is C<file -bsL path>. Note in
647 particular that the filename is not prepended to the output
650 This function returns a string, or NULL on error.
651 I<The caller must free the returned string after use>.
655 int guestfs_fsck (guestfs_h *handle,
659 This runs the filesystem checker (fsck) on C<device> which
660 should have filesystem type C<fstype>.
662 The returned integer is the status. See L<fsck(8)> for the
663 list of status codes from C<fsck>.
671 Multiple status codes can be summed together.
675 A non-zero return code can mean "success", for example if
676 errors have been corrected on the filesystem.
680 Checking or repairing NTFS volumes is not supported
685 This command is entirely equivalent to running C<fsck -a -t fstype device>.
687 On error this function returns -1.
689 =head2 guestfs_get_autosync
691 int guestfs_get_autosync (guestfs_h *handle);
693 Get the autosync flag.
695 This function returns a C truth value on success or -1 on error.
697 =head2 guestfs_get_e2label
699 char *guestfs_get_e2label (guestfs_h *handle,
702 This returns the ext2/3/4 filesystem label of the filesystem on
705 This function returns a string, or NULL on error.
706 I<The caller must free the returned string after use>.
708 =head2 guestfs_get_e2uuid
710 char *guestfs_get_e2uuid (guestfs_h *handle,
713 This returns the ext2/3/4 filesystem UUID of the filesystem on
716 This function returns a string, or NULL on error.
717 I<The caller must free the returned string after use>.
719 =head2 guestfs_get_path
721 const char *guestfs_get_path (guestfs_h *handle);
723 Return the current search path.
725 This is always non-NULL. If it wasn't set already, then this will
726 return the default path.
728 This function returns a string, or NULL on error.
729 The string is owned by the guest handle and must I<not> be freed.
731 =head2 guestfs_get_qemu
733 const char *guestfs_get_qemu (guestfs_h *handle);
735 Return the current qemu binary.
737 This is always non-NULL. If it wasn't set already, then this will
738 return the default qemu binary name.
740 This function returns a string, or NULL on error.
741 The string is owned by the guest handle and must I<not> be freed.
743 =head2 guestfs_get_state
745 int guestfs_get_state (guestfs_h *handle);
747 This returns the current state as an opaque integer. This is
748 only useful for printing debug and internal error messages.
750 For more information on states, see L<guestfs(3)>.
752 On error this function returns -1.
754 =head2 guestfs_get_verbose
756 int guestfs_get_verbose (guestfs_h *handle);
758 This returns the verbose messages flag.
760 This function returns a C truth value on success or -1 on error.
762 =head2 guestfs_grub_install
764 int guestfs_grub_install (guestfs_h *handle,
768 This command installs GRUB (the Grand Unified Bootloader) on
769 C<device>, with the root directory being C<root>.
771 This function returns 0 on success or -1 on error.
773 =head2 guestfs_is_busy
775 int guestfs_is_busy (guestfs_h *handle);
777 This returns true iff this handle is busy processing a command
778 (in the C<BUSY> state).
780 For more information on states, see L<guestfs(3)>.
782 This function returns a C truth value on success or -1 on error.
784 =head2 guestfs_is_config
786 int guestfs_is_config (guestfs_h *handle);
788 This returns true iff this handle is being configured
789 (in the C<CONFIG> state).
791 For more information on states, see L<guestfs(3)>.
793 This function returns a C truth value on success or -1 on error.
795 =head2 guestfs_is_dir
797 int guestfs_is_dir (guestfs_h *handle,
800 This returns C<true> if and only if there is a directory
801 with the given C<path> name. Note that it returns false for
802 other objects like files.
804 See also C<guestfs_stat>.
806 This function returns a C truth value on success or -1 on error.
808 =head2 guestfs_is_file
810 int guestfs_is_file (guestfs_h *handle,
813 This returns C<true> if and only if there is a file
814 with the given C<path> name. Note that it returns false for
815 other objects like directories.
817 See also C<guestfs_stat>.
819 This function returns a C truth value on success or -1 on error.
821 =head2 guestfs_is_launching
823 int guestfs_is_launching (guestfs_h *handle);
825 This returns true iff this handle is launching the subprocess
826 (in the C<LAUNCHING> state).
828 For more information on states, see L<guestfs(3)>.
830 This function returns a C truth value on success or -1 on error.
832 =head2 guestfs_is_ready
834 int guestfs_is_ready (guestfs_h *handle);
836 This returns true iff this handle is ready to accept commands
837 (in the C<READY> state).
839 For more information on states, see L<guestfs(3)>.
841 This function returns a C truth value on success or -1 on error.
843 =head2 guestfs_kill_subprocess
845 int guestfs_kill_subprocess (guestfs_h *handle);
847 This kills the qemu subprocess. You should never need to call this.
849 This function returns 0 on success or -1 on error.
851 =head2 guestfs_launch
853 int guestfs_launch (guestfs_h *handle);
855 Internally libguestfs is implemented by running a virtual machine
858 You should call this after configuring the handle
859 (eg. adding drives) but before performing any actions.
861 This function returns 0 on success or -1 on error.
863 =head2 guestfs_list_devices
865 char **guestfs_list_devices (guestfs_h *handle);
867 List all the block devices.
869 The full block device names are returned, eg. C</dev/sda>
871 This function returns a NULL-terminated array of strings
872 (like L<environ(3)>), or NULL if there was an error.
873 I<The caller must free the strings and the array after use>.
875 =head2 guestfs_list_partitions
877 char **guestfs_list_partitions (guestfs_h *handle);
879 List all the partitions detected on all block devices.
881 The full partition device names are returned, eg. C</dev/sda1>
883 This does not return logical volumes. For that you will need to
886 This function returns a NULL-terminated array of strings
887 (like L<environ(3)>), or NULL if there was an error.
888 I<The caller must free the strings and the array after use>.
892 char *guestfs_ll (guestfs_h *handle,
893 const char *directory);
895 List the files in C<directory> (relative to the root directory,
896 there is no cwd) in the format of 'ls -la'.
898 This command is mostly useful for interactive sessions. It
899 is I<not> intended that you try to parse the output string.
901 This function returns a string, or NULL on error.
902 I<The caller must free the returned string after use>.
906 char **guestfs_ls (guestfs_h *handle,
907 const char *directory);
909 List the files in C<directory> (relative to the root directory,
910 there is no cwd). The '.' and '..' entries are not returned, but
911 hidden files are shown.
913 This command is mostly useful for interactive sessions. Programs
914 should probably use C<guestfs_readdir> instead.
916 This function returns a NULL-terminated array of strings
917 (like L<environ(3)>), or NULL if there was an error.
918 I<The caller must free the strings and the array after use>.
922 struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
925 Returns file information for the given C<path>.
927 This is the same as C<guestfs_stat> except that if C<path>
928 is a symbolic link, then the link is stat-ed, not the file it
931 This is the same as the C<lstat(2)> system call.
933 This function returns a C<struct guestfs_stat *>
934 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
935 or NULL if there was an error.
936 I<The caller must call C<free> after use>.
938 =head2 guestfs_lvcreate
940 int guestfs_lvcreate (guestfs_h *handle,
942 const char *volgroup,
945 This creates an LVM volume group called C<logvol>
946 on the volume group C<volgroup>, with C<size> megabytes.
948 This function returns 0 on success or -1 on error.
950 =head2 guestfs_lvm_remove_all
952 int guestfs_lvm_remove_all (guestfs_h *handle);
954 This command removes all LVM logical volumes, volume groups
955 and physical volumes.
957 This function returns 0 on success or -1 on error.
959 B<This command is dangerous. Without careful use you
960 can easily destroy all your data>.
962 =head2 guestfs_lvremove
964 int guestfs_lvremove (guestfs_h *handle,
967 Remove an LVM logical volume C<device>, where C<device> is
968 the path to the LV, such as C</dev/VG/LV>.
970 You can also remove all LVs in a volume group by specifying
971 the VG name, C</dev/VG>.
973 This function returns 0 on success or -1 on error.
977 char **guestfs_lvs (guestfs_h *handle);
979 List all the logical volumes detected. This is the equivalent
980 of the L<lvs(8)> command.
982 This returns a list of the logical volume device names
983 (eg. C</dev/VolGroup00/LogVol00>).
985 See also C<guestfs_lvs_full>.
987 This function returns a NULL-terminated array of strings
988 (like L<environ(3)>), or NULL if there was an error.
989 I<The caller must free the strings and the array after use>.
991 =head2 guestfs_lvs_full
993 struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
995 List all the logical volumes detected. This is the equivalent
996 of the L<lvs(8)> command. The "full" version includes all fields.
998 This function returns a C<struct guestfs_lvm_lv_list *>
999 (see E<lt>guestfs-structs.hE<gt>),
1000 or NULL if there was an error.
1001 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
1003 =head2 guestfs_mkdir
1005 int guestfs_mkdir (guestfs_h *handle,
1008 Create a directory named C<path>.
1010 This function returns 0 on success or -1 on error.
1012 =head2 guestfs_mkdir_p
1014 int guestfs_mkdir_p (guestfs_h *handle,
1017 Create a directory named C<path>, creating any parent directories
1018 as necessary. This is like the C<mkdir -p> shell command.
1020 This function returns 0 on success or -1 on error.
1024 int guestfs_mkfs (guestfs_h *handle,
1026 const char *device);
1028 This creates a filesystem on C<device> (usually a partition
1029 or LVM logical volume). The filesystem type is C<fstype>, for
1032 This function returns 0 on success or -1 on error.
1034 =head2 guestfs_mount
1036 int guestfs_mount (guestfs_h *handle,
1038 const char *mountpoint);
1040 Mount a guest disk at a position in the filesystem. Block devices
1041 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
1042 the guest. If those block devices contain partitions, they will have
1043 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
1046 The rules are the same as for L<mount(2)>: A filesystem must
1047 first be mounted on C</> before others can be mounted. Other
1048 filesystems can only be mounted on directories which already
1051 The mounted filesystem is writable, if we have sufficient permissions
1052 on the underlying device.
1054 The filesystem options C<sync> and C<noatime> are set with this
1055 call, in order to improve reliability.
1057 This function returns 0 on success or -1 on error.
1059 =head2 guestfs_mount_options
1061 int guestfs_mount_options (guestfs_h *handle,
1062 const char *options,
1064 const char *mountpoint);
1066 This is the same as the C<guestfs_mount> command, but it
1067 allows you to set the mount options as for the
1068 L<mount(8)> I<-o> flag.
1070 This function returns 0 on success or -1 on error.
1072 =head2 guestfs_mount_ro
1074 int guestfs_mount_ro (guestfs_h *handle,
1076 const char *mountpoint);
1078 This is the same as the C<guestfs_mount> command, but it
1079 mounts the filesystem with the read-only (I<-o ro>) flag.
1081 This function returns 0 on success or -1 on error.
1083 =head2 guestfs_mount_vfs
1085 int guestfs_mount_vfs (guestfs_h *handle,
1086 const char *options,
1087 const char *vfstype,
1089 const char *mountpoint);
1091 This is the same as the C<guestfs_mount> command, but it
1092 allows you to set both the mount options and the vfstype
1093 as for the L<mount(8)> I<-o> and I<-t> flags.
1095 This function returns 0 on success or -1 on error.
1097 =head2 guestfs_mounts
1099 char **guestfs_mounts (guestfs_h *handle);
1101 This returns the list of currently mounted filesystems. It returns
1102 the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
1104 Some internal mounts are not shown.
1106 This function returns a NULL-terminated array of strings
1107 (like L<environ(3)>), or NULL if there was an error.
1108 I<The caller must free the strings and the array after use>.
1112 int guestfs_mv (guestfs_h *handle,
1116 This moves a file from C<src> to C<dest> where C<dest> is
1117 either a destination filename or destination directory.
1119 This function returns 0 on success or -1 on error.
1121 =head2 guestfs_ping_daemon
1123 int guestfs_ping_daemon (guestfs_h *handle);
1125 This is a test probe into the guestfs daemon running inside
1126 the qemu subprocess. Calling this function checks that the
1127 daemon responds to the ping message, without affecting the daemon
1128 or attached block device(s) in any other way.
1130 This function returns 0 on success or -1 on error.
1132 =head2 guestfs_pvcreate
1134 int guestfs_pvcreate (guestfs_h *handle,
1135 const char *device);
1137 This creates an LVM physical volume on the named C<device>,
1138 where C<device> should usually be a partition name such
1141 This function returns 0 on success or -1 on error.
1143 =head2 guestfs_pvremove
1145 int guestfs_pvremove (guestfs_h *handle,
1146 const char *device);
1148 This wipes a physical volume C<device> so that LVM will no longer
1151 The implementation uses the C<pvremove> command which refuses to
1152 wipe physical volumes that contain any volume groups, so you have
1153 to remove those first.
1155 This function returns 0 on success or -1 on error.
1159 char **guestfs_pvs (guestfs_h *handle);
1161 List all the physical volumes detected. This is the equivalent
1162 of the L<pvs(8)> command.
1164 This returns a list of just the device names that contain
1165 PVs (eg. C</dev/sda2>).
1167 See also C<guestfs_pvs_full>.
1169 This function returns a NULL-terminated array of strings
1170 (like L<environ(3)>), or NULL if there was an error.
1171 I<The caller must free the strings and the array after use>.
1173 =head2 guestfs_pvs_full
1175 struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
1177 List all the physical volumes detected. This is the equivalent
1178 of the L<pvs(8)> command. The "full" version includes all fields.
1180 This function returns a C<struct guestfs_lvm_pv_list *>
1181 (see E<lt>guestfs-structs.hE<gt>),
1182 or NULL if there was an error.
1183 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
1185 =head2 guestfs_read_lines
1187 char **guestfs_read_lines (guestfs_h *handle,
1190 Return the contents of the file named C<path>.
1192 The file contents are returned as a list of lines. Trailing
1193 C<LF> and C<CRLF> character sequences are I<not> returned.
1195 Note that this function cannot correctly handle binary files
1196 (specifically, files containing C<\0> character which is treated
1197 as end of line). For those you need to use the C<guestfs_read_file>
1198 function which has a more complex interface.
1200 This function returns a NULL-terminated array of strings
1201 (like L<environ(3)>), or NULL if there was an error.
1202 I<The caller must free the strings and the array after use>.
1206 int guestfs_rm (guestfs_h *handle,
1209 Remove the single file C<path>.
1211 This function returns 0 on success or -1 on error.
1213 =head2 guestfs_rm_rf
1215 int guestfs_rm_rf (guestfs_h *handle,
1218 Remove the file or directory C<path>, recursively removing the
1219 contents if its a directory. This is like the C<rm -rf> shell
1222 This function returns 0 on success or -1 on error.
1224 =head2 guestfs_rmdir
1226 int guestfs_rmdir (guestfs_h *handle,
1229 Remove the single directory C<path>.
1231 This function returns 0 on success or -1 on error.
1233 =head2 guestfs_set_autosync
1235 int guestfs_set_autosync (guestfs_h *handle,
1238 If C<autosync> is true, this enables autosync. Libguestfs will make a
1239 best effort attempt to run C<guestfs_umount_all> followed by
1240 C<guestfs_sync> when the handle is closed
1241 (also if the program exits without closing handles).
1243 This is disabled by default (except in guestfish where it is
1244 enabled by default).
1246 This function returns 0 on success or -1 on error.
1248 =head2 guestfs_set_busy
1250 int guestfs_set_busy (guestfs_h *handle);
1252 This sets the state to C<BUSY>. This is only used when implementing
1253 actions using the low-level API.
1255 For more information on states, see L<guestfs(3)>.
1257 This function returns 0 on success or -1 on error.
1259 =head2 guestfs_set_e2label
1261 int guestfs_set_e2label (guestfs_h *handle,
1265 This sets the ext2/3/4 filesystem label of the filesystem on
1266 C<device> to C<label>. Filesystem labels are limited to
1269 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
1270 to return the existing label on a filesystem.
1272 This function returns 0 on success or -1 on error.
1274 =head2 guestfs_set_e2uuid
1276 int guestfs_set_e2uuid (guestfs_h *handle,
1280 This sets the ext2/3/4 filesystem UUID of the filesystem on
1281 C<device> to C<uuid>. The format of the UUID and alternatives
1282 such as C<clear>, C<random> and C<time> are described in the
1283 L<tune2fs(8)> manpage.
1285 You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
1286 to return the existing UUID of a filesystem.
1288 This function returns 0 on success or -1 on error.
1290 =head2 guestfs_set_path
1292 int guestfs_set_path (guestfs_h *handle,
1295 Set the path that libguestfs searches for kernel and initrd.img.
1297 The default is C<$libdir/guestfs> unless overridden by setting
1298 C<LIBGUESTFS_PATH> environment variable.
1300 The string C<path> is stashed in the libguestfs handle, so the caller
1301 must make sure it remains valid for the lifetime of the handle.
1303 Setting C<path> to C<NULL> restores the default path.
1305 This function returns 0 on success or -1 on error.
1307 =head2 guestfs_set_qemu
1309 int guestfs_set_qemu (guestfs_h *handle,
1312 Set the qemu binary that we will use.
1314 The default is chosen when the library was compiled by the
1317 You can also override this by setting the C<LIBGUESTFS_QEMU>
1318 environment variable.
1320 The string C<qemu> is stashed in the libguestfs handle, so the caller
1321 must make sure it remains valid for the lifetime of the handle.
1323 Setting C<qemu> to C<NULL> restores the default qemu binary.
1325 This function returns 0 on success or -1 on error.
1327 =head2 guestfs_set_ready
1329 int guestfs_set_ready (guestfs_h *handle);
1331 This sets the state to C<READY>. This is only used when implementing
1332 actions using the low-level API.
1334 For more information on states, see L<guestfs(3)>.
1336 This function returns 0 on success or -1 on error.
1338 =head2 guestfs_set_verbose
1340 int guestfs_set_verbose (guestfs_h *handle,
1343 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
1345 Verbose messages are disabled unless the environment variable
1346 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
1348 This function returns 0 on success or -1 on error.
1350 =head2 guestfs_sfdisk
1352 int guestfs_sfdisk (guestfs_h *handle,
1357 char * const* const lines);
1359 This is a direct interface to the L<sfdisk(8)> program for creating
1360 partitions on block devices.
1362 C<device> should be a block device, for example C</dev/sda>.
1364 C<cyls>, C<heads> and C<sectors> are the number of cylinders, heads
1365 and sectors on the device, which are passed directly to sfdisk as
1366 the I<-C>, I<-H> and I<-S> parameters. If you pass C<0> for any
1367 of these, then the corresponding parameter is omitted. Usually for
1368 'large' disks, you can just pass C<0> for these, but for small
1369 (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work
1370 out the right geometry and you will need to tell it.
1372 C<lines> is a list of lines that we feed to C<sfdisk>. For more
1373 information refer to the L<sfdisk(8)> manpage.
1375 To create a single partition occupying the whole disk, you would
1376 pass C<lines> as a single element list, when the single element being
1377 the string C<,> (comma).
1379 This function returns 0 on success or -1 on error.
1381 B<This command is dangerous. Without careful use you
1382 can easily destroy all your data>.
1386 struct guestfs_stat *guestfs_stat (guestfs_h *handle,
1389 Returns file information for the given C<path>.
1391 This is the same as the C<stat(2)> system call.
1393 This function returns a C<struct guestfs_stat *>
1394 (see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
1395 or NULL if there was an error.
1396 I<The caller must call C<free> after use>.
1398 =head2 guestfs_statvfs
1400 struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
1403 Returns file system statistics for any mounted file system.
1404 C<path> should be a file or directory in the mounted file system
1405 (typically it is the mount point itself, but it doesn't need to be).
1407 This is the same as the C<statvfs(2)> system call.
1409 This function returns a C<struct guestfs_statvfs *>
1410 (see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
1411 or NULL if there was an error.
1412 I<The caller must call C<free> after use>.
1416 int guestfs_sync (guestfs_h *handle);
1418 This syncs the disk, so that any writes are flushed through to the
1419 underlying disk image.
1421 You should always call this if you have modified a disk image, before
1424 This function returns 0 on success or -1 on error.
1426 =head2 guestfs_tar_in
1428 int guestfs_tar_in (guestfs_h *handle,
1429 const char *tarfile,
1430 const char *directory);
1432 This command uploads and unpacks local file C<tarfile> (an
1433 I<uncompressed> tar file) into C<directory>.
1435 To upload a compressed tarball, use C<guestfs_tgz_in>.
1437 This function returns 0 on success or -1 on error.
1439 =head2 guestfs_tar_out
1441 int guestfs_tar_out (guestfs_h *handle,
1442 const char *directory,
1443 const char *tarfile);
1445 This command packs the contents of C<directory> and downloads
1446 it to local file C<tarfile>.
1448 To download a compressed tarball, use C<guestfs_tgz_out>.
1450 This function returns 0 on success or -1 on error.
1452 =head2 guestfs_tgz_in
1454 int guestfs_tgz_in (guestfs_h *handle,
1455 const char *tarball,
1456 const char *directory);
1458 This command uploads and unpacks local file C<tarball> (a
1459 I<gzip compressed> tar file) into C<directory>.
1461 To upload an uncompressed tarball, use C<guestfs_tar_in>.
1463 This function returns 0 on success or -1 on error.
1465 =head2 guestfs_tgz_out
1467 int guestfs_tgz_out (guestfs_h *handle,
1468 const char *directory,
1469 const char *tarball);
1471 This command packs the contents of C<directory> and downloads
1472 it to local file C<tarball>.
1474 To download an uncompressed tarball, use C<guestfs_tar_out>.
1476 This function returns 0 on success or -1 on error.
1478 =head2 guestfs_touch
1480 int guestfs_touch (guestfs_h *handle,
1483 Touch acts like the L<touch(1)> command. It can be used to
1484 update the timestamps on a file, or, if the file does not exist,
1485 to create a new zero-length file.
1487 This function returns 0 on success or -1 on error.
1489 =head2 guestfs_tune2fs_l
1491 char **guestfs_tune2fs_l (guestfs_h *handle,
1492 const char *device);
1494 This returns the contents of the ext2, ext3 or ext4 filesystem
1495 superblock on C<device>.
1497 It is the same as running C<tune2fs -l device>. See L<tune2fs(8)>
1498 manpage for more details. The list of fields returned isn't
1499 clearly defined, and depends on both the version of C<tune2fs>
1500 that libguestfs was built against, and the filesystem itself.
1502 This function returns a NULL-terminated array of
1503 strings, or NULL if there was an error.
1504 The array of strings will always have length C<2n+1>, where
1505 C<n> keys and values alternate, followed by the trailing NULL entry.
1506 I<The caller must free the strings and the array after use>.
1508 =head2 guestfs_umount
1510 int guestfs_umount (guestfs_h *handle,
1511 const char *pathordevice);
1513 This unmounts the given filesystem. The filesystem may be
1514 specified either by its mountpoint (path) or the device which
1515 contains the filesystem.
1517 This function returns 0 on success or -1 on error.
1519 =head2 guestfs_umount_all
1521 int guestfs_umount_all (guestfs_h *handle);
1523 This unmounts all mounted filesystems.
1525 Some internal mounts are not unmounted by this call.
1527 This function returns 0 on success or -1 on error.
1529 =head2 guestfs_upload
1531 int guestfs_upload (guestfs_h *handle,
1532 const char *filename,
1533 const char *remotefilename);
1535 Upload local file C<filename> to C<remotefilename> on the
1538 C<filename> can also be a named pipe.
1540 See also C<guestfs_download>.
1542 This function returns 0 on success or -1 on error.
1544 =head2 guestfs_vgcreate
1546 int guestfs_vgcreate (guestfs_h *handle,
1547 const char *volgroup,
1548 char * const* const physvols);
1550 This creates an LVM volume group called C<volgroup>
1551 from the non-empty list of physical volumes C<physvols>.
1553 This function returns 0 on success or -1 on error.
1555 =head2 guestfs_vgremove
1557 int guestfs_vgremove (guestfs_h *handle,
1558 const char *vgname);
1560 Remove an LVM volume group C<vgname>, (for example C<VG>).
1562 This also forcibly removes all logical volumes in the volume
1565 This function returns 0 on success or -1 on error.
1569 char **guestfs_vgs (guestfs_h *handle);
1571 List all the volumes groups detected. This is the equivalent
1572 of the L<vgs(8)> command.
1574 This returns a list of just the volume group names that were
1575 detected (eg. C<VolGroup00>).
1577 See also C<guestfs_vgs_full>.
1579 This function returns a NULL-terminated array of strings
1580 (like L<environ(3)>), or NULL if there was an error.
1581 I<The caller must free the strings and the array after use>.
1583 =head2 guestfs_vgs_full
1585 struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
1587 List all the volumes groups detected. This is the equivalent
1588 of the L<vgs(8)> command. The "full" version includes all fields.
1590 This function returns a C<struct guestfs_lvm_vg_list *>
1591 (see E<lt>guestfs-structs.hE<gt>),
1592 or NULL if there was an error.
1593 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
1595 =head2 guestfs_wait_ready
1597 int guestfs_wait_ready (guestfs_h *handle);
1599 Internally libguestfs is implemented by running a virtual machine
1602 You should call this after C<guestfs_launch> to wait for the launch
1605 This function returns 0 on success or -1 on error.
1607 =head2 guestfs_write_file
1609 int guestfs_write_file (guestfs_h *handle,
1611 const char *content,
1614 This call creates a file called C<path>. The contents of the
1615 file is the string C<content> (which can contain any 8 bit data),
1616 with length C<size>.
1618 As a special case, if C<size> is C<0>
1619 then the length is calculated using C<strlen> (so in this case
1620 the content cannot contain embedded ASCII NULs).
1622 This function returns 0 on success or -1 on error.
1624 Because of the message protocol, there is a transfer limit
1625 of somewhere between 2MB and 4MB. To transfer large files you should use
1630 int guestfs_zero (guestfs_h *handle,
1631 const char *device);
1633 This command writes zeroes over the first few blocks of C<device>.
1635 How many blocks are zeroed isn't specified (but it's I<not> enough
1636 to securely wipe the device). It should be sufficient to remove
1637 any partition tables, filesystem superblocks and so on.
1639 This function returns 0 on success or -1 on error.