X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=b0a408db6ab2d2491ce2275c8ba554707497e0d4;hp=de05b55fb181b5056f6239e4c616d3ee0278a2a1;hb=6d6b7edd1102f8383643866bf358e494e0d518ef;hpb=86a53e17de672a79a994b905676b4566da9f072c

diff --git a/src/guestfs.pod b/src/guestfs.pod
index de05b55..b0a408d 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -550,10 +550,11 @@ device (I<not> the underlying encrypted block device).
 =head2 INSPECTION
 
 Libguestfs has APIs for inspecting an unknown disk image to find out
-if it contains operating systems.  (These APIs used to be in a
-separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
-version 1.5.3 the most frequently used part of this library has been
-rewritten in C and moved into the core code).
+if it contains operating systems, an install CD or a live CD.  (These
+APIs used to be in a separate Perl-only library called
+L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most frequently
+used part of this library has been rewritten in C and moved into the
+core code).
 
 Add all disks belonging to the unknown virtual machine and call
 L</guestfs_launch> in the usual way.
@@ -608,6 +609,25 @@ again.  (L</guestfs_inspect_list_applications> works a little
 differently from the other calls and does read the disks.  See
 documentation for that function for details).
 
+=head3 INSPECTING INSTALL DISKS
+
+Libguestfs (since 1.9.4) can detect some install disks, install
+CDs, live CDs and more.
+
+Call L</guestfs_inspect_get_format> to return the format of the
+operating system, which currently can be C<installed> (a regular
+operating system) or C<installer> (some sort of install disk).
+
+Further information is available about the operating system that can
+be installed using the regular inspection APIs like
+L</guestfs_inspect_get_product_name>,
+L</guestfs_inspect_get_major_version> etc.
+
+Some additional information specific to installer disks is also
+available from the L</guestfs_inspect_is_live>,
+L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
+calls.
+
 =head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
 
 Libguestfs can mount NTFS partitions.  It does this using the
@@ -717,7 +737,7 @@ See L<guestfs-ocaml(3)>.
 
 =item B<Perl>
 
-See L<Sys::Guestfs(3)>.
+See L<guestfs-perl(3)> and L<Sys::Guestfs(3)>.
 
 =item B<PHP>
 
@@ -952,6 +972,63 @@ For example:
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 
+=head2 ATTACHING TO RUNNING DAEMONS
+
+I<Note (1):> This is B<highly experimental> and has a tendency to eat
+babies.  Use with caution.
+
+I<Note (2):> This section explains how to attach to a running daemon
+from a low level perspective.  For most users, simply using virt tools
+such as L<guestfish(1)> with the I<--live> option will "just work".
+
+=head3 Using guestfs_set_attach_method
+
+By calling L</guestfs_set_attach_method> you can change how the
+library connects to the C<guestfsd> daemon in L</guestfs_launch>
+(read L</ARCHITECTURE> for some background).
+
+The normal attach method is C<appliance>, where a small appliance is
+created containing the daemon, and then the library connects to this.
+
+Setting attach method to C<unix:I<path>> (where I<path> is the path of
+a Unix domain socket) causes L</guestfs_launch> to connect to an
+existing daemon over the Unix domain socket.
+
+The normal use for this is to connect to a running virtual machine
+that contains a C<guestfsd> daemon, and send commands so you can read
+and write files inside the live virtual machine.
+
+=head3 Using guestfs_add_domain with live flag
+
+L</guestfs_add_domain> provides some help for getting the
+correct attach method.  If you pass the C<live> option to this
+function, then (if the virtual machine is running) it will
+examine the libvirt XML looking for a virtio-serial channel
+to connect to:
+
+ <domain>
+   ...
+   <devices>
+     ...
+     <channel type='unix'>
+       <source mode='bind' path='/path/to/socket'/>
+       <target type='virtio' name='org.libguestfs.channel.0'/>
+     </channel>
+     ...
+   </devices>
+ </domain>
+
+L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
+method to C<unix:/path/to/socket>.
+
+Some of the libguestfs tools (including guestfish) support a I<--live>
+option which is passed through to L</guestfs_add_domain> thus allowing
+you to attach to and modify live virtual machines.
+
+The virtual machine needs to have been set up beforehand so that it
+has the virtio-serial channel and so that guestfsd is running inside
+it.
+
 =head2 ABI GUARANTEE
 
 We guarantee the libguestfs ABI (binary interface), for public,
@@ -1727,8 +1804,9 @@ print these numbers in error messages or debugging messages.
 =head1 PRIVATE DATA AREA
 
 You can attach named pieces of private data to the libguestfs handle,
-and fetch them by name for the lifetime of the handle.  This is called
-the private data area and is only available from the C API.
+fetch them by name, and walk over them, for the lifetime of the
+handle.  This is called the private data area and is only available
+from the C API.
 
 To attach a named piece of data, use the following call:
 
@@ -1759,8 +1837,100 @@ caller must either free it before calling L</guestfs_close> or must
 set up a close callback to do it (see L</guestfs_set_close_callback>,
 and note that only one callback can be registered for a handle).
 
-The private data area is implemented using a hash table, and should be
-reasonably efficient for moderate numbers of keys.
+To walk over all entries, use these two functions:
+
+ void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
+
+ void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
+
+C<guestfs_first_private> returns the first key, pointer pair ("first"
+does not have any particular meaning -- keys are not returned in any
+defined order).  A pointer to the key is returned in C<*key_rtn> and
+the corresponding data pointer is returned from the function.  C<NULL>
+is returned if there are no keys stored in the handle.
+
+C<guestfs_next_private> returns the next key, pointer pair.  The
+return value of this function is also C<NULL> is there are no further
+entries to return.
+
+Notes about walking over entries:
+
+=over 4
+
+=item *
+
+You must not call C<guestfs_set_private> while walking over the
+entries.
+
+=item *
+
+The handle maintains an internal iterator which is reset when you call
+C<guestfs_first_private>.  This internal iterator is invalidated when
+you call C<guestfs_set_private>.
+
+=item *
+
+If you have set the data pointer associated with a key to C<NULL>, ie:
+
+ guestfs_set_private (g, key, NULL);
+
+then that C<key> is not returned when walking.
+
+=item *
+
+C<*key_rtn> is only valid until the next call to
+C<guestfs_first_private>, C<guestfs_next_private> or
+C<guestfs_set_private>.
+
+=back
+
+The following example code shows how to print all keys and data
+pointers that are associated with the handle C<g>:
+
+ const char *key;
+ void *data = guestfs_first_private (g, &key);
+ while (data != NULL)
+   {
+     printf ("key = %s, data = %p\n", key, data);
+     data = guestfs_next_private (g, &key);
+   }
+
+More commonly you are only interested in keys that begin with an
+application-specific prefix C<foo_>.  Modify the loop like so:
+
+ const char *key;
+ void *data = guestfs_first_private (g, &key);
+ while (data != NULL)
+   {
+     if (strncmp (key, "foo_", strlen ("foo_")) == 0)
+       printf ("key = %s, data = %p\n", key, data);
+     data = guestfs_next_private (g, &key);
+   }
+
+If you need to modify keys while walking, then you have to jump back
+to the beginning of the loop.  For example, to delete all keys
+prefixed with C<foo_>:
+
+  const char *key;
+  void *data;
+ again:
+  data = guestfs_first_private (g, &key);
+  while (data != NULL)
+    {
+      if (strncmp (key, "foo_", strlen ("foo_")) == 0)
+        {
+          guestfs_set_private (g, key, NULL);
+          /* note that 'key' pointer is now invalid, and so is
+             the internal iterator */
+          goto again;
+        }
+      data = guestfs_next_private (g, &key);
+    }
+
+Note that the above loop is guaranteed to terminate because the keys
+are being deleted, but other manipulations of keys within the loop
+might not terminate unless you also maintain an indication of which
+keys have been visited.
 
 =begin html
 
@@ -2359,7 +2529,9 @@ C API example code.
 
 =item C<fish>
 
-L<guestfish(1)>, the command-line shell.
+L<guestfish(1)>, the command-line shell, and various shell scripts
+built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>,
+L<virt-tar-in(1)>, L<virt-tar-out(1)>.
 
 =item C<fuse>
 
@@ -2380,6 +2552,10 @@ Some "phony" guest images which we test against.
 
 L<virt-inspector(1)>, the virtual machine image inspector.
 
+=item C<logo>
+
+Logo used on the website.  The fish is called Arthur by the way.
+
 =item C<m4>
 
 M4 macros used by autoconf.
@@ -2475,12 +2651,13 @@ has the same effect as calling C<guestfs_set_trace (g, 1)>.
 
 =item TMPDIR
 
-Location of temporary directory, defaults to C</tmp>.
+Location of temporary directory, defaults to C</tmp> except for the
+cached supermin appliance which defaults to C</var/tmp>.
 
 If libguestfs was compiled to use the supermin appliance then the
 real appliance is cached in this directory, shared between all
 handles belonging to the same EUID.  You can use C<$TMPDIR> to
-configure another directory to use in case C</tmp> is not large
+configure another directory to use in case C</var/tmp> is not large
 enough.
 
 =back
@@ -2494,6 +2671,8 @@ L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<virt-cat(1)>,
+L<virt-copy-in(1)>,
+L<virt-copy-out(1)>,
 L<virt-df(1)>,
 L<virt-edit(1)>,
 L<virt-filesystems(1)>,
@@ -2504,6 +2683,8 @@ L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
 L<virt-tar(1)>,
+L<virt-tar-in(1)>,
+L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,