Implement upload and download commands.

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

diff --git a/perl/lib/Sys/Guestfs.pm b/perl/lib/Sys/Guestfs.pm
index a351d57..bd8da0f 100644 (file)
--- a/perl/lib/Sys/Guestfs.pm
+++ b/perl/lib/Sys/Guestfs.pm
@@ -330,7 +330,7 @@ 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<$h-E<gt>read_file>
+as end of string).  For those you need to use the C<$h-E<gt>download>
 function which has a more complex interface.
 
 Because of the message protocol, there is a transfer limit 
@@ -389,6 +389,15 @@ The first character of C<param> string must be a C<-> (dash).
 
 C<value> can be NULL.
 
+=item $h->download ($remotefilename, $filename);
+
+Download file C<remotefilename> and save it as C<filename>
+on the local machine.
+
+C<filename> can also be a named pipe.
+
+See also C<$h-E<gt>upload>, C<$h-E<gt>cat>.
+
 =item $existsflag = $h->exists ($path);
 
 This returns C<true> if and only if there is a file, directory
@@ -417,10 +426,31 @@ Return the current search path.
 This is always non-NULL.  If it wasn't set already, then this will
 return the default path.
 
+=item $state = $h->get_state ();
+
+This returns the current state as an opaque integer.  This is
+only useful for printing debug and internal error messages.
+
+For more information on states, see L<guestfs(3)>.
+
 =item $verbose = $h->get_verbose ();
 
 This returns the verbose messages flag.
 
+=item $busy = $h->is_busy ();
+
+This returns true iff this handle is busy processing a command
+(in the C<BUSY> state).
+
+For more information on states, see L<guestfs(3)>.
+
+=item $config = $h->is_config ();
+
+This returns true iff this handle is being configured
+(in the C<CONFIG> state).
+
+For more information on states, see L<guestfs(3)>.
+
 =item $dirflag = $h->is_dir ($path);
 
 This returns C<true> if and only if there is a directory
@@ -437,6 +467,20 @@ other objects like directories.
 
 See also C<$h-E<gt>stat>.
 
+=item $launching = $h->is_launching ();
+
+This returns true iff this handle is launching the subprocess
+(in the C<LAUNCHING> state).
+
+For more information on states, see L<guestfs(3)>.
+
+=item $ready = $h->is_ready ();
+
+This returns true iff this handle is ready to accept commands
+(in the C<READY> state).
+
+For more information on states, see L<guestfs(3)>.
+
 =item $h->kill_subprocess ();
 
 This kills the qemu subprocess.  You should never need to call this.
@@ -613,6 +657,13 @@ If C<autosync> is true, this enables autosync.  Libguestfs will make a
 best effort attempt to run C<$h-E<gt>sync> when the handle is closed
 (also if the program exits without closing handles).
 
+=item $h->set_busy ();
+
+This sets the state to C<BUSY>.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+
 =item $h->set_path ($path);
 
 Set the path that libguestfs searches for kernel and initrd.img.
@@ -625,6 +676,13 @@ must make sure it remains valid for the lifetime of the handle.
 
 Setting C<path> to C<NULL> restores the default path.
 
+=item $h->set_ready ();
+
+This sets the state to C<READY>.  This is only used when implementing
+actions using the low-level API.
+
+For more information on states, see L<guestfs(3)>.
+
 =item $h->set_verbose ($verbose);
 
 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
@@ -707,6 +765,15 @@ This unmounts all mounted filesystems.
 
 Some internal mounts are not unmounted by this call.
 
+=item $h->upload ($filename, $remotefilename);
+
+Upload local file C<filename> to C<remotefilename> on the
+filesystem.
+
+C<filename> can also be a named pipe.
+
+See also C<$h-E<gt>download>.
+
 =item $h->vgcreate ($volgroup, \@physvols);
 
 This creates an LVM volume group called C<volgroup>