Fix detection of optional libvirt support in virt-inspector.

[libguestfs.git] / guestfish-actions.pod

diff --git a/guestfish-actions.pod b/guestfish-actions.pod
index 3945fb1..e21dc7b 100644 (file)
--- a/guestfish-actions.pod
+++ b/guestfish-actions.pod
@@ -6,6 +6,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<config> call instead.
+

 =head2 add-drive | add
 
  add-drive filename
 =head2 add-drive | add
 
  add-drive filename


@@ -21,7 +26,33 @@ for whatever operations you want to perform (ie. read access if you
 just want to read the image or write access if you want to modify the
 image).
 
 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<config> call instead.
+
+=head2 add-drive-ro | add-ro
+
+ 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<config> call instead.

 
 =head2 aug-close
 
 
 =head2 aug-close
 


@@ -370,7 +401,9 @@ 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
 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<sh>).

 
 The return value is anything printed to I<stdout> by
 the command.
 
 The return value is anything printed to I<stdout> by
 the command.


@@ -401,6 +434,8 @@ FTP.
 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.
 

+See also: C<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.
 Because of the message protocol, there is a transfer limit 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.


@@ -484,6 +519,17 @@ 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.
 
 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
 =head2 equal
 
  equal file1 file2


@@ -514,6 +560,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


@@ -608,6 +683,21 @@ For more information on states, see L<guestfs(3)>.
 
 This returns the verbose messages flag.
 
 
 This returns the verbose messages flag.
 

+=head2 glob-expand
+
+ 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.
+

 =head2 grub-install
 
  grub-install root device
 =head2 grub-install
 
  grub-install root device


@@ -817,6 +907,29 @@ Create a directory named C<path>.
 Create a directory named C<path>, creating any parent directories
 as necessary.  This is like the C<mkdir -p> shell command.
 
 Create a directory named C<path>, creating any parent directories
 as necessary.  This is like the C<mkdir -p> shell command.
 

+=head2 mkdtemp
+
+ mkdtemp template
+
+This command creates a temporary directory.  The
+C<template> parameter should be a full pathname for the
+temporary directory name with the final six characters being
+"XXXXXX".
+
+For example: "/tmp/myprogXXXXXX" or "/Temp/myprogXXXXXX",
+the second one being suitable for Windows filesystems.
+
+The name of the temporary directory that was created
+is returned.
+
+The temporary directory is created with mode 0700
+and is owned by root.
+
+The caller is responsible for deleting the temporary
+directory and its contents after use.
+
+See also: L<mkdtemp(3)>
+

 =head2 mkfs
 
  mkfs fstype device
 =head2 mkfs
 
  mkfs fstype device


@@ -885,6 +998,22 @@ Some internal mounts are not shown.
 This moves a file from C<src> to C<dest> where C<dest> is
 either a destination filename or destination directory.
 
 This moves a file from C<src> to C<dest> where C<dest> is
 either a destination filename or destination directory.
 

+=head2 ntfs-3g-probe
+
+ ntfs-3g-probe true|false 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.
+

 =head2 ping-daemon
 
  ping-daemon
 =head2 ping-daemon
 
  ping-daemon


@@ -960,6 +1089,12 @@ function which has a more complex interface.
 This resizes an ext2 or ext3 filesystem to match the size of
 the underlying 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


@@ -980,6 +1115,44 @@ command.
 
 Remove the single directory C<path>.
 
 
 Remove the single directory C<path>.
 

+=head2 scrub-device
+
+ 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>.
+
+=head2 scrub-file
+
+ 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.
+
+=head2 scrub-freespace
+
+ 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<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.
+

 =head2 set-append | append
 
  set-append append
 =head2 set-append | append
 
  set-append append


@@ -1133,6 +1306,38 @@ 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.
 
 human-readable output of the L<sfdisk(8)> command.  It is
 not intended to be parsed.
 

+=head2 sh
+
+ sh command
+
+This call runs a command from the guest filesystem via the
+guest's C</bin/sh>.
+
+This is like C<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<command> apply to this call.
+
+=head2 sh-lines
+
+ sh-lines command
+
+This is the same as C<sh>, but splits the result
+into a list of lines.
+
+See also: C<command-lines>
+
+=head2 sleep
+
+ sleep secs
+
+Sleep for C<secs> seconds.
+

 =head2 stat
 
  stat path
 =head2 stat
 
  stat path


@@ -1376,6 +1581,8 @@ 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.
 

+See also: C<scrub-device>.
+

 =head2 zerofree
 
  zerofree device
 =head2 zerofree
 
  zerofree device