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 b203bbf..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>
 
@@ -101,7 +102,9 @@ echoing off so you cannot see what you are typing.  If you are not
 worried about Tempest attacks and there is no one else in the room you
 can specify this flag to see what you are typing.
 
-=item B<--format=raw|qcow2|..> | B<--format>
+=item B<--format=raw|qcow2|..>
+
+=item B<--format>
 
 The default for the I<-a> option is to auto-detect the format of the
 disk image.  Using this forces the disk format for I<-a> options which
@@ -110,19 +113,18 @@ switches back to auto-detection for subsequent I<-a> options.
 
 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>
 
@@ -163,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
@@ -170,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
@@ -183,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