X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=45f63297d6b3cff8b17d4db8e7ee2312dbe8ffbc;hp=1a5abc65f0414aeebb4436de3598c291283acec6;hb=5d93d70b4d36b2337104b3dbca07722fa4d47ff5;hpb=1e35941f62bddafd6b88270b22b3afe4a5d37baa

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 1a5abc6..45f6329 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -313,21 +313,36 @@ in the table below.
 
 =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:
 
- 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
-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>
 
@@ -2165,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.
 
+=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 -->
@@ -2713,7 +2799,7 @@ Packagers can run only certain tests by setting for example:
 
  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
@@ -2831,20 +2917,11 @@ L<virt-alignment-scan(1)> command and documentation.
 
 The libguestfs appliance, build scripts and so on.
 
-=item C<capitests>
-
-Automated tests of the C API.
-
 =item C<cat>
 
 The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
 and documentation.
 
-=item C<caution>
-
-Safety and liveness tests of components that libguestfs depends upon
-(not of libguestfs itself).  Mainly this is for qemu and the kernel.
-
 =item C<clone>
 
 Tools for cloning virtual machines.  Currently contains
@@ -2871,6 +2948,11 @@ L<virt-edit(1)> command and documentation.
 
 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
@@ -2934,15 +3016,19 @@ L<virt-sparsify(1)> command and documentation.
 
 Source code to the C library.
 
-=item C<tools>
-
-Command line tools written in Perl (L<virt-win-reg(1)> and many others).
-
 =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<erlang>
@@ -3212,10 +3298,12 @@ 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<stap(1)>,
 L<http://libguestfs.org/>.
 
 Tools with a similar purpose: