perl plugin: Do not pass NULL to newRV().

[collectd.git] / src / collectd-perl.pod

diff --git a/src/collectd-perl.pod b/src/collectd-perl.pod
index dac80bf..bd99df0 100644 (file)
--- a/src/collectd-perl.pod
+++ b/src/collectd-perl.pod
@@ -11,6 +11,10 @@ collectd-perl - Documentation of collectd's C<perl plugin>
     BaseName "Collectd::Plugin"
     EnableDebugger ""
     LoadPlugin "FooBar"
+
+    <Plugin FooBar>
+      Foo "Bar"
+    </Plugin>
   </Plugin>
 
 =head1 DESCRIPTION
@@ -36,6 +40,16 @@ causes the Perl-interpreter to be initialized.
 Prepends I<Name>B<::> to all plugin names loaded after this option. This is
 provided for convenience to keep plugin names short.
 
+=item E<lt>B<Plugin> I<Name>E<gt> block
+
+This block may be used to pass on configuration settings to a Perl plugin. The
+configuration is converted into a config-item data type which is passed to the
+registered configuration callback. See below for details about the config-item
+data type and how to register callbacks.
+
+The I<name> identifies the callback. It is used literally and independent of
+the B<BaseName> setting.
+
 =item B<EnableDebugger> I<Package>[=I<option>,...]
 
 Run collectd under the control of the Perl source debugger. If I<Package> is
@@ -71,6 +85,13 @@ example. The following types of B<callback functions> are known to collectd
 
 =over 4
 
+=item configuration functions
+
+This type of functions is called during configuration if an appropriate
+B<Plugin> block has been encountered. It is called once for each B<Plugin>
+block which matches the name of the callback as provided with the
+B<plugin_register> method - see below.
+
 =item init functions
 
 This type of functions is called once after loading the module and before any
@@ -140,6 +161,19 @@ and collectd:
 
 =over 4
 
+=item Config-Item
+
+A config-item is one structure which keeps the informations provided in the
+configuration file. The array of children keeps one entry for each
+configuration option. Each such entry is another config-item structure, which
+may nest further if nested blocks are used.
+
+  {
+    key      => key,
+    values   => [ val1, val2, ... ],
+    children => [ { ... }, { ... }, ... ]
+  }
+
 =item Data-Set
 
 A data-set is a list of one or more data-sources. Each data-source defines a
@@ -164,6 +198,7 @@ layout looks like this:
   {
     values => [123, 0.5],
     time   => time (),
+    interval => $interval_g,
     host   => $hostname_g,
     plugin => 'myplugin',
     type   => 'myplugin',
@@ -174,7 +209,9 @@ layout looks like this:
 =item Notification
 
 A notification is one structure defining the severity, time and message of the
-status message as well as an identification of a data instance:
+status message as well as an identification of a data instance. Also, it
+includes an optional list of user-defined meta information represented as
+(name, value) pairs:
 
   {
     severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
@@ -184,7 +221,8 @@ status message as well as an identification of a data instance:
     plugin   => 'myplugin',
     type     => 'mytype',
     plugin_instance => '',
-    type_instance   => ''
+    type_instance   => '',
+    meta     => [ { name => <name>, value => <value> }, ... ]
   }
 
 =back
@@ -204,6 +242,8 @@ I<type> can be one of:
 
 =over 4
 
+=item TYPE_CONFIG
+
 =item TYPE_INIT
 
 =item TYPE_READ
@@ -248,6 +288,11 @@ arguments:
 
 =over 4
 
+=item TYPE_CONFIG
+
+The only argument passed is I<config-item>. See above for the layout of this
+data type.
+
 =item TYPE_INIT
 
 =item TYPE_READ
@@ -263,8 +308,9 @@ string. For the layout of I<data-set> and I<value-list> see above.
 
 =item TYPE_FLUSH
 
-The only argument passed is I<timeout> which indicates that only data older
-than I<timeout> seconds is to be flushed.
+The arguments passed are I<timeout> and I<identifier>. I<timeout> indicates
+that only data older than I<timeout> seconds is to be flushed. I<identifier>
+specifies which values are to be flushed.
 
 =item TYPE_LOG
 
@@ -299,12 +345,26 @@ as the first argument to B<plugin_register>. This syntax is still supported
 for backwards compatibility but has been deprecated and will be removed in
 some future version of collectd.
 
+=item B<plugin_write> ([B<plugins> => I<...>][, B<datasets> => I<...>],
+B<valuelists> => I<...>)
+
+Calls the write function of the given I<plugins> with the provided I<data
+sets> and I<value lists>. In contrast to B<plugin_dispatch_values>, it does
+not update collectd's internal cache and bypasses the filter mechanism (see
+L<collectd.conf(5)> for details). If the B<plugins> argument has been omitted,
+the values will be dispatched to all registered write plugins. If the
+B<datasets> argument has been omitted, the required data sets are looked up
+according to the C<type> member in the appropriate value list. The value of
+all three arguments may either be a single scalar or a reference to an array.
+If the B<datasets> argument has been specified, the number of data sets has to
+equal the number of specified value lists.
+
 =item B<plugin_flush> ([B<timeout> => I<timeout>][, B<plugins> => I<...>][,
 B<identifiers> => I<...>])
 
 Flush one or more plugins. I<timeout> and the specified I<identifiers> are
 passed on to the registered flush-callbacks. If omitted, the timeout defaults
-to C<-1>. The identifier defaults to the undefined value. If the I<plugins>
+to C<-1>. The identifier defaults to the undefined value. If the B<plugins>
 argument has been specified, only named plugins will be flushed. The value of
 the B<plugins> and B<identifiers> arguments may either be a string or a
 reference to an array of strings.
@@ -395,6 +455,8 @@ available (B<:all> will export all of them):
 
 =over 4
 
+=item B<TYPE_CONFIG>
+
 =item B<TYPE_INIT>
 
 =item B<TYPE_READ>
@@ -407,6 +469,8 @@ available (B<:all> will export all of them):
 
 =item B<TYPE_LOG>
 
+=item B<TYPE_DATASET>
+
 =back
 
 =item B<:ds_types>