From 00f1c765cad57d9ccd5263421611b56dfa8e94c4 Mon Sep 17 00:00:00 2001
From: Sebastian Harl <sh@tokkee.org>
Date: Mon, 9 Aug 2010 00:10:22 +0200
Subject: [PATCH] collectdctl(1): Updated the manpage according to the latest
 changes.

---
 src/collectdctl.pod | 105 ++++++++++++++++++++++++++++++++------------
 1 file changed, 76 insertions(+), 29 deletions(-)

diff --git a/src/collectdctl.pod b/src/collectdctl.pod
index f3fb866a..497e9571 100644
--- a/src/collectdctl.pod
+++ b/src/collectdctl.pod
@@ -1,23 +1,19 @@
 =head1 NAME
 
-collectd-flush - Small command line utility to flush collectd
+collectdctl - Control interface for collectd
 
 =head1 SYNOPSIS
 
-collectd-flush I<[options]>
+collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>
 
 =head1 DESCRIPTION
 
-This small command line utitilty uses C<libcollectdclient> to flush collectd
-through a socket from the L<unixsock plugin>. Useful if you want to be sure
-you have the latest values in your RRD files before graphing them or copying
-them somewhere else.
+collectdctl provides a control interface for collectd, which may be used to
+interact with the daemon using the C<unixsock plugin>.
 
-=head1 ARGUMENTS AND OPTIONS
+=head1 OPTIONS
 
-The following arguments and options are understood by collectd-flush. The order
-of the arguments generally doesn't matter, as long as no argument is passed
-more than once.
+collectdctl supports the following options:
 
 =over 4
 
@@ -26,38 +22,84 @@ more than once.
 Path to the UNIX socket opened by collectd's C<unixsock plugin>.
 Default: /var/run/collectd-unixsock
 
-=item B<-p> I<plugin>
+=item B<-h>
 
-Plugin to flush I<to>. Example: B<rrdtool>.
+Display usage information and exit.
 
-=item B<-i> I<identifier>
+=back
 
-If this option is present, only the data specified by I<identifier> will be flushed.
-I<identifier> has the following format:
+=head1 AVAILABLE COMMANDS
 
-[I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
+The following commands are supported:
 
-Examples:
- somehost/cpu-0/cpu-idle
- uptime/uptime
- otherhost/memory/memory-used
+=over 4
 
-Hostname defaults to the local hostname if omitted. No error is returned if the
-specified identifier does not exist (this is a limitation in the
-C<libcollectdclient> library). You can only specify one identifier each time you
-run this program (even though L<collectd-unixsock(5)> supports multiple
-identifiers).
+=item B<getval> I<E<lt>identifierE<gt>>
 
-=item B<-t> I<timeout>
+Query the latest collected value identified by the specified
+I<E<lt>identifierE<gt>> (see below). The value-list associated with that
+data-set is returned as a list of key-value-pairs, each on its own line. Keys
+and values are separated by the equal sign (C<=>).
 
-Only flush values older than I<timeout> seconds.
+=item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>]
+[B<identifier=>I<E<lt>idE<gt>>]
 
-=item B<-h>
+Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest
+values have been written to the respective RRD file before graphing them or
+copying them to somewhere else.
 
-Display usage information and exit.
+The following options are supported by the flush command:
+
+=over 4
+
+=item B<timeout=>I<E<lt>secondsE<gt>>
+
+Flush values older than the specified timeout (in seconds) only.
+
+=item B<plugin=>I<E<lt>nameE<gt>>
+
+Flush the specified plugin only. I.E<nbsp>e., data cached by the specified
+plugin is written to disk (or network or whatever), if the plugin supports
+that operation.
+
+Example: B<rrdtool>.
+
+=item B<identifier=>I<E<lt>idE<gt>>
+
+If this option is present, only the data specified by the specified identifier
+(see below) will be flushed. Note that this option is not supported by all
+plugins (e.E<nbsp>g., the C<network> plugin does not support this).
 
 =back
 
+In contrast to the plain-text protocol used by the C<unixsock> plugin, the
+B<plugin> and B<identifier> options may only be specified once. If specified
+multiple times, the last one overwrites the ones before.
+
+=item B<listval>
+
+Returns a list of all values (by their identifier) available to the
+C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this
+command returns a list of valid identifiers that may be used with the other
+commands.
+
+=back
+
+=head1 IDENTIFIERS
+
+An identifier has the following format:
+
+[I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
+
+Examples:
+ somehost/cpu-0/cpu-idle
+ uptime/uptime
+ otherhost/memory/memory-used
+
+Hostname defaults to the local (non-fully qualified) hostname if omitted. No
+error is returned if the specified identifier does not exist (this is a
+limitation in the C<libcollectdclient> library).
+
 =head1 SEE ALSO
 
 L<collectd(1)>
@@ -66,6 +108,11 @@ L<collectd-unixsock(5)>
 
 =head1 AUTHOR
 
+collectd has been written by Florian Forster E<lt>octo at verplant.orgE<gt>
+and many contributors (see `AUTHORS').
+
+collectdctl has been written by
 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>
+and Sebastian Harl E<lt>sh at tokkee.orgE<gt>.
 
 =cut
-- 
2.30.2