Implement 'strings' and 'hexdump' commands.

[libguestfs.git] / guestfs-actions.pod

diff --git a/guestfs-actions.pod b/guestfs-actions.pod
index 551b3e3..23e0580 100644 (file)
--- a/guestfs-actions.pod
+++ b/guestfs-actions.pod
@@ -58,7 +58,8 @@ On success this returns a pair containing the
 number of nodes in the nodeset, and a boolean flag
 if a node was created.
 
 number of nodes in the nodeset, and a boolean flag
 if a node was created.
 

-This function returns a C<struct guestfs_int_bool *>.
+This function returns a C<struct guestfs_int_bool *>,
+or NULL if there was an error.

 I<The caller must call C<guestfs_free_int_bool> after use>.
 
 =head2 guestfs_aug_defvar
 I<The caller must call C<guestfs_free_int_bool> after use>.
 
 =head2 guestfs_aug_defvar


@@ -84,7 +85,7 @@ On error this function returns -1.
 Look up the value associated with C<path>.  If C<path>
 matches exactly one node, the C<value> is returned.
 
 Look up the value associated with C<path>.  If C<path>
 matches exactly one node, the C<value> is returned.
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 I<The caller must free the returned string after use>.
 
 =head2 guestfs_aug_init
 I<The caller must free the returned string after use>.
 
 =head2 guestfs_aug_init


@@ -238,6 +239,136 @@ Set the value associated with C<path> to C<value>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_blockdev_flushbufs
+
+ int guestfs_blockdev_flushbufs (guestfs_h *handle,
+               const char *device);
+
+This tells the kernel to flush internal buffers associated
+with C<device>.
+
+This uses the L<blockdev(8)> command.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_blockdev_getbsz
+
+ int guestfs_blockdev_getbsz (guestfs_h *handle,
+               const char *device);
+
+This returns the block size of a device.
+
+(Note this is different from both I<size in blocks> and
+I<filesystem block size>).
+
+This uses the L<blockdev(8)> command.
+
+On error this function returns -1.
+
+=head2 guestfs_blockdev_getro
+
+ int guestfs_blockdev_getro (guestfs_h *handle,
+               const char *device);
+
+Returns a boolean indicating if the block device is read-only
+(true if read-only, false if not).
+
+This uses the L<blockdev(8)> command.
+
+This function returns a C truth value on success or -1 on error.
+
+=head2 guestfs_blockdev_getsize64
+
+ int64_t guestfs_blockdev_getsize64 (guestfs_h *handle,
+               const char *device);
+
+This returns the size of the device in bytes.
+
+See also C<guestfs_blockdev_getsz>.
+
+This uses the L<blockdev(8)> command.
+
+On error this function returns -1.
+
+=head2 guestfs_blockdev_getss
+
+ int guestfs_blockdev_getss (guestfs_h *handle,
+               const char *device);
+
+This returns the size of sectors on a block device.
+Usually 512, but can be larger for modern devices.
+
+(Note, this is not the size in sectors, use C<guestfs_blockdev_getsz>
+for that).
+
+This uses the L<blockdev(8)> command.
+
+On error this function returns -1.
+
+=head2 guestfs_blockdev_getsz
+
+ int64_t guestfs_blockdev_getsz (guestfs_h *handle,
+               const char *device);
+
+This returns the size of the device in units of 512-byte sectors
+(even if the sectorsize isn't 512 bytes ... weird).
+
+See also C<guestfs_blockdev_getss> for the real sector size of
+the device, and C<guestfs_blockdev_getsize64> for the more
+useful I<size in bytes>.
+
+This uses the L<blockdev(8)> command.
+
+On error this function returns -1.
+
+=head2 guestfs_blockdev_rereadpt
+
+ int guestfs_blockdev_rereadpt (guestfs_h *handle,
+               const char *device);
+
+Reread the partition table on C<device>.
+
+This uses the L<blockdev(8)> command.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_blockdev_setbsz
+
+ int guestfs_blockdev_setbsz (guestfs_h *handle,
+               const char *device,
+               int blocksize);
+
+This sets the block size of a device.
+
+(Note this is different from both I<size in blocks> and
+I<filesystem block size>).
+
+This uses the L<blockdev(8)> command.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_blockdev_setro
+
+ int guestfs_blockdev_setro (guestfs_h *handle,
+               const char *device);
+
+Sets the block device named C<device> to read-only.
+
+This uses the L<blockdev(8)> command.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_blockdev_setrw
+
+ int guestfs_blockdev_setrw (guestfs_h *handle,
+               const char *device);
+
+Sets the block device named C<device> to read-write.
+
+This uses the L<blockdev(8)> command.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_cat
 
  char *guestfs_cat (guestfs_h *handle,
 =head2 guestfs_cat
 
  char *guestfs_cat (guestfs_h *handle,


@@ -247,16 +378,66 @@ Return the contents of the file named C<path>.
 
 Note that this function cannot correctly handle binary files
 (specifically, files containing C<\0> character which is treated
 
 Note that this function cannot correctly handle binary files
 (specifically, files containing C<\0> character which is treated

-as end of string).  For those you need to use the C<guestfs_read_file>
+as end of string).  For those you need to use the C<guestfs_download>

 function which has a more complex interface.
 
 function which has a more complex interface.
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 I<The caller must free the returned string after use>.
 
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 I<The caller must free the returned string after use>.
 
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=head2 guestfs_checksum
+
+ char *guestfs_checksum (guestfs_h *handle,
+               const char *csumtype,
+               const char *path);
+
+This call computes the MD5, SHAx or CRC checksum of the
+file named C<path>.
+
+The type of checksum to compute is given by the C<csumtype>
+parameter which must have one of the following values:
+
+=over 4
+
+=item C<crc>
+
+Compute the cyclic redundancy check (CRC) specified by POSIX
+for the C<cksum> command.
+
+=item C<md5>
+
+Compute the MD5 hash (using the C<md5sum> program).
+
+=item C<sha1>
+
+Compute the SHA1 hash (using the C<sha1sum> program).
+
+=item C<sha224>
+
+Compute the SHA224 hash (using the C<sha224sum> program).
+
+=item C<sha256>
+
+Compute the SHA256 hash (using the C<sha256sum> program).
+
+=item C<sha384>
+
+Compute the SHA384 hash (using the C<sha384sum> program).
+
+=item C<sha512>
+
+Compute the SHA512 hash (using the C<sha512sum> program).
+
+=back
+
+The checksum is returned as a printable string.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+

 =head2 guestfs_chmod
 
  int guestfs_chmod (guestfs_h *handle,
 =head2 guestfs_chmod
 
  int guestfs_chmod (guestfs_h *handle,


@@ -288,7 +469,7 @@ This function returns 0 on success or -1 on error.
  char *guestfs_command (guestfs_h *handle,
                char * const* const arguments);
 
  char *guestfs_command (guestfs_h *handle,
                char * const* const arguments);
 

-This calls runs a command from the guest filesystem.  The
+This call runs a command from the guest filesystem.  The

 filesystem must be mounted, and must contain a compatible
 operating system (ie. something Linux, with the same
 or compatible processor architecture).
 filesystem must be mounted, and must contain a compatible
 operating system (ie. something Linux, with the same
 or compatible processor architecture).


@@ -309,7 +490,7 @@ correct places.  It is the caller's responsibility to ensure
 all filesystems that are needed are mounted at the right
 locations.
 
 all filesystems that are needed are mounted at the right
 locations.
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 I<The caller must free the returned string after use>.
 
 =head2 guestfs_command_lines
 I<The caller must free the returned string after use>.
 
 =head2 guestfs_command_lines


@@ -341,6 +522,106 @@ C<value> can be NULL.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_cp
+
+ int guestfs_cp (guestfs_h *handle,
+               const char *src,
+               const char *dest);
+
+This copies a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_cp_a
+
+ int guestfs_cp_a (guestfs_h *handle,
+               const char *src,
+               const char *dest);
+
+This copies a file or directory from C<src> to C<dest>
+recursively using the C<cp -a> command.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_debug
+
+ char *guestfs_debug (guestfs_h *handle,
+               const char *subcmd,
+               char * const* const extraargs);
+
+The C<guestfs_debug> command exposes some internals of
+C<guestfsd> (the guestfs daemon) that runs inside the
+qemu subprocess.
+
+There is no comprehensive help for this command.  You have
+to look at the file C<daemon/debug.c> in the libguestfs source
+to find out what you can do.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_dmesg
+
+ char *guestfs_dmesg (guestfs_h *handle);
+
+This returns the kernel messages (C<dmesg> output) from
+the guest kernel.  This is sometimes useful for extended
+debugging of problems.
+
+Another way to get the same information is to enable
+verbose messages with C<guestfs_set_verbose> or by setting
+the environment variable C<LIBGUESTFS_DEBUG=1> before
+running the program.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_download
+
+ int guestfs_download (guestfs_h *handle,
+               const char *remotefilename,
+               const char *filename);
+
+Download file C<remotefilename> and save it as C<filename>
+on the local machine.
+
+C<filename> can also be a named pipe.
+
+See also C<guestfs_upload>, C<guestfs_cat>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_drop_caches
+
+ int guestfs_drop_caches (guestfs_h *handle,
+               int whattodrop);
+
+This instructs the guest kernel to drop its page cache,
+and/or dentries and inode caches.  The parameter C<whattodrop>
+tells the kernel what precisely to drop, see
+L<http://linux-mm.org/Drop_Caches>
+
+Setting C<whattodrop> to 3 should drop everything.
+
+This automatically calls L<sync(2)> before the operation,
+so that the maximum guest memory is freed.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_equal
+
+ int guestfs_equal (guestfs_h *handle,
+               const char *file1,
+               const char *file2);
+
+This compares the two files C<file1> and C<file2> and returns
+true if their content is exactly equal, or false otherwise.
+
+The external L<cmp(1)> program is used for the comparison.
+
+This function returns a C truth value on success or -1 on error.
+

 =head2 guestfs_exists
 
  int guestfs_exists (guestfs_h *handle,
 =head2 guestfs_exists
 
  int guestfs_exists (guestfs_h *handle,


@@ -366,9 +647,45 @@ The exact command which runs is C<file -bsL path>.  Note in
 particular that the filename is not prepended to the output
 (the C<-b> option).
 
 particular that the filename is not prepended to the output
 (the C<-b> option).
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 I<The caller must free the returned string after use>.
 
 I<The caller must free the returned string after use>.
 

+=head2 guestfs_fsck
+
+ int guestfs_fsck (guestfs_h *handle,
+               const char *fstype,
+               const char *device);
+
+This runs the filesystem checker (fsck) on C<device> which
+should have filesystem type C<fstype>.
+
+The returned integer is the status.  See L<fsck(8)> for the
+list of status codes from C<fsck>.
+
+Notes:
+
+=over 4
+
+=item *
+
+Multiple status codes can be summed together.
+
+=item *
+
+A non-zero return code can mean "success", for example if
+errors have been corrected on the filesystem.
+
+=item *
+
+Checking or repairing NTFS volumes is not supported
+(by linux-ntfs).
+
+=back
+
+This command is entirely equivalent to running C<fsck -a -t fstype device>.
+
+On error this function returns -1.
+

 =head2 guestfs_get_autosync
 
  int guestfs_get_autosync (guestfs_h *handle);
 =head2 guestfs_get_autosync
 
  int guestfs_get_autosync (guestfs_h *handle);


@@ -377,6 +694,28 @@ Get the autosync flag.
 
 This function returns a C truth value on success or -1 on error.
 
 
 This function returns a C truth value on success or -1 on error.
 

+=head2 guestfs_get_e2label
+
+ char *guestfs_get_e2label (guestfs_h *handle,
+               const char *device);
+
+This returns the ext2/3/4 filesystem label of the filesystem on
+C<device>.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_get_e2uuid
+
+ char *guestfs_get_e2uuid (guestfs_h *handle,
+               const char *device);
+
+This returns the ext2/3/4 filesystem UUID of the filesystem on
+C<device>.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+

 =head2 guestfs_get_path
 
  const char *guestfs_get_path (guestfs_h *handle);
 =head2 guestfs_get_path
 
  const char *guestfs_get_path (guestfs_h *handle);


@@ -386,9 +725,32 @@ Return the current search path.
 This is always non-NULL.  If it wasn't set already, then this will
 return the default path.
 
 This is always non-NULL.  If it wasn't set already, then this will
 return the default path.
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 The string is owned by the guest handle and must I<not> be freed.
 
 The string is owned by the guest handle and must I<not> be freed.
 

+=head2 guestfs_get_qemu
+
+ const char *guestfs_get_qemu (guestfs_h *handle);
+
+Return the current qemu binary.
+
+This is always non-NULL.  If it wasn't set already, then this will
+return the default qemu binary name.
+
+This function returns a string, or NULL on error.
+The string is owned by the guest handle and must I<not> be freed.
+
+=head2 guestfs_get_state
+
+ int guestfs_get_state (guestfs_h *handle);
+
+This returns the current state as an opaque integer.  This is
+only useful for printing debug and internal error messages.
+
+For more information on states, see L<guestfs(3)>.
+
+On error this function returns -1.
+

 =head2 guestfs_get_verbose
 
  int guestfs_get_verbose (guestfs_h *handle);
 =head2 guestfs_get_verbose
 
  int guestfs_get_verbose (guestfs_h *handle);


@@ -397,6 +759,39 @@ This returns the verbose messages flag.
 
 This function returns a C truth value on success or -1 on error.
 
 
 This function returns a C truth value on success or -1 on error.
 

+=head2 guestfs_grub_install
+
+ int guestfs_grub_install (guestfs_h *handle,
+               const char *root,
+               const char *device);
+
+This command installs GRUB (the Grand Unified Bootloader) on
+C<device>, with the root directory being C<root>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_is_busy
+
+ int guestfs_is_busy (guestfs_h *handle);
+
+This returns true iff this handle is busy processing a command
+(in the C<BUSY> state).
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns a C truth value on success or -1 on error.
+
+=head2 guestfs_is_config
+
+ int guestfs_is_config (guestfs_h *handle);
+
+This returns true iff this handle is being configured
+(in the C<CONFIG> state).
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns a C truth value on success or -1 on error.
+

 =head2 guestfs_is_dir
 
  int guestfs_is_dir (guestfs_h *handle,
 =head2 guestfs_is_dir
 
  int guestfs_is_dir (guestfs_h *handle,


@@ -423,6 +818,28 @@ See also C<guestfs_stat>.
 
 This function returns a C truth value on success or -1 on error.
 
 
 This function returns a C truth value on success or -1 on error.
 

+=head2 guestfs_is_launching
+
+ int guestfs_is_launching (guestfs_h *handle);
+
+This returns true iff this handle is launching the subprocess
+(in the C<LAUNCHING> state).
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns a C truth value on success or -1 on error.
+
+=head2 guestfs_is_ready
+
+ int guestfs_is_ready (guestfs_h *handle);
+
+This returns true iff this handle is ready to accept commands
+(in the C<READY> state).
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns a C truth value on success or -1 on error.
+

 =head2 guestfs_kill_subprocess
 
  int guestfs_kill_subprocess (guestfs_h *handle);
 =head2 guestfs_kill_subprocess
 
  int guestfs_kill_subprocess (guestfs_h *handle);


@@ -481,7 +898,7 @@ there is no cwd) in the format of 'ls -la'.
 This command is mostly useful for interactive sessions.  It
 is I<not> intended that you try to parse the output string.
 
 This command is mostly useful for interactive sessions.  It
 is I<not> intended that you try to parse the output string.
 

-This function returns a string or NULL on error.
+This function returns a string, or NULL on error.

 I<The caller must free the returned string after use>.
 
 =head2 guestfs_ls
 I<The caller must free the returned string after use>.
 
 =head2 guestfs_ls


@@ -500,6 +917,24 @@ This function returns a NULL-terminated array of strings
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.
 
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.
 

+=head2 guestfs_lstat
+
+ struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
+               const char *path);
+
+Returns file information for the given C<path>.
+
+This is the same as C<guestfs_stat> except that if C<path>
+is a symbolic link, then the link is stat-ed, not the file it
+refers to.
+
+This is the same as the C<lstat(2)> system call.
+
+This function returns a C<struct guestfs_stat *>
+(see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.
+I<The caller must call C<free> after use>.
+

 =head2 guestfs_lvcreate
 
  int guestfs_lvcreate (guestfs_h *handle,
 =head2 guestfs_lvcreate
 
  int guestfs_lvcreate (guestfs_h *handle,


@@ -524,6 +959,19 @@ This function returns 0 on success or -1 on error.
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 

+=head2 guestfs_lvremove
+
+ int guestfs_lvremove (guestfs_h *handle,
+               const char *device);
+
+Remove an LVM logical volume C<device>, where C<device> is
+the path to the LV, such as C</dev/VG/LV>.
+
+You can also remove all LVs in a volume group by specifying
+the VG name, C</dev/VG>.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_lvs
 
  char **guestfs_lvs (guestfs_h *handle);
 =head2 guestfs_lvs
 
  char **guestfs_lvs (guestfs_h *handle);


@@ -547,7 +995,9 @@ I<The caller must free the strings and the array after use>.
 List all the logical volumes detected.  This is the equivalent
 of the L<lvs(8)> command.  The "full" version includes all fields.
 
 List all the logical volumes detected.  This is the equivalent
 of the L<lvs(8)> command.  The "full" version includes all fields.
 

-This function returns a C<struct guestfs_lvm_lv_list *>.
+This function returns a C<struct guestfs_lvm_lv_list *>
+(see E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.

 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
 
 =head2 guestfs_mkdir
 I<The caller must call C<guestfs_free_lvm_lv_list> after use>.
 
 =head2 guestfs_mkdir


@@ -576,7 +1026,7 @@ This function returns 0 on success or -1 on error.
                const char *device);
 
 This creates a filesystem on C<device> (usually a partition
                const char *device);
 
 This creates a filesystem on C<device> (usually a partition

-of LVM logical volume).  The filesystem type is C<fstype>, for
+or LVM logical volume).  The filesystem type is C<fstype>, for

 example C<ext3>.
 
 This function returns 0 on success or -1 on error.
 example C<ext3>.
 
 This function returns 0 on success or -1 on error.


@@ -606,6 +1056,44 @@ call, in order to improve reliability.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_mount_options
+
+ int guestfs_mount_options (guestfs_h *handle,
+               const char *options,
+               const char *device,
+               const char *mountpoint);
+
+This is the same as the C<guestfs_mount> command, but it
+allows you to set the mount options as for the
+L<mount(8)> I<-o> flag.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mount_ro
+
+ int guestfs_mount_ro (guestfs_h *handle,
+               const char *device,
+               const char *mountpoint);
+
+This is the same as the C<guestfs_mount> command, but it
+mounts the filesystem with the read-only (I<-o ro>) flag.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mount_vfs
+
+ int guestfs_mount_vfs (guestfs_h *handle,
+               const char *options,
+               const char *vfstype,
+               const char *device,
+               const char *mountpoint);
+
+This is the same as the C<guestfs_mount> command, but it
+allows you to set both the mount options and the vfstype
+as for the L<mount(8)> I<-o> and I<-t> flags.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_mounts
 
  char **guestfs_mounts (guestfs_h *handle);
 =head2 guestfs_mounts
 
  char **guestfs_mounts (guestfs_h *handle);


@@ -619,6 +1107,28 @@ This function returns a NULL-terminated array of strings
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.
 
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.
 

+=head2 guestfs_mv
+
+ int guestfs_mv (guestfs_h *handle,
+               const char *src,
+               const char *dest);
+
+This moves a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_ping_daemon
+
+ int guestfs_ping_daemon (guestfs_h *handle);
+
+This is a test probe into the guestfs daemon running inside
+the qemu subprocess.  Calling this function checks that the
+daemon responds to the ping message, without affecting the daemon
+or attached block device(s) in any other way.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_pvcreate
 
  int guestfs_pvcreate (guestfs_h *handle,
 =head2 guestfs_pvcreate
 
  int guestfs_pvcreate (guestfs_h *handle,


@@ -630,6 +1140,20 @@ as C</dev/sda1>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_pvremove
+
+ int guestfs_pvremove (guestfs_h *handle,
+               const char *device);
+
+This wipes a physical volume C<device> so that LVM will no longer
+recognise it.
+
+The implementation uses the C<pvremove> command which refuses to
+wipe physical volumes that contain any volume groups, so you have
+to remove those first.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_pvs
 
  char **guestfs_pvs (guestfs_h *handle);
 =head2 guestfs_pvs
 
  char **guestfs_pvs (guestfs_h *handle);


@@ -653,7 +1177,9 @@ I<The caller must free the strings and the array after use>.
 List all the physical volumes detected.  This is the equivalent
 of the L<pvs(8)> command.  The "full" version includes all fields.
 
 List all the physical volumes detected.  This is the equivalent
 of the L<pvs(8)> command.  The "full" version includes all fields.
 

-This function returns a C<struct guestfs_lvm_pv_list *>.
+This function returns a C<struct guestfs_lvm_pv_list *>
+(see E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.

 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
 
 =head2 guestfs_read_lines
 I<The caller must call C<guestfs_free_lvm_pv_list> after use>.
 
 =head2 guestfs_read_lines


@@ -710,9 +1236,55 @@ This function returns 0 on success or -1 on error.
                int autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a
                int autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a

-best effort attempt to run C<guestfs_sync> when the handle is closed
+best effort attempt to run C<guestfs_umount_all> followed by
+C<guestfs_sync> when the handle is closed

 (also if the program exits without closing handles).
 
 (also if the program exits without closing handles).
 

+This is disabled by default (except in guestfish where it is
+enabled by default).
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_set_busy
+
+ int guestfs_set_busy (guestfs_h *handle);
+
+This sets the state to C<BUSY>.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_set_e2label
+
+ int guestfs_set_e2label (guestfs_h *handle,
+               const char *device,
+               const char *label);
+
+This sets the ext2/3/4 filesystem label of the filesystem on
+C<device> to C<label>.  Filesystem labels are limited to
+16 characters.
+
+You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2label>
+to return the existing label on a filesystem.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_set_e2uuid
+
+ int guestfs_set_e2uuid (guestfs_h *handle,
+               const char *device,
+               const char *uuid);
+
+This sets the ext2/3/4 filesystem UUID of the filesystem on
+C<device> to C<uuid>.  The format of the UUID and alternatives
+such as C<clear>, C<random> and C<time> are described in the
+L<tune2fs(8)> manpage.
+
+You can use either C<guestfs_tune2fs_l> or C<guestfs_get_e2uuid>
+to return the existing UUID of a filesystem.
+

 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_set_path
 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_set_path


@@ -732,6 +1304,37 @@ Setting C<path> to C<NULL> restores the default path.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_set_qemu
+
+ int guestfs_set_qemu (guestfs_h *handle,
+               const char *qemu);
+
+Set the qemu binary that we will use.
+
+The default is chosen when the library was compiled by the
+configure script.
+
+You can also override this by setting the C<LIBGUESTFS_QEMU>
+environment variable.
+
+The string C<qemu> is stashed in the libguestfs handle, so the caller
+must make sure it remains valid for the lifetime of the handle.
+
+Setting C<qemu> to C<NULL> restores the default qemu binary.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_set_ready
+
+ int guestfs_set_ready (guestfs_h *handle);
+
+This sets the state to C<READY>.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_set_verbose
 
  int guestfs_set_verbose (guestfs_h *handle,
 =head2 guestfs_set_verbose
 
  int guestfs_set_verbose (guestfs_h *handle,


@@ -778,6 +1381,36 @@ This function returns 0 on success or -1 on error.
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 

+=head2 guestfs_stat
+
+ struct guestfs_stat *guestfs_stat (guestfs_h *handle,
+               const char *path);
+
+Returns file information for the given C<path>.
+
+This is the same as the C<stat(2)> system call.
+
+This function returns a C<struct guestfs_stat *>
+(see L<stat(2)> and E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.
+I<The caller must call C<free> after use>.
+
+=head2 guestfs_statvfs
+
+ struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
+               const char *path);
+
+Returns file system statistics for any mounted file system.
+C<path> should be a file or directory in the mounted file system
+(typically it is the mount point itself, but it doesn't need to be).
+
+This is the same as the C<statvfs(2)> system call.
+
+This function returns a C<struct guestfs_statvfs *>
+(see L<statvfs(2)> and E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.
+I<The caller must call C<free> after use>.
+

 =head2 guestfs_sync
 
  int guestfs_sync (guestfs_h *handle);
 =head2 guestfs_sync
 
  int guestfs_sync (guestfs_h *handle);


@@ -790,6 +1423,58 @@ closing the handle.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_tar_in
+
+ int guestfs_tar_in (guestfs_h *handle,
+               const char *tarfile,
+               const char *directory);
+
+This command uploads and unpacks local file C<tarfile> (an
+I<uncompressed> tar file) into C<directory>.
+
+To upload a compressed tarball, use C<guestfs_tgz_in>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_tar_out
+
+ int guestfs_tar_out (guestfs_h *handle,
+               const char *directory,
+               const char *tarfile);
+
+This command packs the contents of C<directory> and downloads
+it to local file C<tarfile>.
+
+To download a compressed tarball, use C<guestfs_tgz_out>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_tgz_in
+
+ int guestfs_tgz_in (guestfs_h *handle,
+               const char *tarball,
+               const char *directory);
+
+This command uploads and unpacks local file C<tarball> (a
+I<gzip compressed> tar file) into C<directory>.
+
+To upload an uncompressed tarball, use C<guestfs_tar_in>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_tgz_out
+
+ int guestfs_tgz_out (guestfs_h *handle,
+               const char *directory,
+               const char *tarball);
+
+This command packs the contents of C<directory> and downloads
+it to local file C<tarball>.
+
+To download an uncompressed tarball, use C<guestfs_tar_out>.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_touch
 
  int guestfs_touch (guestfs_h *handle,
 =head2 guestfs_touch
 
  int guestfs_touch (guestfs_h *handle,


@@ -801,6 +1486,25 @@ to create a new zero-length file.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_tune2fs_l
+
+ char **guestfs_tune2fs_l (guestfs_h *handle,
+               const char *device);
+
+This returns the contents of the ext2, ext3 or ext4 filesystem
+superblock on C<device>.
+
+It is the same as running C<tune2fs -l device>.  See L<tune2fs(8)>
+manpage for more details.  The list of fields returned isn't
+clearly defined, and depends on both the version of C<tune2fs>
+that libguestfs was built against, and the filesystem itself.
+
+This function returns a NULL-terminated array of
+strings, or NULL if there was an error.
+The array of strings will always have length C<2n+1>, where
+C<n> keys and values alternate, followed by the trailing NULL entry.
+I<The caller must free the strings and the array after use>.
+

 =head2 guestfs_umount
 
  int guestfs_umount (guestfs_h *handle,
 =head2 guestfs_umount
 
  int guestfs_umount (guestfs_h *handle,


@@ -822,6 +1526,21 @@ Some internal mounts are not unmounted by this call.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_upload
+
+ int guestfs_upload (guestfs_h *handle,
+               const char *filename,
+               const char *remotefilename);
+
+Upload local file C<filename> to C<remotefilename> on the
+filesystem.
+
+C<filename> can also be a named pipe.
+
+See also C<guestfs_download>.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_vgcreate
 
  int guestfs_vgcreate (guestfs_h *handle,
 =head2 guestfs_vgcreate
 
  int guestfs_vgcreate (guestfs_h *handle,


@@ -833,6 +1552,18 @@ from the non-empty list of physical volumes C<physvols>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_vgremove
+
+ int guestfs_vgremove (guestfs_h *handle,
+               const char *vgname);
+
+Remove an LVM volume group C<vgname>, (for example C<VG>).
+
+This also forcibly removes all logical volumes in the volume
+group (if any).
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_vgs
 
  char **guestfs_vgs (guestfs_h *handle);
 =head2 guestfs_vgs
 
  char **guestfs_vgs (guestfs_h *handle);


@@ -856,7 +1587,9 @@ I<The caller must free the strings and the array after use>.
 List all the volumes groups detected.  This is the equivalent
 of the L<vgs(8)> command.  The "full" version includes all fields.
 
 List all the volumes groups detected.  This is the equivalent
 of the L<vgs(8)> command.  The "full" version includes all fields.
 

-This function returns a C<struct guestfs_lvm_vg_list *>.
+This function returns a C<struct guestfs_lvm_vg_list *>
+(see E<lt>guestfs-structs.hE<gt>),
+or NULL if there was an error.

 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
 
 =head2 guestfs_wait_ready
 I<The caller must call C<guestfs_free_lvm_vg_list> after use>.
 
 =head2 guestfs_wait_ready


@@ -892,3 +1625,16 @@ Because of the message protocol, there is a transfer limit
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=head2 guestfs_zero
+
+ int guestfs_zero (guestfs_h *handle,
+               const char *device);
+
+This command writes zeroes over the first few blocks of C<device>.
+
+How many blocks are zeroed isn't specified (but it's I<not> enough
+to securely wipe the device).  It should be sufficient to remove
+any partition tables, filesystem superblocks and so on.
+
+This function returns 0 on success or -1 on error.
+