tests: Split images -> tests/data + tests/guests

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index a847a5f..f7740b6 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -42,8 +42,8 @@ FUSE.
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,

-Java, PHP, Haskell or C#).  You can also use it from shell scripts or the
-command line.
+Java, PHP, Erlang, Haskell or C#).  You can also use it from shell
+scripts or the command line.

 
 You don't need to be root to use libguestfs, although obviously you do
 need enough permissions to access the disk images.
 
 You don't need to be root to use libguestfs, although obviously you do
 need enough permissions to access the disk images.


@@ -313,21 +313,36 @@ in the table below.
 
 =item B<file> to B<file>
 
 
 =item B<file> to B<file>
 

-Use L</guestfs_cp> to copy a single file, or
-L</guestfs_cp_a> to copy directories recursively.
+Use L</guestfs_cp> to copy a single file, or L</guestfs_cp_a> to copy
+directories recursively.

 
 

-=item B<file or device> to B<file or device>
+To copy part of a file (offset and size) use
+L</guestfs_copy_file_to_file>.

 
 

-Use L</guestfs_dd> which efficiently uses L<dd(1)>
-to copy between files and devices in the guest.
+=item B<file> to B<device>
+
+=item B<device> to B<file>
+
+=item B<device> to B<device>
+
+Use L</guestfs_copy_file_to_device>, L</guestfs_copy_device_to_file>,
+or L</guestfs_copy_device_to_device>.

 
 Example: duplicate the contents of an LV:
 
 
 Example: duplicate the contents of an LV:
 

- guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy");
+ guestfs_copy_device_to_device (g,
+         "/dev/VG/Original", "/dev/VG/Copy",
+         /* -1 marks the end of the list of optional parameters */
+         -1);

 
 The destination (C</dev/VG/Copy>) must be at least as large as the
 
 The destination (C</dev/VG/Copy>) must be at least as large as the

-source (C</dev/VG/Original>).  To copy less than the whole
-source device, use L</guestfs_copy_size>.
+source (C</dev/VG/Original>).  To copy less than the whole source
+device, use the optional C<size> parameter:
+
+ guestfs_copy_device_to_device (g,
+         "/dev/VG/Original", "/dev/VG/Copy",
+         GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000,
+         -1);

 
 =item B<file on the host> to B<file or device>
 
 
 =item B<file on the host> to B<file or device>
 


@@ -354,7 +369,7 @@ doing:
 
  guestfs_download (g, filename, "/dev/stdout");
 
 
  guestfs_download (g, filename, "/dev/stdout");
 

-and you can write tar output to a pipe C<fd> by doing:
+and you can write tar output to a file descriptor C<fd> by doing:

 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
 
  char devfd[64];
  snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);


@@ -641,16 +656,15 @@ you might find a Windows configuration file referring to a path like
 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
 that directory might be referred to as C</WINDOWS/System32>.
 
 C<c:\windows\system32>.  When the filesystem is mounted in libguestfs,
 that directory might be referred to as C</WINDOWS/System32>.
 

-Drive letter mappings are outside the scope of libguestfs.  You have
-to use libguestfs to read the appropriate Windows Registry and
-configuration files, to determine yourself how drives are mapped (see
-also L<hivex(3)> and L<virt-inspector(1)>).
+Drive letter mappings can be found using inspection
+(see L</INSPECTION> and L</guestfs_inspect_get_drive_mappings>)

 
 

-Replacing backslash characters with forward slash characters is also
-outside the scope of libguestfs, but something that you can easily do.
+Dealing with separator characters (backslash vs forward slash) is
+outside the scope of libguestfs, but usually a simple character
+replacement will work.

 
 

-Where we can help is in resolving the case insensitivity of paths.
-For this, call L</guestfs_case_sensitive_path>.
+To resolve the case insensitivity of paths, call
+L</guestfs_case_sensitive_path>.

 
 =head3 ACCESSING THE WINDOWS REGISTRY
 
 
 =head3 ACCESSING THE WINDOWS REGISTRY
 


@@ -720,6 +734,10 @@ used.
 The C# bindings are highly experimental.  Please read the warnings
 at the top of C<csharp/Libguestfs.cs>.
 
 The C# bindings are highly experimental.  Please read the warnings
 at the top of C<csharp/Libguestfs.cs>.
 

+=item B<Erlang>
+
+See L<guestfs-erlang(3)>.
+

 =item B<Haskell>
 
 This is the only language binding that is working but incomplete.
 =item B<Haskell>
 
 This is the only language binding that is working but incomplete.


@@ -729,7 +747,7 @@ and we are looking for help to complete this binding.
 =item B<Java>
 
 Full documentation is contained in the Javadoc which is distributed
 =item B<Java>
 
 Full documentation is contained in the Javadoc which is distributed

-with libguestfs.
+with libguestfs.  For examples, see L<guestfs-java(3)>.

 
 =item B<OCaml>
 
 
 =item B<OCaml>
 


@@ -776,6 +794,9 @@ them.
 
 =item Autosync / forgetting to sync.
 
 
 =item Autosync / forgetting to sync.
 

+I<Update:> Autosync is enabled by default for all API users starting
+from libguestfs 1.5.24.  This section only applies to older versions.
+

 When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:
 When modifying a filesystem from C or another language, you B<must>
 unmount all filesystems and call L</guestfs_sync> explicitly before
 you close the libguestfs handle.  You can also call:


@@ -794,11 +815,11 @@ Note that in L<guestfish(3)> autosync is the default.  So quick and
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this very puzzling if you are trying to debug a problem.
 
 dirty guestfish scripts that forget to sync will work just fine, which
 can make this very puzzling if you are trying to debug a problem.
 

-Update: Autosync is enabled by default for all API users starting from
-libguestfs 1.5.24.
-

 =item Mount option C<-o sync> should not be the default.
 
 =item Mount option C<-o sync> should not be the default.
 

+I<Update:> L</guestfs_mount> no longer adds any options starting
+from libguestfs 1.13.16.  This section only applies to older versions.
+

 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
 implicitly.  However C<-o sync> does not add any reliability benefit,
 but does have a very large performance impact.
 If you use L</guestfs_mount>, then C<-o sync,noatime> are added
 implicitly.  However C<-o sync> does not add any reliability benefit,
 but does have a very large performance impact.


@@ -880,29 +901,6 @@ representation.  Also consider how it might work in guestfish.
 
 =back
 
 
 =back
 

-=head2 PROTOCOL LIMITS
-
-Internally libguestfs uses a message-based protocol to pass API calls
-and their responses to and from a small "appliance" (see L</INTERNALS>
-for plenty more detail about this).  The maximum message size used by
-the protocol is slightly less than 4 MB.  For some API calls you may
-need to be aware of this limit.  The API calls which may be affected
-are individually documented, with a link back to this section of the
-documentation.
-
-A simple call such as L</guestfs_cat> returns its result (the file
-data) in a simple string.  Because this string is at some point
-internally encoded as a message, the maximum size that it can return
-is slightly under 4 MB.  If the requested file is larger than this
-then you will get an error.
-
-In order to transfer large files into and out of the guest filesystem,
-you need to use particular calls that support this.  The sections
-L</UPLOADING> and L</DOWNLOADING> document how to do this.
-
-You might also consider mounting the disk image using our FUSE
-filesystem support (L<guestmount(1)>).
-

 =head2 KEYS AND PASSPHRASES
 
 Certain libguestfs calls take a parameter that contains sensitive key
 =head2 KEYS AND PASSPHRASES
 
 Certain libguestfs calls take a parameter that contains sensitive key


@@ -972,6 +970,29 @@ For example:
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 
 Note that libguestfs also calls qemu with the -help and -version
 options in order to determine features.
 

+Wrappers can also be used to edit the options passed to qemu.  In the
+following example, the C<-machine ...> option (C<-machine> and the
+following argument) are removed from the command line and replaced
+with C<-machine pc,accel=tcg>.  The while loop iterates over the
+options until it finds the right one to remove, putting the remaining
+options into the C<args> array.
+
+ #!/bin/bash -
+ 
+ i=0
+ while [ $# -gt 0 ]; do
+     case "$1" in
+     -machine)
+         shift 2;;
+     *)
+         args[i]="$1"
+         (( i++ ))
+         shift ;;
+     esac
+ done
+ 
+ exec qemu-kvm -machine pc,accel=tcg "${args[@]}"
+

 =head2 ATTACHING TO RUNNING DAEMONS
 
 I<Note (1):> This is B<highly experimental> and has a tendency to eat
 =head2 ATTACHING TO RUNNING DAEMONS
 
 I<Note (1):> This is B<highly experimental> and has a tendency to eat


@@ -1309,7 +1330,7 @@ Create a handle by calling L</guestfs_create>.  Call L</guestfs_close>
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section
 to free the handle and release all resources used.
 
 For information on using multiple handles and threads, see the section

-L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> above.

 
 =head2 guestfs_create
 
 
 =head2 guestfs_create
 


@@ -1317,15 +1338,16 @@ L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
 
 Create a connection handle.
 
 
 Create a connection handle.
 

-You have to call L</guestfs_add_drive_opts> (or one of the equivalent
-calls) on the handle at least once.
+On success this returns a non-NULL pointer to a handle.  On error it
+returns NULL.

 
 

-This function returns a non-NULL pointer to a handle on success or
-NULL on error.
+You have to "configure" the handle after creating it.  This includes
+calling L</guestfs_add_drive_opts> (or one of the equivalent calls) on
+the handle at least once.

 
 After configuring the handle, you have to call L</guestfs_launch>.
 
 
 After configuring the handle, you have to call L</guestfs_launch>.
 

-You may also want to configure error handling for the handle.  See
+You may also want to configure error handling for the handle.  See the

 L</ERROR HANDLING> section below.
 
 =head2 guestfs_close
 L</ERROR HANDLING> section below.
 
 =head2 guestfs_close


@@ -1334,6 +1356,12 @@ L</ERROR HANDLING> section below.
 
 This closes the connection handle and frees up all resources used.
 
 
 This closes the connection handle and frees up all resources used.
 

+If autosync was set on the handle and the handle was launched, then
+this implicitly calls various functions to unmount filesystems and
+sync the disk.  See L</guestfs_set_autosync> for more details.
+
+If a close callback was set on the handle, then it is called.
+

 =head1 ERROR HANDLING
 
 API functions can return errors.  For example, almost all functions
 =head1 ERROR HANDLING
 
 API functions can return errors.  For example, almost all functions


@@ -1361,8 +1389,6 @@ been printed to C<stderr> before the program exits.
 For other programs the caller will almost certainly want to install an
 alternate error handler or do error handling in-line like this:
 
 For other programs the caller will almost certainly want to install an
 alternate error handler or do error handling in-line like this:
 

- g = guestfs_create ();
- 

  /* This disables the default behaviour of printing errors
     on stderr. */
  guestfs_set_error_handler (g, NULL, NULL);
  /* This disables the default behaviour of printing errors
     on stderr. */
  guestfs_set_error_handler (g, NULL, NULL);


@@ -1371,9 +1397,12 @@ alternate error handler or do error handling in-line like this:
    /* Examine the error message and print it etc. */
    char *msg = guestfs_last_error (g);
    int errnum = guestfs_last_errno (g);
    /* Examine the error message and print it etc. */
    char *msg = guestfs_last_error (g);
    int errnum = guestfs_last_errno (g);

-   fprintf (stderr, "%s\n", msg);
+   fprintf (stderr, "%s", msg);
+   if (errnum != 0)
+     fprintf (stderr, ": %s", strerror (errnum));
+   fprintf (stderr, "\n");

    /* ... */
    /* ... */

-  }
+ }

 
 Out of memory errors are handled differently.  The default action is
 to call L<abort(3)>.  If this is undesirable, then you can set a
 
 Out of memory errors are handled differently.  The default action is
 to call L<abort(3)>.  If this is undesirable, then you can set a


@@ -1469,8 +1498,8 @@ Returns the current error handler callback.
 =head2 guestfs_set_out_of_memory_handler
 
  typedef void (*guestfs_abort_cb) (void);
 =head2 guestfs_set_out_of_memory_handler
 
  typedef void (*guestfs_abort_cb) (void);

- int guestfs_set_out_of_memory_handler (guestfs_h *g,
-                                        guestfs_abort_cb);
+ void guestfs_set_out_of_memory_handler (guestfs_h *g,
+                                         guestfs_abort_cb);

 
 The callback C<cb> will be called if there is an out of memory
 situation.  I<Note this callback must not return>.
 
 The callback C<cb> will be called if there is an out of memory
 situation.  I<Note this callback must not return>.


@@ -1689,7 +1718,8 @@ old functions C<guestfs_set_log_message_callback>,
 C<guestfs_set_subprocess_quit_callback>,
 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
 C<guestfs_set_progress_callback> are no longer documented in this
 C<guestfs_set_subprocess_quit_callback>,
 C<guestfs_set_launch_done_callback>, C<guestfs_set_close_callback> and
 C<guestfs_set_progress_callback> are no longer documented in this

-manual page.
+manual page.  Because of the ABI guarantee, the old functions continue
+to work.

 
 Handles generate events when certain things happen, such as log
 messages being generated, progress messages during long-running
 
 Handles generate events when certain things happen, such as log
 messages being generated, progress messages during long-running


@@ -1779,12 +1809,27 @@ indicator which shows the ratio of C<position>:C<total>.
 =item *
 
 If any progress notification is sent during a call, then a final
 =item *
 
 If any progress notification is sent during a call, then a final

-progress notification is always sent when C<position> = C<total>.
+progress notification is always sent when C<position> = C<total>
+(I<unless> the call fails with an error).

 
 This is to simplify caller code, so callers can easily set the
 progress indicator to "100%" at the end of the operation, without
 requiring special code to detect this case.
 
 
 This is to simplify caller code, so callers can easily set the
 progress indicator to "100%" at the end of the operation, without
 requiring special code to detect this case.
 

+=item *
+
+For some calls we are unable to estimate the progress of the call, but
+we can still generate progress messages to indicate activity.  This is
+known as "pulse mode", and is directly supported by certain progress
+bar implementations (eg. GtkProgressBar).
+
+For these calls, zero or more progress messages are generated with
+C<position = 0> and C<total = 1>, followed by a final message with
+C<position = total = 1>.
+
+As noted above, if the call fails with an error then the final message
+may not be generated.
+

 =back
 
 The callback also receives the procedure number (C<proc_nr>) and
 =back
 
 The callback also receives the procedure number (C<proc_nr>) and


@@ -1833,6 +1878,21 @@ If no callback is registered: the messages are sent to stderr.  You
 can override the printing of trace messages to stderr by setting up a
 callback.
 
 can override the printing of trace messages to stderr by setting up a
 callback.
 

+=item GUESTFS_EVENT_ENTER
+(payload type: function name)
+
+The callback function is called whenever a libguestfs function
+is entered.
+
+The payload is a string which contains the name of the function
+that we are entering (not including C<guestfs_> prefix).
+
+Note that libguestfs functions can call themselves, so you may
+see many events from a single call.  A few libguestfs functions
+do not generate this event.
+
+If no callback is registered: the event is ignored.
+

 =back
 
 =head3 guestfs_set_event_callback
 =back
 
 =head3 guestfs_set_event_callback


@@ -1950,6 +2010,45 @@ this example, messages are directed to syslog:
      syslog (priority, "event 0x%lx: %s", event, buf);
  }
 
      syslog (priority, "event 0x%lx: %s", event, buf);
  }
 

+=head1 CANCELLING LONG TRANSFERS
+
+Some operations can be cancelled by the caller while they are in
+progress.  Currently only operations that involve uploading or
+downloading data can be cancelled (technically: operations that have
+C<FileIn> or C<FileOut> parameters in the generator).
+
+=head2 guestfs_user_cancel
+
+ void guestfs_user_cancel (guestfs_h *g);
+
+C<guestfs_user_cancel> cancels the current upload or download
+operation.
+
+Unlike most other libguestfs calls, this function is signal safe and
+thread safe.  You can call it from a signal handler or from another
+thread, without needing to do any locking.
+
+The transfer that was in progress (if there is one) will stop shortly
+afterwards, and will return an error.  The errno (see
+L</guestfs_last_errno>) is set to C<EINTR>, so you can test for this
+to find out if the operation was cancelled or failed because of
+another error.
+
+No cleanup is performed: for example, if a file was being uploaded
+then after cancellation there may be a partially uploaded file.  It is
+the caller's responsibility to clean up if necessary.
+
+There are two common places that you might call C<guestfs_user_cancel>.
+
+In an interactive text-based program, you might call it from a
+C<SIGINT> signal handler so that pressing C<^C> cancels the current
+operation.  (You also need to call L</guestfs_set_pgroup> so that
+child processes don't receive the C<^C> signal).
+
+In a graphical program, when the main thread is displaying a progress
+bar with a cancel button, wire up the cancel button to call this
+function.
+

 =head1 PRIVATE DATA AREA
 
 You can attach named pieces of private data to the libguestfs handle,
 =head1 PRIVATE DATA AREA
 
 You can attach named pieces of private data to the libguestfs handle,


@@ -1963,12 +2062,13 @@ To attach a named piece of data, use the following call:
 
 C<key> is the name to associate with this data, and C<data> is an
 arbitrary pointer (which can be C<NULL>).  Any previous item with the
 
 C<key> is the name to associate with this data, and C<data> is an
 arbitrary pointer (which can be C<NULL>).  Any previous item with the

-same name is overwritten.
+same key is overwritten.

 
 

-You can use any C<key> you want, but names beginning with an
-underscore character are reserved for internal libguestfs purposes
-(for implementing language bindings).  It is recommended to prefix the
-name with some unique string to avoid collisions with other users.
+You can use any C<key> you want, but your key should I<not> start with
+an underscore character.  Keys beginning with an underscore character
+are reserved for internal libguestfs purposes (eg. for implementing
+language bindings).  It is recommended that you prefix the key with
+some unique string to avoid collisions with other users.

 
 To retrieve the pointer, use:
 
 
 To retrieve the pointer, use:
 


@@ -2080,6 +2180,77 @@ 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.
 
 might not terminate unless you also maintain an indication of which
 keys have been visited.
 

+=head1 SYSTEMTAP
+
+The libguestfs C library can be probed using systemtap or DTrace.
+This is true of any library, not just libguestfs.  However libguestfs
+also contains static markers to help in probing internal operations.
+
+You can list all the static markers by doing:
+
+ stap -l 'process("/usr/lib*/libguestfs.so.0")
+              .provider("guestfs").mark("*")'
+
+B<Note:> These static markers are I<not> part of the stable API and
+may change in future versions.
+
+=head2 SYSTEMTAP SCRIPT EXAMPLE
+
+This script contains examples of displaying both the static markers
+and some ordinary C entry points:
+
+ global last;
+ 
+ function display_time () {
+       now = gettimeofday_us ();
+       delta = 0;
+       if (last > 0)
+             delta = now - last;
+       last = now;
+ 
+       printf ("%d (+%d):", now, delta);
+ }
+ 
+ probe begin {
+       last = 0;
+       printf ("ready\n");
+ }
+ 
+ /* Display all calls to static markers. */
+ probe process("/usr/lib*/libguestfs.so.0")
+           .provider("guestfs").mark("*") ? {
+       display_time();
+       printf ("\t%s %s\n", $$name, $$parms);
+ }
+ 
+ /* Display all calls to guestfs_mkfs* functions. */
+ probe process("/usr/lib*/libguestfs.so.0")
+           .function("guestfs_mkfs*") ? {
+       display_time();
+       printf ("\t%s %s\n", probefunc(), $$parms);
+ }
+
+The script above can be saved to C<test.stap> and run using the
+L<stap(1)> program.  Note that you either have to be root, or you have
+to add yourself to several special stap groups.  Consult the systemtap
+documentation for more information.
+
+ # stap /tmp/test.stap
+ ready
+
+In another terminal, run a guestfish command such as this:
+
+ guestfish -N fs
+
+In the first terminal, stap trace output similar to this is shown:
+
+ 1318248056692655 (+0):        launch_start
+ 1318248056692850 (+195):       launch_build_appliance_start
+ 1318248056818285 (+125435):    launch_build_appliance_end
+ 1318248056838059 (+19774):     launch_run_qemu
+ 1318248061071167 (+4233108):   launch_end
+ 1318248061280324 (+209157):    guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60
+

 =begin html
 
 <!-- old anchor for the next section -->
 =begin html
 
 <!-- old anchor for the next section -->


@@ -2188,6 +2359,99 @@ callback to receive these messages.
 
 =head1 INTERNALS
 
 
 =head1 INTERNALS
 

+=head2 APPLIANCE BOOT PROCESS
+
+This process has evolved and continues to evolve.  The description
+here corresponds only to the current version of libguestfs and is
+provided for information only.
+
+In order to follow the stages involved below, enable libguestfs
+debugging (set the environment variable C<LIBGUESTFS_DEBUG=1>).
+
+=over 4
+
+=item Create the appliance
+
+C<febootstrap-supermin-helper> is invoked to create the kernel, a
+small initrd and the appliance.
+
+The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in
+another directory if C<TMPDIR> is set).
+
+For a complete description of how the appliance is created and cached,
+read the L<febootstrap(8)> and L<febootstrap-supermin-helper(8)> man
+pages.
+
+=item Start qemu and boot the kernel
+
+qemu is invoked to boot the kernel.
+
+=item Run the initrd
+
+C<febootstrap-supermin-helper> builds a small initrd.  The initrd is
+not the appliance.  The purpose of the initrd is to load enough kernel
+modules in order that the appliance itself can be mounted and started.
+
+The initrd is a cpio archive called
+C</var/tmp/.guestfs-E<lt>UIDE<gt>/initrd>.
+
+When the initrd has started you will see messages showing that kernel
+modules are being loaded, similar to this:
+
+ febootstrap: ext2 mini initrd starting up
+ febootstrap: mounting /sys
+ febootstrap: internal insmod libcrc32c.ko
+ febootstrap: internal insmod crc32c-intel.ko
+
+=item Find and mount the appliance device
+
+The appliance is a sparse file containing an ext2 filesystem which
+contains a familiar (although reduced in size) Linux operating system.
+It would normally be called C</var/tmp/.guestfs-E<lt>UIDE<gt>/root>.
+
+The regular disks being inspected by libguestfs are the first
+devices exposed by qemu (eg. as C</dev/vda>).
+
+The last disk added to qemu is the appliance itself (eg. C</dev/vdb>
+if there was only one regular disk).
+
+Thus the final job of the initrd is to locate the appliance disk,
+mount it, and switch root into the appliance, and run C</init> from
+the appliance.
+
+If this works successfully you will see messages such as:
+
+ febootstrap: picked /sys/block/vdb/dev as root device
+ febootstrap: creating /dev/root as block special 252:16
+ febootstrap: mounting new root on /root
+ febootstrap: chroot
+ Starting /init script ...
+
+Note that C<Starting /init script ...> indicates that the appliance's
+init script is now running.
+
+=item Initialize the appliance
+
+The appliance itself now initializes itself.  This involves starting
+certain processes like C<udev>, possibly printing some debug
+information, and finally running the daemon (C<guestfsd>).
+
+=item The daemon
+
+Finally the daemon (C<guestfsd>) runs inside the appliance.  If it
+runs you should see:
+
+ verbose daemon enabled
+
+The daemon expects to see a named virtio-serial port exposed by qemu
+and connected on the other end to the library.
+
+The daemon connects to this port (and hence to the library) and sends
+a four byte message C<GUESTFS_LAUNCH_FLAG>, which initiates the
+communication protocol (see below).
+
+=back
+

 =head2 COMMUNICATION PROTOCOL
 
 Don't rely on using this protocol directly.  This section documents
 =head2 COMMUNICATION PROTOCOL
 
 Don't rely on using this protocol directly.  This section documents


@@ -2473,8 +2737,9 @@ the OCaml description.
 You can supply zero or as many tests as you want per API call.  The
 tests can either be added as part of the API description
 (C<generator/generator_actions.ml>), or in some rarer cases you may
 You can supply zero or as many tests as you want per API call.  The
 tests can either be added as part of the API description
 (C<generator/generator_actions.ml>), or in some rarer cases you may

-want to drop a script into C<regressions/>.  Note that adding a script
-to C<regressions/> is slower, so if possible use the first method.
+want to drop a script into C<tests/*/>.  Note that adding
+a script to C<tests/*/> is slower, so if possible use the
+first method.

 
 The following describes the test environment used when you add an API
 test in C<generator_actions.ml>.
 
 The following describes the test environment used when you add an API
 test in C<generator_actions.ml>.


@@ -2535,7 +2800,7 @@ Packagers can run only certain tests by setting for example:
 
  TEST_ONLY="vfs_type zerofree"
 
 
  TEST_ONLY="vfs_type zerofree"
 

-See C<capitests/tests.c> for more details of how these environment
+See C<tests/c-api/tests.c> for more details of how these environment

 variables work.
 
 =head2 DEBUGGING NEW API ACTIONS
 variables work.
 
 =head2 DEBUGGING NEW API ACTIONS


@@ -2645,19 +2910,24 @@ the programmers.
 
 =over 4
 
 
 =over 4
 

-=item C<appliance>
+=item C<align>

 
 

-The libguestfs appliance, build scripts and so on.
+L<virt-alignment-scan(1)> command and documentation.

 
 

-=item C<capitests>
+=item C<appliance>

 
 

-Automated tests of the C API.
+The libguestfs appliance, build scripts and so on.

 
 =item C<cat>
 
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 
 
 =item C<cat>
 
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 

+=item C<clone>
+
+Tools for cloning virtual machines.  Currently contains
+L<virt-sysprep(1)> command and documentation.
+

 =item C<contrib>
 
 Outside contributions, experimental parts.
 =item C<contrib>
 
 Outside contributions, experimental parts.


@@ -2671,6 +2941,10 @@ actions.
 
 L<virt-df(1)> command and documentation.
 
 
 L<virt-df(1)> command and documentation.
 

+=item C<edit>
+
+L<virt-edit(1)> command and documentation.
+

 =item C<examples>
 
 C API example code.
 =item C<examples>
 
 C API example code.


@@ -2690,12 +2964,6 @@ L<guestmount(1)>, FUSE (userspace filesystem) built on top of libguestfs.
 The crucially important generator, used to automatically generate
 large amounts of boilerplate C code for things like RPC and bindings.
 
 The crucially important generator, used to automatically generate
 large amounts of boilerplate C code for things like RPC and bindings.
 

-=item C<images>
-
-Files used by the test suite.
-
-Some "phony" guest images which we test against.
-

 =item C<inspector>
 
 L<virt-inspector(1)>, the virtual machine image inspector.
 =item C<inspector>
 
 L<virt-inspector(1)>, the virtual machine image inspector.


@@ -2718,29 +2986,39 @@ The build infrastructure and PO files for translations of manpages and
 POD files.  Eventually this will be combined with the C<po> directory,
 but that is rather complicated.
 
 POD files.  Eventually this will be combined with the C<po> directory,
 but that is rather complicated.
 

-=item C<regressions>
-
-Regression tests.
-

 =item C<rescue>
 
 L<virt-rescue(1)> command and documentation.
 
 =item C<rescue>
 
 L<virt-rescue(1)> command and documentation.
 

-=item C<src>
+=item C<resize>

 
 

-Source code to the C library.
+L<virt-resize(1)> command and documentation.

 
 

-=item C<tools>
+=item C<sparsify>
+
+L<virt-sparsify(1)> command and documentation.

 
 

-Command line tools written in Perl (L<virt-resize(1)> and many others).
+=item C<src>
+
+Source code to the C library.

 
 =item C<test-tool>
 
 Test tool for end users to test if their qemu/kernel combination
 will work with libguestfs.
 
 
 =item C<test-tool>
 
 Test tool for end users to test if their qemu/kernel combination
 will work with libguestfs.
 

+=item C<tests>
+
+Tests.
+
+=item C<tools>
+
+Command line tools written in Perl (L<virt-win-reg(1)> and many others).
+

 =item C<csharp>
 
 =item C<csharp>
 

+=item C<erlang>
+

 =item C<haskell>
 
 =item C<java>
 =item C<haskell>
 
 =item C<java>


@@ -2759,10 +3037,175 @@ Language bindings.
 
 =back
 
 
 =back
 

+=head2 MAKING A STABLE RELEASE
+
+When we make a stable release, there are several steps documented
+here.  See L</LIBGUESTFS VERSION NUMBERS> for general information
+about the stable branch policy.
+
+=over 4
+
+=item *
+
+Check C<make && make check> works on at least Fedora, Debian and
+Ubuntu.
+
+=item *
+
+Finalize RELEASE-NOTES.
+
+=item *
+
+Update ROADMAP.
+
+=item *
+
+Run C<src/api-support/update-from-tarballs.sh>.
+
+=item *
+
+Push and pull from Transifex.
+
+Run:
+
+ tx push -s
+
+to push the latest POT files to Transifex.  Then run:
+
+ ./tx-pull.sh
+
+which is a wrapper to pull the latest translated C<*.po> files.
+
+=item *
+
+Create new stable and development directories under
+L<http://libguestfs.org/download>.
+
+=item *
+
+Create the branch in git:
+
+ git tag -a 1.XX.0 -m "Version 1.XX.0 (stable)"
+ git tag -a 1.YY.0 -m "Version 1.YY.0 (development)"
+ git branch stable-1.XX
+ git push origin tag 1.XX.0 1.YY.0 stable-1.XX
+
+=back
+
+=head1 LIMITS
+
+=head2 PROTOCOL LIMITS
+
+Internally libguestfs uses a message-based protocol to pass API calls
+and their responses to and from a small "appliance" (see L</INTERNALS>
+for plenty more detail about this).  The maximum message size used by
+the protocol is slightly less than 4 MB.  For some API calls you may
+need to be aware of this limit.  The API calls which may be affected
+are individually documented, with a link back to this section of the
+documentation.
+
+A simple call such as L</guestfs_cat> returns its result (the file
+data) in a simple string.  Because this string is at some point
+internally encoded as a message, the maximum size that it can return
+is slightly under 4 MB.  If the requested file is larger than this
+then you will get an error.
+
+In order to transfer large files into and out of the guest filesystem,
+you need to use particular calls that support this.  The sections
+L</UPLOADING> and L</DOWNLOADING> document how to do this.
+
+You might also consider mounting the disk image using our FUSE
+filesystem support (L<guestmount(1)>).
+
+=head2 MAXIMUM NUMBER OF DISKS
+
+When using virtio disks (the default) the current limit is B<25>
+disks.
+
+Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited
+to 31 slots.  However febootstrap only understands disks with names
+C</dev/vda> through C</dev/vdz> (26 letters) and it reserves one disk
+for its own purposes.
+
+We are working to substantially raise this limit in future versions
+but it requires complex changes to qemu.
+
+In future versions of libguestfs it should also be possible to "hot
+plug" disks (add and remove disks after calling L</guestfs_launch>).
+This also requires changes to qemu.
+
+=head2 MAXIMUM NUMBER OF PARTITIONS PER DISK
+
+Virtio limits the maximum number of partitions per disk to B<15>.
+
+This is because it reserves 4 bits for the minor device number (thus
+C</dev/vda>, and C</dev/vda1> through C</dev/vda15>).
+
+If you attach a disk with more than 15 partitions, the extra
+partitions are ignored by libguestfs.
+
+=head2 MAXIMUM SIZE OF A DISK
+
+Probably the limit is between 2**63-1 and 2**64-1 bytes.
+
+We have tested block devices up to 1 exabyte (2**60 or
+1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS
+host filesystem.
+
+Although libguestfs probably does not impose any limit, the underlying
+host storage will.  If you store disk images on a host ext4
+filesystem, then the maximum size will be limited by the maximum ext4
+file size (currently 16 TB).  If you store disk images as host logical
+volumes then you are limited by the maximum size of an LV.
+
+For the hugest disk image files, we recommend using XFS on the host
+for storage.
+
+=head2 MAXIMUM SIZE OF A PARTITION
+
+The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector
+numbers.  Assuming a 512 byte sector size, this means that MBR cannot
+address a partition located beyond 2 TB on the disk.
+
+It is recommended that you use GPT partitions on disks which are
+larger than this size.  GPT uses 64 bit sector numbers and so can
+address partitions which are theoretically larger than the largest
+disk we could support.
+
+=head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES
+
+This depends on the filesystem type.  libguestfs itself does not
+impose any known limit.  Consult Wikipedia or the filesystem
+documentation to find out what these limits are.
+
+=head2 MAXIMUM UPLOAD AND DOWNLOAD
+
+The API functions L</guestfs_upload>, L</guestfs_download>,
+L</guestfs_tar_in>, L</guestfs_tar_out> and the like allow unlimited
+sized uploads and downloads.
+
+=head2 INSPECTION LIMITS
+
+The inspection code has several arbitrary limits on things like the
+size of Windows Registry hive it will read, and the length of product
+name.  These are intended to stop a malicious guest from consuming
+arbitrary amounts of memory and disk space on the host, and should not
+be reached in practice.  See the source code for more information.
+

 =head1 ENVIRONMENT VARIABLES
 
 =over 4
 
 =head1 ENVIRONMENT VARIABLES
 
 =over 4
 

+=item FEBOOTSTRAP_KERNEL
+
+=item FEBOOTSTRAP_MODULES
+
+These two environment variables allow the kernel that libguestfs uses
+in the appliance to be selected.  If C<$FEBOOTSTRAP_KERNEL> is not
+set, then the most recent host kernel is chosen.  For more information
+about kernel selection, see L<febootstrap-supermin-helper(8)>.  This
+feature is only available in febootstrap E<ge> 3.8.
+

 =item LIBGUESTFS_APPEND
 
 Pass additional options to the guest kernel.
 =item LIBGUESTFS_APPEND
 
 Pass additional options to the guest kernel.


@@ -2813,11 +3256,15 @@ enough.
 =head1 SEE ALSO
 
 L<guestfs-examples(3)>,
 =head1 SEE ALSO
 
 L<guestfs-examples(3)>,

+L<guestfs-erlang(3)>,
+L<guestfs-java(3)>,

 L<guestfs-ocaml(3)>,
 L<guestfs-ocaml(3)>,

+L<guestfs-perl(3)>,

 L<guestfs-python(3)>,
 L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 L<guestfs-python(3)>,
 L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,

+L<virt-alignment-scan(1)>,

 L<virt-cat(1)>,
 L<virt-copy-in(1)>,
 L<virt-copy-out(1)>,
 L<virt-cat(1)>,
 L<virt-copy-in(1)>,
 L<virt-copy-out(1)>,


@@ -2830,13 +3277,19 @@ L<virt-list-partitions(1)>,
 L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
 L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,

+L<virt-resize(1)>,
+L<virt-sparsify(1)>,
+L<virt-sysprep(1)>,

 L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,
 L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,
 L<virt-win-reg(1)>,

+L<guestfs-testing(1)>,

 L<qemu(1)>,
 L<febootstrap(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,

+L<febootstrap-supermin-helper(8)>,

 L<hivex(3)>,
 L<hivex(3)>,

+L<stap(1)>,

 L<http://libguestfs.org/>.
 
 Tools with a similar purpose:
 L<http://libguestfs.org/>.
 
 Tools with a similar purpose:


@@ -2885,7 +3338,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-Copyright (C) 2009-2010 Red Hat Inc.
+Copyright (C) 2009-2011 Red Hat Inc.

 L<http://libguestfs.org/>
 
 This library is free software; you can redistribute it and/or
 L<http://libguestfs.org/>
 
 This library is free software; you can redistribute it and/or