Generated code for df / df-h.

[libguestfs.git] / perl / lib / Sys / Guestfs.pm

diff --git a/perl/lib/Sys/Guestfs.pm b/perl/lib/Sys/Guestfs.pm
index 445d9b8..69ffe8b 100644 (file)
--- a/perl/lib/Sys/Guestfs.pm
+++ b/perl/lib/Sys/Guestfs.pm
@@ -115,7 +115,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


@@ -432,7 +432,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<$h-E<gt>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.


@@ -461,6 +463,8 @@ FTP.
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 

+See also: C<$h-E<gt>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.


@@ -496,6 +500,23 @@ There is no comprehensive help for this command.  You have
 to look at the file C<daemon/debug.c> in the libguestfs source
 to find out what you can do.
 
 to look at the file C<daemon/debug.c> in the libguestfs source
 to find out what you can do.
 

+=item $output = $h->df ();
+
+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.
+
+=item $output = $h->df_h ();
+
+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.
+

 =item $kmsgs = $h->dmesg ();
 
 This returns the kernel messages (C<dmesg> output) from
 =item $kmsgs = $h->dmesg ();
 
 This returns the kernel messages (C<dmesg> output) from


@@ -672,11 +693,47 @@ For more information on states, see L<guestfs(3)>.
 
 This returns the verbose messages flag.
 
 
 This returns the verbose messages flag.
 

+=item @paths = $h->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.
+

 =item $h->grub_install ($root, $device);
 
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 
 =item $h->grub_install ($root, $device);
 
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 

+=item @lines = $h->head ($path);
+
+This command returns up to the first 10 lines of a file as
+a list of strings.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+
+=item @lines = $h->head_n ($nrlines, $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.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+

 =item $dump = $h->hexdump ($path);
 
 This runs C<hexdump -C> on the given C<path>.  The result is
 =item $dump = $h->hexdump ($path);
 
 This runs C<hexdump -C> on the given C<path>.  The result is


@@ -835,6 +892,27 @@ 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.
 

+=item $dir = $h->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)>
+

 =item $h->mkfs ($fstype, $device);
 
 This creates a filesystem on C<device> (usually a partition
 =item $h->mkfs ($fstype, $device);
 
 This creates a filesystem on C<device> (usually a partition


@@ -889,6 +967,20 @@ 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.
 

+=item $status = $h->ntfs_3g_probe ($rw, $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.
+

 =item $h->ping_daemon ();
 
 This is a test probe into the guestfs daemon running inside
 =item $h->ping_daemon ();
 
 This is a test probe into the guestfs daemon running inside


@@ -968,6 +1060,38 @@ command.
 
 Remove the single directory C<path>.
 
 
 Remove the single directory C<path>.
 

+=item $h->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>.
+
+=item $h->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.
+
+=item $h->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<$h-E<gt>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.
+

 =item $h->set_append ($append);
 
 This function is used to add additional options to the
 =item $h->set_append ($append);
 
 This function is used to add additional options to the


@@ -1077,7 +1201,7 @@ See also: C<$h-E<gt>sfdisk_l>, C<$h-E<gt>sfdisk_N>
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 
 B<This command is dangerous.  Without careful use you
 can easily destroy all your data>.
 

-=item $h->sfdisk_N ($device, $n, $cyls, $heads, $sectors, $line);
+=item $h->sfdisk_N ($device, $partnum, $cyls, $heads, $sectors, $line);

 
 This runs L<sfdisk(8)> option to modify just the single
 partition C<n> (note: C<n> counts from 1).
 
 This runs L<sfdisk(8)> option to modify just the single
 partition C<n> (note: C<n> counts from 1).


@@ -1111,6 +1235,28 @@ 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.
 

+=item $output = $h->sh ($command);
+
+This call runs a command from the guest filesystem via the
+guest's C</bin/sh>.
+
+This is like C<$h-E<gt>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<$h-E<gt>command> apply to this call.
+
+=item @lines = $h->sh_lines ($command);
+
+This is the same as C<$h-E<gt>sh>, but splits the result
+into a list of lines.
+
+See also: C<$h-E<gt>command_lines>
+

 =item $h->sleep ($secs);
 
 Sleep for C<secs> seconds.
 =item $h->sleep ($secs);
 
 Sleep for C<secs> seconds.


@@ -1162,6 +1308,29 @@ underlying disk image.
 You should always call this if you have modified a disk image, before
 closing the handle.
 
 You should always call this if you have modified a disk image, before
 closing the handle.
 

+=item @lines = $h->tail ($path);
+
+This command returns up to the last 10 lines of a file as
+a list of strings.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+
+=item @lines = $h->tail_n ($nrlines, $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.
+
+Because of the message protocol, there is a transfer limit 
+of somewhere between 2MB and 4MB.  To transfer large files you should use
+FTP.
+

 =item $h->tar_in ($tarfile, $directory);
 
 This command uploads and unpacks local file C<tarfile> (an
 =item $h->tar_in ($tarfile, $directory);
 
 This command uploads and unpacks local file C<tarfile> (an


@@ -1285,6 +1454,21 @@ using L<qemu(1)>.
 You should call this after C<$h-E<gt>launch> to wait for the launch
 to complete.
 
 You should call this after C<$h-E<gt>launch> to wait for the launch
 to complete.
 

+=item $chars = $h->wc_c ($path);
+
+This command counts the characters in a file, using the
+C<wc -c> external command.
+
+=item $lines = $h->wc_l ($path);
+
+This command counts the lines in a file, using the
+C<wc -l> external command.
+
+=item $words = $h->wc_w ($path);
+
+This command counts the words in a file, using the
+C<wc -w> external command.
+

 =item $h->write_file ($path, $content, $size);
 
 This call creates a file called C<path>.  The contents of the
 =item $h->write_file ($path, $content, $size);
 
 This call creates a file called C<path>.  The contents of the


@@ -1312,6 +1496,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<$h-E<gt>scrub_device>.
+

 =item $h->zerofree ($device);
 
 This runs the I<zerofree> program on C<device>.  This program
 =item $h->zerofree ($device);
 
 This runs the I<zerofree> program on C<device>.  This program