X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=2e18fd6de8478c5360201c8034427e7fb93747c2;hp=331945dc01a9ce38c42b73c12d5c3f4dd19270f5;hb=72f5487be2df82277021d61f01884381ed9efbc5;hpb=f3341222b37f91d7f7fcdafe30b107ea9da9ad02 diff --git a/src/guestfs.pod b/src/guestfs.pod index 331945d..2e18fd6 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 @@ -2823,6 +2909,10 @@ the programmers. =over 4 +=item C + +L command and documentation. + =item C The libguestfs appliance, build scripts and so on. @@ -2836,10 +2926,10 @@ Automated tests of the C API. The L, L and L commands and documentation. -=item C +=item C -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 command and documentation. =item C @@ -2862,6 +2952,11 @@ L command and documentation. C API example code. +=item C + +Extra tests. These are not run by default because they require +special tools or configuration. + =item C L, the command-line shell, and various shell scripts @@ -2925,15 +3020,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 @@ -3183,6 +3282,7 @@ L, L, L, L, +L, L, L, L, @@ -3197,14 +3297,17 @@ L, L, L, L, +L, L, L, L, L, +L, L, L, L, L, +L, L. Tools with a similar purpose: