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
just want to read the image or write access if you want to modify the
image).
-This is equivalent to the qemu parameter C<-drive file=filename>.
+This is equivalent to the qemu parameter C<-drive file=filename,cache=off>.
+
+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 ();
The single parameter is an argv-style list of arguments.
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).
+non-empty (ie. must contain a program name). Note that
+the command runs directly, and is I<not> invoked via
+the shell (see C<$h-E<gt>sh>).
+
+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
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.
+See also: C<$h-E<gt>sh_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
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>
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
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
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.
This returns the verbose messages flag.
+=item @paths = $h->glob_expand ($pattern);
+
+This command searches for all the pathnames matching
+C<pattern> according to the wildcard expansion rules
+used by the shell.
+
+If no paths match, then this returns an empty list
+(note: not an error).
+
+It is just a wrapper around the C L<glob(3)> function
+with flags C<GLOB_MARK|GLOB_BRACE>.
+See that manual page for more details.
+
=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
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 $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);
This moves a file from C<src> to C<dest> where C<dest> is
either a destination filename or destination directory.
+=item $status = $h->ntfs_3g_probe ($rw, $device);
+
+This command runs the L<ntfs-3g.probe(8)> command which probes
+an NTFS C<device> for mountability. (Not all NTFS volumes can
+be mounted read-write, and some cannot be mounted at all).
+
+C<rw> is a boolean flag. Set it to true if you want to test
+if the volume can be mounted read-write. Set it to false if
+you want to test if the volume can be mounted read-only.
+
+The return value is an integer which C<0> if the operation
+would succeed, or some non-zero value documented in the
+L<ntfs-3g.probe(8)> manual page.
+
+=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>,
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
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>.
Remove the single directory C<path>.
+=item $h->scrub_device ($device);
+
+This command writes patterns over C<device> to make data retrieval
+more difficult.
+
+It is an interface to the L<scrub(1)> program. See that
+manual page for more details.
+
+B<This command is dangerous. Without careful use you
+can easily destroy all your data>.
+
+=item $h->scrub_file ($file);
+
+This command writes patterns over a file to make data retrieval
+more difficult.
+
+The file is I<removed> after scrubbing.
+
+It is an interface to the L<scrub(1)> program. See that
+manual page for more details.
+
+=item $h->scrub_freespace ($dir);
+
+This command creates the directory C<dir> and then fills it
+with files until the filesystem is full, and scrubs the files
+as for C<$h-E<gt>scrub_file>, and deletes them.
+The intention is to scrub any free space on the partition
+containing C<dir>.
+
+It is an interface to the L<scrub(1)> program. See that
+manual page for more details.
+
+=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
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.
=item $h->set_qemu ($qemu);
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.
=item $h->set_ready ();
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>.
+=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 $output = $h->sh ($command);
+
+This call runs a command from the guest filesystem via the
+guest's C</bin/sh>.
+
+This is like C<$h-E<gt>command>, but passes the command to:
+
+ /bin/sh -c "command"
+
+Depending on the guest's shell, this usually results in
+wildcards being expanded, shell expressions being interpolated
+and so on.
+
+All the provisos about C<$h-E<gt>command> apply to this call.
+
+=item @lines = $h->sh_lines ($command);
+
+This is the same as C<$h-E<gt>sh>, but splits the result
+into a list of lines.
+
+See also: C<$h-E<gt>command_lines>
+
+=item $h->sleep ($secs);
+
+Sleep for C<secs> seconds.
+
=item %statbuf = $h->stat ($path);
Returns file information for the given C<path>.
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
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>
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.
to securely wipe the device). It should be sufficient to remove
any partition tables, filesystem superblocks and so on.
+See also: C<$h-E<gt>scrub_device>.
+
+=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;