Use a squashfs attached as /dev/sdd during the C API tests.

[libguestfs.git] / guestfish-actions.pod

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index 74242e3..fa82ef1 100644 (file)
--- 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).
 
 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


@@ -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.
 
 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 ...'
 =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.
 
 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
 =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.
 
 
 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 ...'
 =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.
 
 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|-)
 =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.
 
 
 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
 =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).
 
 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
 =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>.
 
 
 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
 =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>.
 
 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
 =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>.
 
 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
 =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
  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
 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.
 
 
 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
 =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.
 
 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
 =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.
 
 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
 =head2 rm
 
  rm path


@@ -857,6 +1026,19 @@ command.
 
 Remove the single directory C<path>.
 
 
 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
 =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 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
 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.
 
 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
 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).
 
 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>.
 
 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
 =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.
 
 
 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
 =head2 sync
 
  sync


@@ -1080,6 +1329,33 @@ See also C<download>.
 
 Use C<-> instead of a filename to read/write from stdin/stdout.
 
 
 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 ...'
 =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).
 
 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.
 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.
 
 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.
+