Generated code for mount-loop command.

[libguestfs.git] / guestfs-actions.pod

diff --git a/guestfs-actions.pod b/guestfs-actions.pod
index 0b06470..56949fa 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>.


@@ -576,6 +614,33 @@ to find out what you can do.
 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_df
+
+ char *guestfs_df (guestfs_h *handle);
+
+This command runs the C<df> command to report disk space used.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+Use C<statvfs> from programs.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_df_h
+
+ char *guestfs_df_h (guestfs_h *handle);
+
+This command runs the C<df -h> command to report disk space used
+in human-readable format.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+Use C<statvfs> from programs.
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+

 =head2 guestfs_dmesg
 
  char *guestfs_dmesg (guestfs_h *handle);
 =head2 guestfs_dmesg
 
  char *guestfs_dmesg (guestfs_h *handle);


@@ -624,6 +689,23 @@ 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_du
+
+ int64_t guestfs_du (guestfs_h *handle,
+               const char *path);
+
+This command runs the C<du -s> command to estimate file space
+usage for C<path>.
+
+C<path> can be a file or a directory.  If C<path> is a directory
+then the estimate includes the contents of the directory and all
+subdirectories (recursively).
+
+The result is the estimated size in I<kilobytes>
+(ie. units of 1024 bytes).
+
+On error this function returns -1.
+

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


@@ -846,6 +928,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,


@@ -857,6 +959,44 @@ C<device>, with the root directory being C<root>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_head
+
+ char **guestfs_head (guestfs_h *handle,
+               const char *path);
+
+This command returns up to the first 10 lines of a file as
+a list of strings.
+
+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>.
+
+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 guestfs_head_n
+
+ char **guestfs_head_n (guestfs_h *handle,
+               int nrlines,
+               const char *path);
+
+If the parameter C<nrlines> is a positive number, this returns the first
+C<nrlines> lines of the file C<path>.
+
+If the parameter C<nrlines> is a negative number, this returns lines
+from the file C<path>, excluding the last C<nrlines> lines.
+
+If the parameter C<nrlines> is zero, this returns an empty list.
+
+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>.
+
+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 guestfs_hexdump
 
  char *guestfs_hexdump (guestfs_h *handle,
 =head2 guestfs_hexdump
 
  char *guestfs_hexdump (guestfs_h *handle,


@@ -872,6 +1012,25 @@ Because of the message protocol, there is a transfer limit
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 
 of somewhere between 2MB and 4MB.  To transfer large files you should use
 FTP.
 

+=head2 guestfs_initrd_list
+
+ char **guestfs_initrd_list (guestfs_h *handle,
+               const char *path);
+
+This command lists out files contained in an initrd.
+
+The files are listed without any initial C</> character.  The
+files are listed in the order they appear (not necessarily
+alphabetical).  Directory names are listed as separate items.
+
+Old Linux kernels (2.4 and earlier) used a compressed ext2
+filesystem as initrd.  We I<only> support the newer initramfs
+format (compressed cpio files).
+
+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_is_busy
 
  int guestfs_is_busy (guestfs_h *handle);
 =head2 guestfs_is_busy
 
  int guestfs_is_busy (guestfs_h *handle);


@@ -1133,6 +1292,33 @@ as necessary.  This is like the C<mkdir -p> shell command.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_mkdtemp
+
+ char *guestfs_mkdtemp (guestfs_h *handle,
+               const char *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)>
+
+This function returns a string, or NULL on error.
+I<The caller must free the returned string after use>.
+

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


@@ -1170,6 +1356,18 @@ call, in order to improve reliability.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_mount_loop
+
+ int guestfs_mount_loop (guestfs_h *handle,
+               const char *file,
+               const char *mountpoint);
+
+This command lets you mount C<file> (a filesystem image
+in a file) on a mount point.  It is entirely equivalent to
+the command C<mount -o loop file mountpoint>.
+
+This function returns 0 on success or -1 on error.
+

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


@@ -1232,6 +1430,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);


@@ -1370,6 +1588,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,


@@ -1537,7 +1802,7 @@ can easily destroy all your data>.
 
  int guestfs_sfdisk_N (guestfs_h *handle,
                const char *device,
 
  int guestfs_sfdisk_N (guestfs_h *handle,
                const char *device,

-               int n,
+               int partnum,

                int cyls,
                int heads,
                int sectors,
                int cyls,
                int heads,
                int sectors,


@@ -1595,6 +1860,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,


@@ -1677,6 +1986,44 @@ closing the handle.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_tail
+
+ char **guestfs_tail (guestfs_h *handle,
+               const char *path);
+
+This command returns up to the last 10 lines of a file as
+a list of strings.
+
+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>.
+
+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 guestfs_tail_n
+
+ char **guestfs_tail_n (guestfs_h *handle,
+               int nrlines,
+               const char *path);
+
+If the parameter C<nrlines> is a positive number, this returns the last
+C<nrlines> lines of the file C<path>.
+
+If the parameter C<nrlines> is a negative number, this returns lines
+from the file C<path>, starting with the C<-nrlines>th line.
+
+If the parameter C<nrlines> is zero, this returns an empty list.
+
+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>.
+
+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 guestfs_tar_in
 
  int guestfs_tar_in (guestfs_h *handle,
 =head2 guestfs_tar_in
 
  int guestfs_tar_in (guestfs_h *handle,


@@ -1892,6 +2239,36 @@ to complete.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_wc_c
+
+ int guestfs_wc_c (guestfs_h *handle,
+               const char *path);
+
+This command counts the characters in a file, using the
+C<wc -c> external command.
+
+On error this function returns -1.
+
+=head2 guestfs_wc_l
+
+ int guestfs_wc_l (guestfs_h *handle,
+               const char *path);
+
+This command counts the lines in a file, using the
+C<wc -l> external command.
+
+On error this function returns -1.
+
+=head2 guestfs_wc_w
+
+ int guestfs_wc_w (guestfs_h *handle,
+               const char *path);
+
+This command counts the words in a file, using the
+C<wc -w> external command.
+
+On error this function returns -1.
+

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


@@ -1929,6 +2306,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