X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfish-actions.pod;h=fa82ef1b11853c4a25f9496bf0e6d311af287738;hp=74242e32aa9390c4372dc796d1e154fca503e807;hb=e02066bcb33a2aed5f23dd18c3168dc66efddb18;hpb=e118c14b9552de311cbc1734e03a3226b484c1e8

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index 74242e3..fa82ef1 100644
--- a/guestfish-actions.pod
+++ b/guestfish-actions.pod
@@ -372,6 +372,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).
 
+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
@@ -383,6 +390,10 @@ correct places.  It is the caller's responsibility to ensure
 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.
+
 =head2 command-lines
 
  command-lines 'arguments ...'
@@ -390,6 +401,10 @@ locations.
 This is the same as C<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.
+
 =head2 config
 
  config qemuparam qemuvalue
@@ -403,6 +418,20 @@ 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 ...'
@@ -415,6 +444,19 @@ 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|-)
@@ -428,6 +470,40 @@ 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 e2fsck-f
+
+ 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<resize2fs>
+(q.v.).  Normally you should use C<fsck>.
+
+=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
@@ -449,6 +525,35 @@ 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 find
+
+ 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<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.
+
 =head2 fsck
 
  fsck fstype device
@@ -481,6 +586,15 @@ Checking or repairing NTFS volumes is not supported
 
 This command is entirely equivalent to running C<fsck -a -t fstype device>.
 
+=head2 get-append
+
+ get-append
+
+Return the additional kernel options which are added to the
+guest kernel command line.
+
+If C<NULL> then no options are added.
+
 =head2 get-autosync
 
  get-autosync
@@ -541,6 +655,17 @@ This returns the verbose messages flag.
 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
@@ -692,6 +817,14 @@ 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>.
 
+=head2 lvresize
+
+ 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.
+
 =head2 lvs
 
  lvs
@@ -729,7 +862,7 @@ as necessary.  This is like the C<mkdir -p> shell command.
  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>.
 
 =head2 mount
@@ -785,6 +918,22 @@ the list of devices (eg. C</dev/sda1>, C</dev/VG/LV>).
 
 Some internal mounts are not shown.
 
+=head2 mv
+
+ mv src dest
+
+This moves a file from C<src> to C<dest> where C<dest> is
+either a destination filename or destination directory.
+
+=head2 ping-daemon
+
+ 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.
+
 =head2 pvcreate
 
  pvcreate device
@@ -804,6 +953,13 @@ 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.
 
+=head2 pvresize
+
+ pvresize device
+
+This resizes (expands or shrinks) an existing LVM physical
+volume to match the new size of the underlying device.
+
 =head2 pvs
 
  pvs
@@ -837,6 +993,19 @@ Note that this function cannot correctly handle binary files
 as end of line).  For those you need to use the C<read-file>
 function which has a more complex interface.
 
+=head2 resize2fs
+
+ 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<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<e2fsck-f> before
+calling this function.
+
 =head2 rm
 
  rm path
@@ -857,6 +1026,19 @@ command.
 
 Remove the single directory C<path>.
 
+=head2 set-append | append
+
+ 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).
+
 =head2 set-autosync | autosync
 
  set-autosync true|false
@@ -901,9 +1083,6 @@ 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 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.
 
 =head2 set-qemu | qemu
@@ -918,9 +1097,6 @@ 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.
 
 =head2 set-verbose | verbose
@@ -956,9 +1132,53 @@ 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).
 
+See also: C<sfdisk-l>, C<sfdisk-N>
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=head2 sfdisk-N
+
+ 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<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>.
 
+=head2 sfdisk-disk-geometry
+
+ 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<sfdisk-kernel-geometry>).
+
+The result is in human-readable format, and not designed to
+be parsed.
+
+=head2 sfdisk-kernel-geometry
+
+ 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.
+
+=head2 sfdisk-l
+
+ 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.
+
 =head2 stat
 
  stat path
@@ -977,6 +1197,35 @@ C<path> should be a file or directory in the mounted file system
 
 This is the same as the C<statvfs(2)> system call.
 
+=head2 strings
+
+ 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.
+
+=head2 strings-e
+
+ strings-e encoding path
+
+This is like the C<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.
+
 =head2 sync
 
  sync
@@ -1080,6 +1329,33 @@ See also C<download>.
 
 Use C<-> instead of a filename to read/write from stdin/stdout.
 
+=head2 vg-activate
+
+ vg-activate true|false '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.
+
+=head2 vg-activate-all
+
+ vg-activate-all true|false
+
+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>
+
 =head2 vgcreate
 
  vgcreate volgroup 'physvols ...'
@@ -1127,6 +1403,11 @@ 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).
 
+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<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.
@@ -1141,3 +1422,18 @@ 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.
 
+=head2 zerofree
+
+ 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.
+