diff --git a/src/collectdctl.pod b/src/collectdctl.pod
index 497e9571395a1bd3a0a883b7f6cd4b4e0e5a0769..d921330464aba9487d7d9caa4fee7480497ad691 100644 (file)
--- a/src/collectdctl.pod
+++ b/src/collectdctl.pod
+=encoding UTF-8
+
=head1 NAME
collectdctl - Control interface for collectd
=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.
+The B<plugin> and B<identifier> options may be specified more than once. In
+that case, all combinations of specified plugins and identifiers will be
+flushed only.
=item B<listval>
command returns a list of valid identifiers that may be used with the other
commands.
+=item B<putval> I<E<lt>identifierE<gt>> [B<interval=>I<E<lt>secondsE<gt>>]
+I<E<lt>value-list(s)E<gt>>
+
+Submit one or more values (identified by I<E<lt>identifierE<gt>>, see below)
+to the daemon which will then dispatch them to the write plugins. B<interval>
+specifies the interval (in seconds) used to collect the values following that
+option. It defaults to the default of the running collectd instance receiving
+the data. Multiple I<E<lt>value-list(s)E<gt>> (see below) may be specified.
+Each of them will be submitted to the daemon. The values have to match the
+data-set definition specified by the type as given in the identifier (see
+L<types.db(5)> for details).
+
=back
=head1 IDENTIFIERS
error is returned if the specified identifier does not exist (this is a
limitation in the C<libcollectdclient> library).
+=head1 VALUE-LIST
+
+A value list describes one data-set as handled by collectd. It is a colon
+(C<:>) separated list of the time and the values. Each value is either given
+as an integer if the data-type is a counter, or as a double if the data-type
+is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
+The number of values and the data-types have to match the type specified in
+the identifier (see L<types.db(5)> for details). The time is specified as
+epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
+interpreted as now.
+
+=head1 EXAMPLES
+
+=over 4
+
+=item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
+
+Flushes all CPU wait RRD values of the first CPU of the local host.
+I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
+
+=item C<for ident in `collectdctl listval | grep users/users`; do
+ collectdctl getval $ident;
+ done>
+
+Query the latest number of logged in users on all hosts known to the local
+collectd instance.
+
+=back
+
=head1 SEE ALSO
-L<collectd(1)>
-L<collectd.conf(5)>
-L<collectd-unixsock(5)>
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<collectd-unixsock(5)>,
+L<types.db(5)>
=head1 AUTHOR
-collectd has been written by Florian Forster E<lt>octo at verplant.orgE<gt>
+collectd has been written by Florian Forster E<lt>octo at collectd.orgE<gt>
and many contributors (see `AUTHORS').
collectdctl has been written by