Generated code for 'add_drive_ro' call.

[libguestfs.git] / perl / lib / Sys / Guestfs.pm

diff --git a/perl/lib/Sys/Guestfs.pm b/perl/lib/Sys/Guestfs.pm
index 09663bc..f8e6b77 100644 (file)
--- a/perl/lib/Sys/Guestfs.pm
+++ b/perl/lib/Sys/Guestfs.pm
@@ -97,6 +97,11 @@ This function adds a virtual CD-ROM disk image to the guest.
 
 This is equivalent to the qemu parameter C<-cdrom filename>.
 
 
 This is equivalent to the qemu parameter C<-cdrom filename>.
 

+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<$h-E<gt>config> call instead.
+

 =item $h->add_drive ($filename);
 
 This function adds a virtual machine disk image C<filename> to the
 =item $h->add_drive ($filename);
 
 This function adds a virtual machine disk image C<filename> to the


@@ -112,6 +117,30 @@ image).
 
 This is equivalent to the qemu parameter C<-drive file=filename>.
 
 
 This is equivalent to the qemu parameter C<-drive file=filename>.
 

+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<$h-E<gt>config> call instead.
+
+=item $h->add_drive_ro ($filename);
+
+This adds a drive in snapshot mode, making it effectively
+read-only.
+
+Note that writes to the device are allowed, and will be seen for
+the duration of the guestfs handle, but they are written
+to a temporary file which is discarded as soon as the guestfs
+handle is closed.  We don't currently have any method to enable
+changes to be committed, although qemu can support this.
+
+This is equivalent to the qemu parameter
+C<-drive file=filename,snapshot=on>.
+
+Note that this call checks for the existence of C<filename>.  This
+stops you from specifying other types of drive which are supported
+by qemu such as C<nbd:> and C<http:> URLs.  To specify those, use
+the general C<$h-E<gt>config> call instead.
+

 =item $h->aug_close ();
 
 Close the current Augeas handle and free up any resources
 =item $h->aug_close ();
 
 Close the current Augeas handle and free up any resources


@@ -245,19 +274,141 @@ how files are saved.
 
 Set the value associated with C<path> to C<value>.
 
 
 Set the value associated with C<path> to C<value>.
 

+=item $h->blockdev_flushbufs ($device);
+
+This tells the kernel to flush internal buffers associated
+with C<device>.
+
+This uses the L<blockdev(8)> command.
+
+=item $blocksize = $h->blockdev_getbsz ($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.
+
+=item $ro = $h->blockdev_getro ($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.
+
+=item $sizeinbytes = $h->blockdev_getsize64 ($device);
+
+This returns the size of the device in bytes.
+
+See also C<$h-E<gt>blockdev_getsz>.
+
+This uses the L<blockdev(8)> command.
+
+=item $sectorsize = $h->blockdev_getss ($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<$h-E<gt>blockdev_getsz>
+for that).
+
+This uses the L<blockdev(8)> command.
+
+=item $sizeinsectors = $h->blockdev_getsz ($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<$h-E<gt>blockdev_getss> for the real sector size of
+the device, and C<$h-E<gt>blockdev_getsize64> for the more
+useful I<size in bytes>.
+
+This uses the L<blockdev(8)> command.
+
+=item $h->blockdev_rereadpt ($device);
+
+Reread the partition table on C<device>.
+
+This uses the L<blockdev(8)> command.
+
+=item $h->blockdev_setbsz ($device, $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.
+
+=item $h->blockdev_setro ($device);
+
+Sets the block device named C<device> to read-only.
+
+This uses the L<blockdev(8)> command.
+
+=item $h->blockdev_setrw ($device);
+
+Sets the block device named C<device> to read-write.
+
+This uses the L<blockdev(8)> command.
+

 =item $content = $h->cat ($path);
 
 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
 =item $content = $h->cat ($path);
 
 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

-as end of string).  For those you need to use the C<$h-E<gt>read_file>
+as end of string).  For those you need to use the C<$h-E<gt>download>

 function which has a more complex interface.
 
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 function which has a more complex interface.
 
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=item $checksum = $h->checksum ($csumtype, $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.
+

 =item $h->chmod ($mode, $path);
 
 Change the mode (permissions) of C<path> to C<mode>.  Only
 =item $h->chmod ($mode, $path);
 
 Change the mode (permissions) of C<path> to C<mode>.  Only


@@ -283,6 +434,13 @@ The first element is the name of the program to run.
 Subsequent elements are parameters.  The list must be
 non-empty (ie. must contain a program name).
 
 Subsequent elements are parameters.  The list must be
 non-empty (ie. must contain a program name).
 

+The return value is anything printed to I<stdout> by
+the command.
+
+If the command returns a non-zero exit status, then
+this function returns an error message.  The error message
+string is the content of I<stderr> from the command.
+

 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the
 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the


@@ -294,11 +452,19 @@ 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.
 

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

 =item @lines = $h->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 
 =item @lines = $h->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 

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

 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters
 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters


@@ -310,6 +476,82 @@ The first character of C<param> string must be a C<-> (dash).
 
 C<value> can be NULL.
 
 
 C<value> can be NULL.
 

+=item $h->cp ($src, $dest);
+
+This copies a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+=item $h->cp_a ($src, $dest);
+
+This copies a file or directory from C<src> to C<dest>
+recursively using the C<cp -a> command.
+
+=item $result = $h->debug ($subcmd, \@extraargs);
+
+The C<$h-E<gt>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.
+
+=item $kmsgs = $h->dmesg ();
+
+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<$h-E<gt>set_verbose> or by setting
+the environment variable C<LIBGUESTFS_DEBUG=1> before
+running the program.
+
+=item $h->download ($remotefilename, $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<$h-E<gt>upload>, C<$h-E<gt>cat>.
+
+=item $h->drop_caches ($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.
+
+=item $h->e2fsck_f ($device);
+
+This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
+filesystem checker on C<device>, noninteractively (C<-p>),
+even if the filesystem appears to be clean (C<-f>).
+
+This command is only needed because of C<$h-E<gt>resize2fs>
+(q.v.).  Normally you should use C<$h-E<gt>fsck>.
+
+=item $h->end_busy ();
+
+This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
+state as is.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+
+=item $equality = $h->equal ($file1, $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.
+

 =item $existsflag = $h->exists ($path);
 
 This returns C<true> if and only if there is a file, directory
 =item $existsflag = $h->exists ($path);
 
 This returns C<true> if and only if there is a file, directory


@@ -327,10 +569,84 @@ 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).
 

+=item @names = $h->find ($directory);
+
+This command lists out all files and directories, recursively,
+starting at C<directory>.  It is essentially equivalent to
+running the shell command C<find directory -print> but some
+post-processing happens on the output, described below.
+
+This returns a list of strings I<without any prefix>.  Thus
+if the directory structure was:
+
+ /tmp/a
+ /tmp/b
+ /tmp/c/d
+
+then the returned list from C<$h-E<gt>find> C</tmp> would be
+4 elements:
+
+ a
+ b
+ c
+ c/d
+
+If C<directory> is not a directory, then this command returns
+an error.
+
+The returned list is sorted.
+
+=item $status = $h->fsck ($fstype, $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>.
+
+=item $append = $h->get_append ();
+
+Return the additional kernel options which are added to the
+guest kernel command line.
+
+If C<NULL> then no options are added.
+

 =item $autosync = $h->get_autosync ();
 
 Get the autosync flag.
 
 =item $autosync = $h->get_autosync ();
 
 Get the autosync flag.
 

+=item $label = $h->get_e2label ($device);
+
+This returns the ext2/3/4 filesystem label of the filesystem on
+C<device>.
+
+=item $uuid = $h->get_e2uuid ($device);
+
+This returns the ext2/3/4 filesystem UUID of the filesystem on
+C<device>.
+

 =item $path = $h->get_path ();
 
 Return the current search path.
 =item $path = $h->get_path ();
 
 Return the current search path.


@@ -338,10 +654,52 @@ 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.
 

+=item $qemu = $h->get_qemu ();
+
+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.
+
+=item $state = $h->get_state ();
+
+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)>.
+

 =item $verbose = $h->get_verbose ();
 
 This returns the verbose messages flag.
 
 =item $verbose = $h->get_verbose ();
 
 This returns the verbose messages flag.
 

+=item $h->grub_install ($root, $device);
+
+This command installs GRUB (the Grand Unified Bootloader) on
+C<device>, with the root directory being C<root>.
+
+=item $dump = $h->hexdump ($path);
+
+This runs C<hexdump -C> on the given C<path>.  The result is
+the human-readable, canonical hex dump of the file.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+
+=item $busy = $h->is_busy ();
+
+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)>.
+
+=item $config = $h->is_config ();
+
+This returns true iff this handle is being configured
+(in the C<CONFIG> state).
+
+For more information on states, see L<guestfs(3)>.
+

 =item $dirflag = $h->is_dir ($path);
 
 This returns C<true> if and only if there is a directory
 =item $dirflag = $h->is_dir ($path);
 
 This returns C<true> if and only if there is a directory


@@ -358,6 +716,20 @@ other objects like directories.
 
 See also C<$h-E<gt>stat>.
 
 
 See also C<$h-E<gt>stat>.
 

+=item $launching = $h->is_launching ();
+
+This returns true iff this handle is launching the subprocess
+(in the C<LAUNCHING> state).
+
+For more information on states, see L<guestfs(3)>.
+
+=item $ready = $h->is_ready ();
+
+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)>.
+

 =item $h->kill_subprocess ();
 
 This kills the qemu subprocess.  You should never need to call this.
 =item $h->kill_subprocess ();
 
 This kills the qemu subprocess.  You should never need to call this.


@@ -425,6 +797,20 @@ and physical volumes.
 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>.
 

+=item $h->lvremove ($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>.
+
+=item $h->lvresize ($device, $mbytes);
+
+This resizes (expands or shrinks) an existing LVM logical
+volume to C<mbytes>.  When reducing, data in the reduced part
+is lost.
+

 =item @logvols = $h->lvs ();
 
 List all the logical volumes detected.  This is the equivalent
 =item @logvols = $h->lvs ();
 
 List all the logical volumes detected.  This is the equivalent


@@ -452,7 +838,7 @@ as necessary.  This is like the C<mkdir -p> shell command.
 =item $h->mkfs ($fstype, $device);
 
 This creates a filesystem on C<device> (usually a partition
 =item $h->mkfs ($fstype, $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>.
 
 =item $h->mount ($device, $mountpoint);
 example C<ext3>.
 
 =item $h->mount ($device, $mountpoint);


@@ -474,6 +860,23 @@ on the underlying device.
 The filesystem options C<sync> and C<noatime> are set with this
 call, in order to improve reliability.
 
 The filesystem options C<sync> and C<noatime> are set with this
 call, in order to improve reliability.
 

+=item $h->mount_options ($options, $device, $mountpoint);
+
+This is the same as the C<$h-E<gt>mount> command, but it
+allows you to set the mount options as for the
+L<mount(8)> I<-o> flag.
+
+=item $h->mount_ro ($device, $mountpoint);
+
+This is the same as the C<$h-E<gt>mount> command, but it
+mounts the filesystem with the read-only (I<-o ro>) flag.
+
+=item $h->mount_vfs ($options, $vfstype, $device, $mountpoint);
+
+This is the same as the C<$h-E<gt>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.
+

 =item @devices = $h->mounts ();
 
 This returns the list of currently mounted filesystems.  It returns
 =item @devices = $h->mounts ();
 
 This returns the list of currently mounted filesystems.  It returns


@@ -481,12 +884,38 @@ the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
 
 Some internal mounts are not shown.
 
 
 Some internal mounts are not shown.
 

+=item $h->mv ($src, $dest);
+
+This moves a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+=item $h->ping_daemon ();
+
+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.
+

 =item $h->pvcreate ($device);
 
 This creates an LVM physical volume on the named C<device>,
 where C<device> should usually be a partition name such
 as C</dev/sda1>.
 
 =item $h->pvcreate ($device);
 
 This creates an LVM physical volume on the named C<device>,
 where C<device> should usually be a partition name such
 as C</dev/sda1>.
 

+=item $h->pvremove ($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.
+
+=item $h->pvresize ($device);
+
+This resizes (expands or shrinks) an existing LVM physical
+volume to match the new size of the underlying device.
+

 =item @physvols = $h->pvs ();
 
 List all the physical volumes detected.  This is the equivalent
 =item @physvols = $h->pvs ();
 
 List all the physical volumes detected.  This is the equivalent


@@ -514,6 +943,17 @@ Note that this function cannot correctly handle binary files
 as end of line).  For those you need to use the C<$h-E<gt>read_file>
 function which has a more complex interface.
 
 as end of line).  For those you need to use the C<$h-E<gt>read_file>
 function which has a more complex interface.
 

+=item $h->resize2fs ($device);
+
+This resizes an ext2 or ext3 filesystem to match the size of
+the underlying device.
+
+I<Note:> It is sometimes required that you run C<$h-E<gt>e2fsck_f>
+on the C<device> before calling this command.  For unknown reasons
+C<resize2fs> sometimes gives an error about this and sometimes not.
+In any case, it is always safe to call C<$h-E<gt>e2fsck_f> before
+calling this function.
+

 =item $h->rm ($path);
 
 Remove the single file C<path>.
 =item $h->rm ($path);
 
 Remove the single file C<path>.


@@ -528,12 +968,53 @@ command.
 
 Remove the single directory C<path>.
 
 
 Remove the single directory C<path>.
 

+=item $h->set_append ($append);
+
+This function is used to add additional options to the
+guest kernel command line.
+
+The default is C<NULL> unless overridden by setting
+C<LIBGUESTFS_APPEND> environment variable.
+
+Setting C<append> to C<NULL> means I<no> additional options
+are passed (libguestfs always adds a few of its own).
+

 =item $h->set_autosync ($autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a
 =item $h->set_autosync ($autosync);
 
 If C<autosync> is true, this enables autosync.  Libguestfs will make a

-best effort attempt to run C<$h-E<gt>sync> when the handle is closed
+best effort attempt to run C<$h-E<gt>umount_all> followed by
+C<$h-E<gt>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).
+
+=item $h->set_busy ();
+
+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)>.
+
+=item $h->set_e2label ($device, $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<$h-E<gt>tune2fs_l> or C<$h-E<gt>get_e2label>
+to return the existing label on a filesystem.
+
+=item $h->set_e2uuid ($device, $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<$h-E<gt>tune2fs_l> or C<$h-E<gt>get_e2uuid>
+to return the existing UUID of a filesystem.
+

 =item $h->set_path ($path);
 
 Set the path that libguestfs searches for kernel and initrd.img.
 =item $h->set_path ($path);
 
 Set the path that libguestfs searches for kernel and initrd.img.


@@ -541,11 +1022,27 @@ Set the path that libguestfs searches for kernel and initrd.img.
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 
 The default is C<$libdir/guestfs> unless overridden by setting
 C<LIBGUESTFS_PATH> environment variable.
 

-The string C<path> is stashed in the libguestfs handle, so the caller
-must make sure it remains valid for the lifetime of the handle.
-

 Setting C<path> to C<NULL> restores the default path.
 
 Setting C<path> to C<NULL> restores the default path.
 

+=item $h->set_qemu ($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.
+
+Setting C<qemu> to C<NULL> restores the default qemu binary.
+
+=item $h->set_ready ();
+
+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)>.
+

 =item $h->set_verbose ($verbose);
 
 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
 =item $h->set_verbose ($verbose);
 
 If C<verbose> is true, this turns on verbose messages (to C<stderr>).


@@ -575,9 +1072,45 @@ To create a single partition occupying the whole disk, you would
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 
 pass C<lines> as a single element list, when the single element being
 the string C<,> (comma).
 

+See also: C<$h-E<gt>sfdisk_l>, C<$h-E<gt>sfdisk_N>
+

 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>.
 

+=item $h->sfdisk_N ($device, $n, $cyls, $heads, $sectors, $line);
+
+This runs L<sfdisk(8)> option to modify just the single
+partition C<n> (note: C<n> counts from 1).
+
+For other parameters, see C<$h-E<gt>sfdisk>.  You should usually
+pass C<0> for the cyls/heads/sectors parameters.
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=item $partitions = $h->sfdisk_disk_geometry ($device);
+
+This displays the disk geometry of C<device> read from the
+partition table.  Especially in the case where the underlying
+block device has been resized, this can be different from the
+kernel's idea of the geometry (see C<$h-E<gt>sfdisk_kernel_geometry>).
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=item $partitions = $h->sfdisk_kernel_geometry ($device);
+
+This displays the kernel's idea of the geometry of C<device>.
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=item $partitions = $h->sfdisk_l ($device);
+
+This displays the partition table on C<device>, in the
+human-readable output of the L<sfdisk(8)> command.  It is
+not intended to be parsed.
+

 =item %statbuf = $h->stat ($path);
 
 Returns file information for the given C<path>.
 =item %statbuf = $h->stat ($path);
 
 Returns file information for the given C<path>.


@@ -592,6 +1125,31 @@ C<path> should be a file or directory in the mounted file system
 
 This is the same as the C<statvfs(2)> system call.
 
 
 This is the same as the C<statvfs(2)> system call.
 

+=item @stringsout = $h->strings ($path);
+
+This runs the L<strings(1)> command on a file and returns
+the list of printable strings found.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+
+=item @stringsout = $h->strings_e ($encoding, $path);
+
+This is like the C<$h-E<gt>strings> command, but allows you to
+specify the encoding.
+
+See the L<strings(1)> manpage for the full list of encodings.
+
+Commonly useful encodings are C<l> (lower case L) which will
+show strings inside Windows/x86 files.
+
+The returned strings are transcoded to UTF-8.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+

 =item $h->sync ();
 
 This syncs the disk, so that any writes are flushed through to the
 =item $h->sync ();
 
 This syncs the disk, so that any writes are flushed through to the


@@ -600,12 +1158,50 @@ underlying disk image.
 You should always call this if you have modified a disk image, before
 closing the handle.
 
 You should always call this if you have modified a disk image, before
 closing the handle.
 

+=item $h->tar_in ($tarfile, $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<$h-E<gt>tgz_in>.
+
+=item $h->tar_out ($directory, $tarfile);
+
+This command packs the contents of C<directory> and downloads
+it to local file C<tarfile>.
+
+To download a compressed tarball, use C<$h-E<gt>tgz_out>.
+
+=item $h->tgz_in ($tarball, $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<$h-E<gt>tar_in>.
+
+=item $h->tgz_out ($directory, $tarball);
+
+This command packs the contents of C<directory> and downloads
+it to local file C<tarball>.
+
+To download an uncompressed tarball, use C<$h-E<gt>tar_out>.
+

 =item $h->touch ($path);
 
 Touch acts like the L<touch(1)> command.  It can be used to
 update the timestamps on a file, or, if the file does not exist,
 to create a new zero-length file.
 
 =item $h->touch ($path);
 
 Touch acts like the L<touch(1)> command.  It can be used to
 update the timestamps on a file, or, if the file does not exist,
 to create a new zero-length file.
 

+=item %superblock = $h->tune2fs_l ($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.
+

 =item $h->umount ($pathordevice);
 
 This unmounts the given filesystem.  The filesystem may be
 =item $h->umount ($pathordevice);
 
 This unmounts the given filesystem.  The filesystem may be


@@ -618,11 +1214,50 @@ This unmounts all mounted filesystems.
 
 Some internal mounts are not unmounted by this call.
 
 
 Some internal mounts are not unmounted by this call.
 

+=item $h->upload ($filename, $remotefilename);
+
+Upload local file C<filename> to C<remotefilename> on the
+filesystem.
+
+C<filename> can also be a named pipe.
+
+See also C<$h-E<gt>download>.
+
+=item $h->vg_activate ($activate, \@volgroups);
+
+This command activates or (if C<activate> is false) deactivates
+all logical volumes in the listed volume groups C<volgroups>.
+If activated, then they are made known to the
+kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n volgroups...>
+
+Note that if C<volgroups> is an empty list then B<all> volume groups
+are activated or deactivated.
+
+=item $h->vg_activate_all ($activate);
+
+This command activates or (if C<activate> is false) deactivates
+all logical volumes in all volume groups.
+If activated, then they are made known to the
+kernel, ie. they appear as C</dev/mapper> devices.  If deactivated,
+then those devices disappear.
+
+This command is the same as running C<vgchange -a y|n>
+

 =item $h->vgcreate ($volgroup, \@physvols);
 
 This creates an LVM volume group called C<volgroup>
 from the non-empty list of physical volumes C<physvols>.
 
 =item $h->vgcreate ($volgroup, \@physvols);
 
 This creates an LVM volume group called C<volgroup>
 from the non-empty list of physical volumes C<physvols>.
 

+=item $h->vgremove ($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).
+

 =item @volgroups = $h->vgs ();
 
 List all the volumes groups detected.  This is the equivalent
 =item @volgroups = $h->vgs ();
 
 List all the volumes groups detected.  This is the equivalent


@@ -656,10 +1291,36 @@ As a special case, if C<size> is C<0>
 then the length is calculated using C<strlen> (so in this case
 the content cannot contain embedded ASCII NULs).
 
 then the length is calculated using C<strlen> (so in this case
 the content cannot contain embedded ASCII NULs).
 

+I<NB.> Owing to a bug, writing content containing ASCII NUL
+characters does I<not> work, even if the length is specified.
+We hope to resolve this bug in a future version.  In the meantime
+use C<$h-E<gt>upload>.
+

 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=item $h->zero ($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.
+
+=item $h->zerofree ($device);
+
+This runs the I<zerofree> program on C<device>.  This program
+claims to zero unused inodes and disk blocks on an ext2/3
+filesystem, thus making it possible to compress the filesystem
+more effectively.
+
+You should B<not> run this program if the filesystem is
+mounted.
+
+It is possible that using this program can damage the filesystem
+or data on the filesystem.
+

 =cut
 
 1;
 =cut
 
 1;