C<virt-cat> can be used to quickly view a file. To edit a file, use
C<virt-edit>. For more complex cases you should look at the
-L<guestfish(1)> tool.
+L<guestfish(1)> tool (see L</USING GUESTFISH> below).
=head1 EXAMPLES
=item B<--domain> guest
-Add all the disks from the named libvirt guest.
+Add all the disks from the named libvirt guest. Domain UUIDs can be
+used instead of names.
=item B<--echo-keys>
For example:
- virt-cat --format=raw -a disk.img
+ virt-cat --format=raw -a disk.img file
forces raw format (no auto-detection) for C<disk.img>.
- virt-cat --format=raw -a disk.img --format -a another.img
+ virt-cat --format=raw -a disk.img --format -a another.img file
forces raw format (no auto-detection) for C<disk.img> and reverts to
auto-detection for C<another.img>.
If you have untrusted raw-format guest disk images, you should use
this option to specify the disk format. This avoids a possible
-security problem with malicious guests (CVE-2010-3851). See also
-L</add-drive-opts>.
+security problem with malicious guests (CVE-2010-3851).
=item B<--keys-from-stdin>
For compatibility the old style is still supported.
+=head1 WINDOWS PATHS
+
+C<virt-cat> has a limited ability to understand Windows drive letters
+and paths (eg. C<E:\foo\bar.txt>).
+
+If and only if the guest is running Windows then:
+
+=over 4
+
+=item *
+
+Drive letter prefixes like C<C:> are resolved against the
+Windows Registry to the correct filesystem.
+
+=item *
+
+Any backslash (C<\>) characters in the path are replaced
+with forward slashes so that libguestfs can process it.
+
+=item *
+
+The path is resolved case insensitively to locate the file
+that should be displayed.
+
+=back
+
+There are some known shortcomings:
+
+=over 4
+
+=item *
+
+Some NTFS symbolic links may not be followed correctly.
+
+=item *
+
+NTFS junction points that cross filesystems are not followed.
+
+=back
+
+=head1 USING GUESTFISH
+
+L<guestfish(1)> is a more powerful, lower level tool which you can use
+when C<virt-cat> doesn't work.
+
+Using C<virt-cat> is approximately equivalent to doing:
+
+ guestfish --ro -i -d domname download file -
+
+where C<domname> is the name of the libvirt guest, and C<file> is the
+full path to the file. Note the final C<-> (meaning "output to
+stdout").
+
+The command above uses libguestfs's guest inspection feature and so
+does not work on guests that libguestfs cannot inspect, or on things
+like arbitrary disk images that don't contain guests. To display a
+file from a disk image directly, use:
+
+ guestfish --ro -a disk.img -m /dev/sda1 download file -
+
+where C<disk.img> is the disk image, C</dev/sda1> is the filesystem
+within the disk image, and C<file> is the full path to the file.
+
=head1 SHELL QUOTING
Libvirt guest names can contain arbitrary characters, some of which
quote or escape these characters on the command line. See the shell
manual page L<sh(1)> for details.
+=head1 EXIT STATUS
+
+This program returns 0 if successful, or non-zero if there was an
+error.
+
=head1 SEE ALSO
L<guestfs(3)>,
L<guestfish(1)>,
+L<virt-copy-out(1)>,
L<virt-edit(1)>,
+L<virt-tar-out(1)>,
L<http://libguestfs.org/>.
=head1 AUTHOR
=head1 COPYRIGHT
-Copyright (C) 2010 Red Hat Inc.
+Copyright (C) 2010-2011 Red Hat Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by