Fix dependencies in perl so it doesn't always rebuild

[libguestfs.git] / guestfs-actions.pod

diff --git a/guestfs-actions.pod b/guestfs-actions.pod
index 6f33d80..9afa5de 100644 (file)
--- a/guestfs-actions.pod
+++ b/guestfs-actions.pod
@@ -7,6 +7,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<guestfs_config> call instead.
+

 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_add_drive
 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_add_drive


@@ -25,7 +30,36 @@ 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<guestfs_config> call instead.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_add_drive_ro
+
+ int guestfs_add_drive_ro (guestfs_h *handle,
+               const char *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<guestfs_config> call instead.

 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 


@@ -477,7 +511,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<guestfs_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.


@@ -512,6 +548,8 @@ FTP.
 This is the same as C<guestfs_command>, but splits the
 result into a list of lines.
 
 This is the same as C<guestfs_command>, but splits the
 result into a list of lines.
 

+See also: C<guestfs_sh_lines>
+

 This function returns a NULL-terminated array of strings
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.
 This function returns a NULL-terminated array of strings
 (like L<environ(3)>), or NULL if there was an error.
 I<The caller must free the strings and the array after use>.


@@ -624,6 +662,20 @@ so that the maximum guest memory is freed.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_e2fsck_f
+
+ int guestfs_e2fsck_f (guestfs_h *handle,
+               const char *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<guestfs_resize2fs>
+(q.v.).  Normally you should use C<guestfs_fsck>.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_end_busy
 
  int guestfs_end_busy (guestfs_h *handle);
 =head2 guestfs_end_busy
 
  int guestfs_end_busy (guestfs_h *handle);


@@ -677,6 +729,40 @@ particular that the filename is not prepended to the output
 This function returns a string, or NULL on error.
 I<The caller must free the returned string after use>.
 
 This function returns a string, or NULL on error.
 I<The caller must free the returned string after use>.
 

+=head2 guestfs_find
+
+ char **guestfs_find (guestfs_h *handle,
+               const char *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<guestfs_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.
+
+This function returns a NULL-terminated array of strings
+(like L<environ(3)>), or NULL if there was an error.
+I<The caller must free the strings and the array after use>.
+

 =head2 guestfs_fsck
 
  int guestfs_fsck (guestfs_h *handle,
 =head2 guestfs_fsck
 
  int guestfs_fsck (guestfs_h *handle,


@@ -798,6 +884,26 @@ This returns the verbose messages flag.
 
 This function returns a C truth value on success or -1 on error.
 
 
 This function returns a C truth value on success or -1 on error.
 

+=head2 guestfs_glob_expand
+
+ char **guestfs_glob_expand (guestfs_h *handle,
+               const char *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.
+
+This function returns a NULL-terminated array of strings
+(like L<environ(3)>), or NULL if there was an error.
+I<The caller must free the strings and the array after use>.
+

 =head2 guestfs_grub_install
 
  int guestfs_grub_install (guestfs_h *handle,
 =head2 guestfs_grub_install
 
  int guestfs_grub_install (guestfs_h *handle,


@@ -1184,6 +1290,26 @@ either a destination filename or destination directory.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_ntfs_3g_probe
+
+ int guestfs_ntfs_3g_probe (guestfs_h *handle,
+               int rw,
+               const char *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.
+
+On error this function returns -1.
+

 =head2 guestfs_ping_daemon
 
  int guestfs_ping_daemon (guestfs_h *handle);
 =head2 guestfs_ping_daemon
 
  int guestfs_ping_daemon (guestfs_h *handle);


@@ -1285,6 +1411,12 @@ I<The caller must free the strings and the array after use>.
 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<guestfs_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<guestfs_e2fsck_f> before
+calling this function.
+

 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_rm
 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_rm


@@ -1316,6 +1448,53 @@ Remove the single directory C<path>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_scrub_device
+
+ int guestfs_scrub_device (guestfs_h *handle,
+               const char *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.
+
+This function returns 0 on success or -1 on error.
+
+B<This command is dangerous.  Without careful use you
+can easily destroy all your data>.
+
+=head2 guestfs_scrub_file
+
+ int guestfs_scrub_file (guestfs_h *handle,
+               const char *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.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_scrub_freespace
+
+ int guestfs_scrub_freespace (guestfs_h *handle,
+               const char *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<guestfs_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.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_set_append
 
  int guestfs_set_append (guestfs_h *handle,
 =head2 guestfs_set_append
 
  int guestfs_set_append (guestfs_h *handle,


@@ -1541,6 +1720,50 @@ not intended to be parsed.
 This function returns a string, or NULL on error.
 I<The caller must free the returned string after use>.
 
 This function returns a string, or NULL on error.
 I<The caller must free the returned string after use>.
 

+=head2 guestfs_sh
+
+ char *guestfs_sh (guestfs_h *handle,
+               const char *command);
+
+This call runs a command from the guest filesystem via the
+guest's C</bin/sh>.
+
+This is like C<guestfs_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<guestfs_command> apply to this call.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_sh_lines
+
+ char **guestfs_sh_lines (guestfs_h *handle,
+               const char *command);
+
+This is the same as C<guestfs_sh>, but splits the result
+into a list of lines.
+
+See also: C<guestfs_command_lines>
+
+This function returns a NULL-terminated array of strings
+(like L<environ(3)>), or NULL if there was an error.
+I<The caller must free the strings and the array after use>.
+
+=head2 guestfs_sleep
+
+ int guestfs_sleep (guestfs_h *handle,
+               int secs);
+
+Sleep for C<secs> seconds.
+
+This function returns 0 on success or -1 on error.
+

 =head2 guestfs_stat
 
  struct guestfs_stat *guestfs_stat (guestfs_h *handle,
 =head2 guestfs_stat
 
  struct guestfs_stat *guestfs_stat (guestfs_h *handle,


@@ -1875,6 +2098,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<guestfs_scrub_device>.
+

 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_zerofree
 This function returns 0 on success or -1 on error.
 
 =head2 guestfs_zerofree