=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>
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 -->
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
+L<virt-sysprep(1)> command and documentation.
+
=item C<contrib>
Outside contributions, experimental parts.
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<febootstrap(1)>,
L<febootstrap-supermin-helper(8)>,
L<hivex(3)>,
+L<stap(1)>,
L<http://libguestfs.org/>.
Tools with a similar purpose: