Generated code for mknod, mkfifo, mknod_b, mknod_c, umask.

[libguestfs.git] / guestfs-actions.pod

diff --git a/guestfs-actions.pod b/guestfs-actions.pod
index d35d1aa..50eba95 100644 (file)
--- a/guestfs-actions.pod
+++ b/guestfs-actions.pod
@@ -30,7 +30,7 @@ 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
 
 Note that this call checks for the existence of C<filename>.  This
 stops you from specifying other types of drive which are supported


@@ -614,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);


@@ -662,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,


@@ -841,6 +885,22 @@ C<device>.
 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_get_memsize
+
+ int guestfs_get_memsize (guestfs_h *handle);
+
+This gets the memory size in megabytes allocated to the
+qemu subprocess.
+
+If C<guestfs_set_memsize> was not called
+on this handle, and if C<LIBGUESTFS_MEMSIZE> was not set,
+then this returns the compiled-in default value for memsize.
+
+For more information on the architecture of libguestfs,
+see L<guestfs(3)>.
+
+On error this function returns -1.
+

 =head2 guestfs_get_path
 
  const char *guestfs_get_path (guestfs_h *handle);
 =head2 guestfs_get_path
 
  const char *guestfs_get_path (guestfs_h *handle);


@@ -915,6 +975,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,


@@ -930,6 +1028,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);


@@ -1191,6 +1308,45 @@ 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_mkfifo
+
+ int guestfs_mkfifo (guestfs_h *handle,
+               int mode,
+               const char *path);
+
+This call creates a FIFO (named pipe) called C<path> with
+mode C<mode>.  It is just a convenient wrapper around
+C<guestfs_mknod>.
+
+This function returns 0 on success or -1 on error.
+

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


@@ -1203,6 +1359,81 @@ example C<ext3>.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_mknod
+
+ int guestfs_mknod (guestfs_h *handle,
+               int mode,
+               int devmajor,
+               int devminor,
+               const char *path);
+
+This call creates block or character special devices, or
+named pipes (FIFOs).
+
+The C<mode> parameter should be the mode, using the standard
+constants.  C<devmajor> and C<devminor> are the
+device major and minor numbers, only used when creating block
+and character special devices.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mknod_b
+
+ int guestfs_mknod_b (guestfs_h *handle,
+               int mode,
+               int devmajor,
+               int devminor,
+               const char *path);
+
+This call creates a block device node called C<path> with
+mode C<mode> and device major/minor C<devmajor> and C<devminor>.
+It is just a convenient wrapper around C<guestfs_mknod>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mknod_c
+
+ int guestfs_mknod_c (guestfs_h *handle,
+               int mode,
+               int devmajor,
+               int devminor,
+               const char *path);
+
+This call creates a char device node called C<path> with
+mode C<mode> and device major/minor C<devmajor> and C<devminor>.
+It is just a convenient wrapper around C<guestfs_mknod>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mkswap
+
+ int guestfs_mkswap (guestfs_h *handle,
+               const char *device);
+
+Create a swap partition on C<device>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mkswap_L
+
+ int guestfs_mkswap_L (guestfs_h *handle,
+               const char *label,
+               const char *device);
+
+Create a swap partition on C<device> with label C<label>.
+
+This function returns 0 on success or -1 on error.
+
+=head2 guestfs_mkswap_U
+
+ int guestfs_mkswap_U (guestfs_h *handle,
+               const char *uuid,
+               const char *device);
+
+Create a swap partition on C<device> with UUID C<uuid>.
+
+This function returns 0 on success or -1 on error.
+

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


@@ -1228,6 +1459,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,


@@ -1448,6 +1691,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,


@@ -1521,6 +1811,24 @@ to return the existing UUID of a filesystem.
 
 This function returns 0 on success or -1 on error.
 
 
 This function returns 0 on success or -1 on error.
 

+=head2 guestfs_set_memsize
+
+ int guestfs_set_memsize (guestfs_h *handle,
+               int memsize);
+
+This sets the memory size in megabytes allocated to the
+qemu subprocess.  This only has any effect if called before
+C<guestfs_launch>.
+
+You can also change this by setting the environment
+variable C<LIBGUESTFS_MEMSIZE> before the handle is
+created.
+
+For more information on the architecture of libguestfs,
+see L<guestfs(3)>.
+
+This function returns 0 on success or -1 on error.
+

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


@@ -1615,7 +1923,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,


@@ -1799,6 +2107,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,


@@ -1881,6 +2227,25 @@ The array of strings will always have length C<2n+1>, where
 C<n> keys and values alternate, followed by the trailing NULL entry.
 I<The caller must free the strings and the array after use>.
 
 C<n> keys and values alternate, followed by the trailing NULL entry.
 I<The caller must free the strings and the array after use>.
 

+=head2 guestfs_umask
+
+ int guestfs_umask (guestfs_h *handle,
+               int mask);
+
+This function sets the mask used for creating new files and
+device nodes to C<mask & 0777>.
+
+Typical umask values would be C<022> which creates new files
+with permissions like "-rw-r--r--" or "-rwxr-xr-x", and
+C<002> which creates new files with permissions like
+"-rw-rw-r--" or "-rwxrwxr-x".
+
+See also L<umask(2)>, C<guestfs_mknod>, C<guestfs_mkdir>.
+
+This call returns the previous umask.
+
+On error this function returns -1.
+

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


@@ -2014,6 +2379,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,


@@ -2051,6 +2446,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