python: Memory leak: Free roots array along handle close path.

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

diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod
index 225e3f6..04e421d 100755 (executable)
--- a/inspector/virt-inspector.pod
+++ b/inspector/virt-inspector.pod
@@ -86,7 +86,8 @@ then libvirt is not used at all.
 
 =item B<--domain> guest
 
 
 =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>
 
 
 =item B<--echo-keys>
 


@@ -131,6 +132,13 @@ Display version number and exit.
 
 Enable tracing of libguestfs API calls.
 
 
 Enable tracing of libguestfs API calls.
 

+=item B<--xpath> query
+
+Perform an XPath query on the XML on stdin, and print the result on
+stdout.  In this mode virt-inspector simply runs an XPath query; all
+other inspection functions are disabled.  See L</XPATH QUERIES> below
+for some examples.
+

 =back
 
 =head1 OLD-STYLE COMMAND LINE ARGUMENTS
 =back
 
 =head1 OLD-STYLE COMMAND LINE ARGUMENTS


@@ -284,6 +292,27 @@ Note that this only covers permanent local filesystem mappings, not
 things like network shares.  Furthermore NTFS volume mount points may
 not be listed here.
 
 things like network shares.  Furthermore NTFS volume mount points may
 not be listed here.
 

+=head2 E<lt>iconE<gt>
+
+Virt-inspector is sometimes able to extract an icon or logo for the
+guest.  The icon is returned as base64-encoded PNG data.  Note that
+the icon can be very large and high quality.
+
+ <operatingsystems>
+   <operatingsystem>
+     ...
+     <icon>
+       iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
+       [... many lines of base64 data ...]
+     </icon>
+
+To display the icon, you have to extract it and convert the base64
+data back to a binary file.  Use an XPath query or simply an editor to
+extract the data, then use the coreutils L<base64(1)> program to do
+the conversion back to a PNG file:
+
+ base64 -i -d < icon.data > icon.png
+

 =head2 INSPECTING INSTALL DISKS, LIVE CDs
 
 Virt-inspector can detect some operating system installers on
 =head2 INSPECTING INSTALL DISKS, LIVE CDs
 
 Virt-inspector can detect some operating system installers on


@@ -305,24 +334,35 @@ installer, or one part of a multipart CD.  For example:
      <format>installer</format>
      <live/>
 
      <format>installer</format>
      <live/>
 

-=head1 USING XPATH
+=head1 XPATH QUERIES

 
 

-You can use the XPath query language, and/or the xpath tool, in order
-to select parts of the XML.
+Virt-inspector includes built in support for running XPath queries.
+The reason for including XPath support directly in virt-inspector is
+simply that there are no good and widely available command line
+programs that can do XPath queries.  The only good one is
+L<xmlstarlet(1)> and that is not available on Red Hat Enterprise
+Linux.
+
+To perform an XPath query, use the I<--xpath> option.  Note that in
+this mode, virt-inspector simply reads XML from stdin and outputs the
+query result on stdout.  All other inspection features are disabled in
+this mode.

 
 For example:
 
 
 For example:
 

- $ virt-inspector -d Guest | xpath //filesystems
- Found 1 nodes:
- -- NODE --
+ $ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'

  <filesystems>
       <filesystem dev="/dev/vg_f13x64/lv_root">
         <type>ext4</type>
  <filesystems>
       <filesystem dev="/dev/vg_f13x64/lv_root">
         <type>ext4</type>

- [etc]
+ [...]

 
  $ virt-inspector -d Guest | \
 
  $ virt-inspector -d Guest | \

-     xpath "string(//filesystem[@dev='/dev/sda1']/type)"
- Query didn't return a nodeset. Value: ext4
+     virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
+ ext4
+
+ $ virt-inspector -d Guest | \
+     virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
+ [displays the guest icon, if there is one]

 
 =head1 SHELL QUOTING
 
 
 =head1 SHELL QUOTING
 


@@ -347,11 +387,18 @@ versions of virt-inspector with different names:
  virt-inspector     Old Perl version.
  virt-inspector2    New C version.
 
  virt-inspector     Old Perl version.
  virt-inspector2    New C version.
 

+=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<http://www.w3.org/TR/xpath/>,
 =head1 SEE ALSO
 
 L<guestfs(3)>,
 L<guestfish(1)>,
 L<http://www.w3.org/TR/xpath/>,

+L<base64(1)>,
+L<xmlstarlet(1)>,

 L<http://libguestfs.org/>.
 
 =head1 AUTHORS
 L<http://libguestfs.org/>.
 
 =head1 AUTHORS


@@ -384,4 +431,4 @@ GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software

-Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.