X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs-actions.pod;h=f89ae26b75b263ced117bba440b703a32829e994;hp=0eb24838a5110c9f6b8b8c81afda4716d2eee98c;hb=8e570870f577ff0c3db074f88924633b559af5d4;hpb=8d0068a752ee8e6bc223de5cb7cac5d190a8855e

diff --git a/guestfs-actions.pod b/guestfs-actions.pod
index 0eb2483..f89ae26 100644
--- a/guestfs-actions.pod
+++ b/guestfs-actions.pod
@@ -1,6 +1,85 @@
+=head2 guestfs_cat
+
+ char *guestfs_cat (guestfs_h *handle,
+		const char *path);
+
+Return the contents of the file named C<path>.
+
+Note that this function cannot correctly handle binary files
+(specifically, files containing C<\0> character which is treated
+as end of string).  For those you need to use the C<guestfs_read_file>
+function which has a more complex interface.
+
+This function returns a string or NULL on error.
+I<The caller must free the returned string 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_list_devices
+
+ char **guestfs_list_devices (guestfs_h *handle);
+
+List all the block devices.
+
+The full block device names are returned, eg. C</dev/sda>
+
+
+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_list_partitions
+
+ char **guestfs_list_partitions (guestfs_h *handle);
+
+List all the partitions detected on all block devices.
+
+The full partition device names are returned, eg. C</dev/sda1>
+
+This does not return logical volumes.  For that you will need to
+call C<guestfs_lvs>.
+
+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_ll
+
+ char *guestfs_ll (guestfs_h *handle,
+		const char *directory);
+
+List the files in C<directory> (relative to the root directory,
+there is no cwd) in the format of 'ls -la'.
+
+This command is mostly useful for interactive sessions.  It
+is I<not> intended that you try to parse the output string.
+
+This function returns a string or NULL on error.
+I<The caller must free the returned string after use>.
+
+=head2 guestfs_ls
+
+ char **guestfs_ls (guestfs_h *handle,
+		const char *directory);
+
+List the files in C<directory> (relative to the root directory,
+there is no cwd).  The '.' and '..' entries are not returned, but
+hidden files are shown.
+
+This command is mostly useful for interactive sessions.  Programs
+should probably use C<guestfs_readdir> instead.
+
+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_mount
 
- int guestfs_mount (guestfs_h *handle, const char *device, const char *mountpoint);
+ int guestfs_mount (guestfs_h *handle,
+		const char *device,
+		const char *mountpoint);
 
 Mount a guest disk at a position in the filesystem.  Block devices
 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
@@ -13,6 +92,14 @@ first be mounted on C</> before others can be mounted.  Other
 filesystems can only be mounted on directories which already
 exist.
 
+The mounted filesystem is writable, if we have sufficient permissions
+on the underlying device.
+
+The filesystem options C<sync> and C<noatime> are set with this
+call, in order to improve reliability.
+
+This function returns 0 on success or -1 on error.
+
 =head2 guestfs_sync
 
  int guestfs_sync (guestfs_h *handle);
@@ -23,11 +110,16 @@ underlying disk image.
 You should always call this if you have modified a disk image, before
 calling C<guestfs_close>.
 
+This function returns 0 on success or -1 on error.
+
 =head2 guestfs_touch
 
- int guestfs_touch (guestfs_h *handle, const char *path);
+ int guestfs_touch (guestfs_h *handle,
+		const char *path);
 
 Touch acts like the L<touch(1)> command.  It can be used to
-update the filesystems on a file, or, if the file does not exist,
+update the timestamps on a file, or, if the file does not exist,
 to create a new zero-length file.
 
+This function returns 0 on success or -1 on error.
+