New APIs: mount-local, mount-local-run, umount-local (FUSE support in the API).

Add FUSE support directly to the API.  Instead of needing to use the
external 'guestmount' command, you can mount the libguestfs filesystem
space on a local mountpoint using an API call from any language.

Note that although mount-local-run is marked as Cancellable, the
current implementation does not support it, but it would be relatively
simple to add it.

1 files changed, 52 insertions, 0 deletions

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 531d123b..05f5c746 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -233,6 +233,10 @@ language bindings turn these errors into exceptions).
 File writes are affected by the per-handle umask, set by calling
 L</guestfs_umask> and defaulting to 022.  See L</UMASK>.
 
+Since libguestfs 1.18, it is possible to mount the libguestfs
+filesystem on a local directory, subject to some restrictions.  See
+L</MOUNT LOCAL> below.
+
 =head2 PARTITIONING
 
 Libguestfs contains API calls to read, create and modify partition
@@ -562,6 +566,54 @@ Then close the mapper device by calling
 L</guestfs_luks_close> on the C</dev/mapper/mapname>
 device (I<not> the underlying encrypted block device).
 
+=head2 MOUNT LOCAL
+
+In libguestfs E<ge> 1.18, it is possible to mount the libguestfs
+filesystem on a local directory and access it using ordinary POSIX
+calls and programs.
+
+Availability of this is subject to a number of restrictions: it
+requires FUSE (the Filesystem in USErspace), and libfuse must also
+have been available when libguestfs was compiled.  FUSE may require
+that a kernel module is loaded, and it may be necessary to add the
+current user to a special C<fuse> group.  See the documentation for
+your distribution and L<http://fuse.sf.net> for further information.
+
+The call to mount the libguestfs filesystem on a local directory is
+L</guestfs_mount_local> (q.v.) followed by L</guestfs_mount_local_run>.
+The latter does not return until you unmount the filesystem.
+The reason is that the call enters the FUSE main loop and processes
+kernel requests, turning them into libguestfs calls.  An alternative
+design would have been to create a background thread to do this, but
+libguestfs doesn't require pthreads.  This way is also more flexible:
+for example the user can create another thread for
+L</guestfs_mount_local_run>.
+
+L</guestfs_mount_local> needs a certain amount of time to set up the
+mountpoint.  The mountpoint is not ready to use until the call
+returns.  At this point, accesses to the filesystem will block
+until the main loop is entered (ie. L</guestfs_mount_local_run>).
+So if you need to start another process to access the filesystem,
+put the fork between L</guestfs_mount_local> and
+L</guestfs_mount_local_run>.
+
+=head3 MOUNT LOCAL COMPATIBILITY
+
+Since local mounting was only added in libguestfs 1.18, and may not
+be available even in these builds, you should consider writing code
+so that it doesn't depend on this feature, and can fall back to
+using libguestfs file system calls.
+
+If libguestfs was compiled without support for L</guestfs_mount_local>
+then calling it will return an error with errno set to C<ENOTSUP> (see
+L</guestfs_last_errno>).
+
+=head3 MOUNT LOCAL PERFORMANCE
+
+Libguestfs on top of FUSE performs quite poorly.  For best performance
+do not use it.  Use ordinary libguestfs filesystem calls, upload,
+download etc. instead.
+
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out