+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 checksum
+
+ 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.
+
+=head2 chmod
+
+ chmod mode path
+
+Change the mode (permissions) of C<path> to C<mode>. Only
+numeric modes are supported.
+
+=head2 chown
+
+ chown owner group path
+
+Change the file owner to C<owner> and group to C<group>.
+
+Only numeric uid and gid are supported. If you want to use
+names, you will need to locate and parse the password file
+yourself (Augeas support makes this relatively easy).
+
+=head2 command
+
+ command 'arguments ...'
+
+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).
+
+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).
+
+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
+first parameter.
+
+Shared libraries and data files required by the program
+must be available on filesystems which are mounted in the
+correct places. It is the caller's responsibility to ensure
+all filesystems that are needed are mounted at the right
+locations.
+
+=head2 command-lines
+
+ command-lines 'arguments ...'
+
+This is the same as C<command>, but splits the
+result into a list of lines.
+
+=head2 config
+
+ config qemuparam qemuvalue
+
+This can be used to add arbitrary qemu command line parameters
+of the form C<-param value>. Actually it's not quite arbitrary - we
+prevent you from setting some parameters which would interfere with
+parameters that we use.
+
+The first character of C<param> string must be a C<-> (dash).
+
+C<value> can be NULL.
+
+=head2 cp
+
+ cp src dest
+
+This copies a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+=head2 cp-a
+
+ cp-a src dest
+
+This copies a file or directory from C<src> to C<dest>
+recursively using the C<cp -a> command.
+
+=head2 debug
+
+ debug subcmd 'extraargs ...'
+
+The C<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.
+
+=head2 dmesg
+
+ 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<set-verbose> or by setting
+the environment variable C<LIBGUESTFS_DEBUG=1> before
+running the program.
+
+=head2 download
+
+ 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<upload>, C<cat>.
+
+Use C<-> instead of a filename to read/write from stdin/stdout.
+
+=head2 drop-caches
+
+ 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.
+
+=head2 equal
+
+ 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.
+
+=head2 exists
+
+ exists path
+
+This returns C<true> if and only if there is a file, directory
+(or anything) with the given C<path> name.
+
+See also C<is-file>, C<is-dir>, C<stat>.
+
+=head2 file
+
+ file path
+
+This call uses the standard L<file(1)> command to determine
+the type or contents of the file. This also works on devices,
+for example to find out whether a partition contains a filesystem.
+
+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).
+
+=head2 fsck
+
+ 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>.
+
+=head2 get-autosync
+
+ get-autosync
+
+Get the autosync flag.
+
+=head2 get-e2label
+
+ get-e2label device
+
+This returns the ext2/3/4 filesystem label of the filesystem on
+C<device>.
+
+=head2 get-e2uuid
+
+ get-e2uuid device
+
+This returns the ext2/3/4 filesystem UUID of the filesystem on
+C<device>.
+
+=head2 get-path
+
+ get-path
+
+Return the current search path.
+
+This is always non-NULL. If it wasn't set already, then this will
+return the default path.
+
+=head2 get-qemu
+
+ 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.
+
+=head2 get-state
+
+ 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)>.
+
+=head2 get-verbose
+
+ get-verbose
+
+This returns the verbose messages flag.
+
+=head2 grub-install
+
+ grub-install root device
+
+This command installs GRUB (the Grand Unified Bootloader) on
+C<device>, with the root directory being C<root>.
+
+=head2 hexdump
+
+ 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.
+
+=head2 is-busy
+
+ 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)>.
+
+=head2 is-config
+
+ 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)>.
+
+=head2 is-dir
+
+ is-dir path
+
+This returns C<true> if and only if there is a directory
+with the given C<path> name. Note that it returns false for
+other objects like files.
+
+See also C<stat>.
+
+=head2 is-file
+
+ is-file path
+
+This returns C<true> if and only if there is a file
+with the given C<path> name. Note that it returns false for
+other objects like directories.
+
+See also C<stat>.
+
+=head2 is-launching
+
+ 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)>.
+
+=head2 is-ready
+
+ 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)>.
+
+=head2 kill-subprocess
+
+ kill-subprocess
+
+This kills the qemu subprocess. You should never need to call this.
+
+=head2 launch | run
+
+ launch
+
+Internally libguestfs is implemented by running a virtual machine
+using L<qemu(1)>.
+
+You should call this after configuring the handle
+(eg. adding drives) but before performing any actions.
+
git.annexia.org / libguestfs.git / blobdiff