tests: Rename capitests -> tests/c-api.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index a1831c0..45f6329 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>
 


@@ -719,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.


@@ -798,6 +817,9 @@ can make this very puzzling if you are trying to debug a problem.
 
 =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.


@@ -948,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


@@ -1453,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>.


@@ -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


@@ -2120,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 -->


@@ -2228,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


@@ -2575,7 +2799,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


@@ -2685,23 +2909,23 @@ 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<caution>
+=item C<clone>

 
 

-Safety and liveness tests of components that libguestfs depends upon
-(not of libguestfs itself).  Mainly this is for qemu and the kernel.
+Tools for cloning virtual machines.  Currently contains
+L<virt-sysprep(1)> command and documentation.

 
 =item C<contrib>
 
 
 =item C<contrib>
 


@@ -2724,6 +2948,11 @@ L<virt-edit(1)> command and documentation.
 
 C API example code.
 
 
 C API example code.
 

+=item C<extratests>
+
+Extra tests.  These are not run by default because they require
+special tools or configuration.
+

 =item C<fish>
 
 L<guestfish(1)>, the command-line shell, and various shell scripts
 =item C<fish>
 
 L<guestfish(1)>, the command-line shell, and various shell scripts


@@ -2775,21 +3004,35 @@ Regression tests.
 
 L<virt-rescue(1)> command and documentation.
 
 
 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.
+
+=item C<src>

 
 

-Command line tools written in Perl (L<virt-resize(1)> and many others).
+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>


@@ -3027,6 +3270,7 @@ 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-perl(3)>,
 L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,


@@ -3034,6 +3278,7 @@ L<guestfs-python(3)>,
 L<guestfs-ruby(3)>,
 L<guestfish(1)>,
 L<guestmount(1)>,
 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)>,


@@ -3046,14 +3291,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<febootstrap-supermin-helper(8)>,
 L<hivex(3)>,
 L<qemu(1)>,
 L<febootstrap(1)>,
 L<febootstrap-supermin-helper(8)>,
 L<hivex(3)>,

+L<stap(1)>,

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