X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=f7740b6b04159e6997e07a98dbc315bb1e2e5da9;hp=1a5abc65f0414aeebb4436de3598c291283acec6;hb=HEAD;hpb=1e35941f62bddafd6b88270b22b3afe4a5d37baa diff --git a/src/guestfs.pod b/src/guestfs.pod index 1a5abc6..f7740b6 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -313,21 +313,36 @@ in the table below. =item B to B -Use L to copy a single file, or -L to copy directories recursively. +Use L to copy a single file, or L to copy +directories recursively. -=item B to B +To copy part of a file (offset and size) use +L. -Use L which efficiently uses L -to copy between files and devices in the guest. +=item B to B + +=item B to B + +=item B to B + +Use L, L, +or L. 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) must be at least as large as the -source (C). To copy less than the whole -source device, use L. +source (C). To copy less than the whole source +device, use the optional C parameter: + + guestfs_copy_device_to_device (g, + "/dev/VG/Original", "/dev/VG/Copy", + GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000, + -1); =item B to B @@ -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 These static markers are I 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 and run using the +L 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 @@ -2651,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), or in some rarer cases you may -want to drop a script into C. Note that adding a script -to C is slower, so if possible use the first method. +want to drop a script into C. Note that adding +a script to C is slower, so if possible use the +first method. The following describes the test environment used when you add an API test in C. @@ -2713,7 +2800,7 @@ Packagers can run only certain tests by setting for example: TEST_ONLY="vfs_type zerofree" -See C for more details of how these environment +See C for more details of how these environment variables work. =head2 DEBUGGING NEW API ACTIONS @@ -2831,20 +2918,11 @@ L command and documentation. The libguestfs appliance, build scripts and so on. -=item C - -Automated tests of the C API. - =item C The L, L and L commands and documentation. -=item C - -Safety and liveness tests of components that libguestfs depends upon -(not of libguestfs itself). Mainly this is for qemu and the kernel. - =item C Tools for cloning virtual machines. Currently contains @@ -2886,12 +2964,6 @@ L, 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. -=item C - -Files used by the test suite. - -Some "phony" guest images which we test against. - =item C L, the virtual machine image inspector. @@ -2914,10 +2986,6 @@ The build infrastructure and PO files for translations of manpages and POD files. Eventually this will be combined with the C directory, but that is rather complicated. -=item C - -Regression tests. - =item C L command and documentation. @@ -2934,15 +3002,19 @@ L command and documentation. Source code to the C library. -=item C - -Command line tools written in Perl (L and many others). - =item C Test tool for end users to test if their qemu/kernel combination will work with libguestfs. +=item C + +Tests. + +=item C + +Command line tools written in Perl (L and many others). + =item C =item C @@ -3212,10 +3284,12 @@ L, L, L, L, +L, L, L, L, L, +L, L. Tools with a similar purpose: