Hostinfo day 1: Mainly documentation.

[virt-hostinfo.git] / hostinfo-status / hostinfo-status.pl

diff --git a/hostinfo-status/hostinfo-status.pl b/hostinfo-status/hostinfo-status.pl
new file mode 100755 (executable)
index 0000000..b367206
--- /dev/null
+++ b/hostinfo-status/hostinfo-status.pl
@@ -0,0 +1,121 @@
+#!/usr/bin/perl -w
+# @configure_input@
+# virt-hostinfo
+# Copyright (C) 2009 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
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# 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
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+use strict;
+
+#use Sys::Virt;
+
+=pod
+
+=head1 NAME
+
+hostinfo-status - check if hostinfo is enabled for a guest
+
+=head1 SYNOPSIS
+
+ hostinfo-status [GUESTNAME [GUESTNAME...]]
+
+=head1 DESCRIPTION
+
+This command finds out if hostinfo is enabled or disabled for a
+particular guest.
+
+For example:
+
+ # hostinfo-status myguest
+ myguest: hostinfo is enabled on serial port 1 (ttyS1/COM2)
+
+If no guest names are listed on the command line, this command
+displays the status of all guests known to libvirt.
+
+If you want to find out if the hostinfo feature is enabled for the
+host as a whole, you should use this command instead:
+
+ service hostinfo status
+
+(see L<hostinfo(8)>).
+
+=cut
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--quiet>
+
+Use this option from scripts to test if hostinfo is enabled
+for a single guest without the verbose messages:
+
+ if hostinfo-status --quiet myguest; then
+   echo Yes, hostinfo is enabled for this guest.
+ else
+   echo No, hostinfo is not enabled for this guest.
+ fi
+
+=back
+
+=cut
+
+
+
+
+=head1 RETURN VALUE
+
+Normally C<hostinfo-status> returns 0 if the command was successful,
+or 2 if there was an error.
+
+However if you use the C<--quiet> option, it returns 0 if hostinfo
+is enabled, 1 if hostinfo is disabled, or 2 if there was an error.
+
+=cut
+
+
+
+=head1 SEE ALSO
+
+L<hostinfo(8)>,
+L<hostinfo-set(8)>,
+L<hostinfo-test(8)>,
+L<virt-install(1)>,
+L<virt-manager(1)>,
+L<http://fedoraproject.org/wiki/Features/Hostinfo>,
+L<http://libvirt.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2009 Red Hat Inc.
+L<http://fedoraproject.org/wiki/Features/Hostinfo>
+
+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
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+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
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.