man pages: Add a standard EXIT STATUS section to most pages.

[libguestfs.git] / cat / virt-cat.pod

diff --git a/cat/virt-cat.pod b/cat/virt-cat.pod
index 395b10b..4002188 100755 (executable)
--- a/cat/virt-cat.pod
+++ b/cat/virt-cat.pod
@@ -27,7 +27,7 @@ directory (starting with '/').
 
 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
 
@@ -92,7 +92,8 @@ not used at all.
 
 =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>
 
@@ -123,8 +124,7 @@ 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>
 
@@ -165,6 +165,30 @@ name as a guest.
 
 For compatibility the old style is still supported.
 
+=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 to edit, and C<file> is the full path to the
+file.
+
 =head1 SHELL QUOTING
 
 Libvirt guest names can contain arbitrary characters, some of which
@@ -172,11 +196,18 @@ have meaning to the shell such as C<#> and space.  You may need to
 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
@@ -185,7 +216,7 @@ Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 
 =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