Test the 'command' and 'command_lines' functions thoroughly.

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

diff --git a/perl/lib/Sys/Guestfs.pm b/perl/lib/Sys/Guestfs.pm
index 116f716..001fa88 100644 (file)
--- a/perl/lib/Sys/Guestfs.pm
+++ b/perl/lib/Sys/Guestfs.pm
@@ -405,6 +405,13 @@ 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).
 
 Subsequent elements are parameters.  The list must be
 non-empty (ie. must contain a program name).
 

+The return value is anything printed to I<stdout> by
+the command.
+
+If the command returns a non-zero exit status, then
+this function returns an error message.  The error message
+string is the content of I<stderr> from the command.
+

 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the
 The C<$PATH> environment variable will contain at least
 C</usr/bin> and C</bin>.  If you require a program from
 another location, you should provide the full path in the


@@ -416,11 +423,19 @@ correct places.  It is the caller's responsibility to ensure
 all filesystems that are needed are mounted at the right
 locations.
 
 all filesystems that are needed are mounted at the right
 locations.
 

+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->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of lines.
 
 =item @lines = $h->command_lines (\@arguments);
 
 This is the same as C<$h-E<gt>command>, but splits the
 result into a list of 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.
+

 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters
 =item $h->config ($qemuparam, $qemuvalue);
 
 This can be used to add arbitrary qemu command line parameters


@@ -484,6 +499,14 @@ Setting C<whattodrop> to 3 should drop everything.
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 
 This automatically calls L<sync(2)> before the operation,
 so that the maximum guest memory is freed.
 

+=item $h->end_busy ();
+
+This sets the state to C<READY>, or if in C<CONFIG> then it leaves the
+state as is.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+

 =item $equality = $h->equal ($file1, $file2);
 
 This compares the two files C<file1> and C<file2> and returns
 =item $equality = $h->equal ($file1, $file2);
 
 This compares the two files C<file1> and C<file2> and returns


@@ -582,6 +605,15 @@ This returns the verbose messages flag.
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 
 This command installs GRUB (the Grand Unified Bootloader) on
 C<device>, with the root directory being C<root>.
 

+=item $dump = $h->hexdump ($path);
+
+This runs C<hexdump -C> on the given C<path>.  The result is
+the human-readable, canonical hex dump of the file.
+
+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 $busy = $h->is_busy ();
 
 This returns true iff this handle is busy processing a command
 =item $busy = $h->is_busy ();
 
 This returns true iff this handle is busy processing a command


@@ -958,6 +990,31 @@ C<path> should be a file or directory in the mounted file system
 
 This is the same as the C<statvfs(2)> system call.
 
 
 This is the same as the C<statvfs(2)> system call.
 

+=item @stringsout = $h->strings ($path);
+
+This runs the L<strings(1)> command on a file and returns
+the list of printable strings found.
+
+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 @stringsout = $h->strings_e ($encoding, $path);
+
+This is like the C<$h-E<gt>strings> command, but allows you to
+specify the encoding.
+
+See the L<strings(1)> manpage for the full list of encodings.
+
+Commonly useful encodings are C<l> (lower case L) which will
+show strings inside Windows/x86 files.
+
+The returned strings are transcoded to UTF-8.
+
+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->sync ();
 
 This syncs the disk, so that any writes are flushed through to the
 =item $h->sync ();
 
 This syncs the disk, so that any writes are flushed through to the


@@ -1076,6 +1133,11 @@ As a special case, if C<size> is C<0>
 then the length is calculated using C<strlen> (so in this case
 the content cannot contain embedded ASCII NULs).
 
 then the length is calculated using C<strlen> (so in this case
 the content cannot contain embedded ASCII NULs).
 

+I<NB.> Owing to a bug, writing content containing ASCII NUL
+characters does I<not> work, even if the length is specified.
+We hope to resolve this bug in a future version.  In the meantime
+use C<$h-E<gt>upload>.
+

 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.