![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/collectd-perl.5 b/src/collectd-perl.5
--- /dev/null
+++ b/src/collectd-perl.5
@@ -0,0 +1,858 @@
+.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+. if \nF \{
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "COLLECTD-PERL 5"
+.TH COLLECTD-PERL 5 "2015-05-20" "5.4.2.911.g0c88d3b" "collectd"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+collectd\-perl \- Documentation of collectd's "perl plugin"
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 7
+\& LoadPlugin perl
+\& # ...
+\& <Plugin perl>
+\& IncludeDir "/path/to/perl/plugins"
+\& BaseName "Collectd::Plugins"
+\& EnableDebugger ""
+\& LoadPlugin "FooBar"
+\&
+\& <Plugin FooBar>
+\& Foo "Bar"
+\& </Plugin>
+\& </Plugin>
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`perl plugin\*(C'\fR embeds a Perl-interpreter into collectd and provides an
+interface to collectd's plugin system. This makes it possible to write plugins
+for collectd in Perl. This is a lot more efficient than executing a
+Perl-script every time you want to read a value with the \f(CW\*(C`exec plugin\*(C'\fR (see
+\&\fIcollectd\-exec\fR\|(5)) and provides a lot more functionality, too.
+.SH "CONFIGURATION"
+.IX Header "CONFIGURATION"
+.IP "\fBLoadPlugin\fR \fIPlugin\fR" 4
+.IX Item "LoadPlugin Plugin"
+Loads the Perl plugin \fIPlugin\fR. This does basically the same as \fBuse\fR would
+do in a Perl program. As a side effect, the first occurrence of this option
+causes the Perl-interpreter to be initialized.
+.IP "\fBBaseName\fR \fIName\fR" 4
+.IX Item "BaseName Name"
+Prepends \fIName\fR\fB::\fR to all plugin names loaded after this option. This is
+provided for convenience to keep plugin names short. All Perl-based plugins
+provided with the \fIcollectd\fR distributions reside in the \f(CW\*(C`Collectd::Plugins\*(C'\fR
+namespace.
+.IP "<\fBPlugin\fR \fIName\fR> block" 4
+.IX Item "<Plugin Name> 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.
+.Sp
+The \fIname\fR identifies the callback. It is used literally and independent of
+the \fBBaseName\fR setting.
+.IP "\fBEnableDebugger\fR \fIPackage\fR[=\fIoption\fR,...]" 4
+.IX Item "EnableDebugger Package[=option,...]"
+Run collectd under the control of the Perl source debugger. If \fIPackage\fR is
+not the empty string, control is passed to the debugging, profiling, or
+tracing module installed as Devel::\fIPackage\fR. A comma-separated list of
+options may be specified after the \*(L"=\*(R" character. Please note that you may not
+leave out the \fIPackage\fR option even if you specify \fB""\fR. This is the same as
+using the \fB\-d:Package\fR command line option.
+.Sp
+See perldebug for detailed documentation about debugging Perl.
+.Sp
+This option does not prevent collectd from daemonizing, so you should start
+collectd with the \fB\-f\fR command line option. Else you will not be able to use
+the command line driven interface of the debugger.
+.IP "\fBIncludeDir\fR \fIDir\fR" 4
+.IX Item "IncludeDir Dir"
+Adds \fIDir\fR to the \fB\f(CB@INC\fB\fR array. This is the same as using the \fB\-IDir\fR
+command line option or \fBuse lib Dir\fR in the source code. Please note that it
+only has effect on plugins loaded after this option.
+.SH "WRITING YOUR OWN PLUGINS"
+.IX Header "WRITING YOUR OWN PLUGINS"
+Writing your own plugins is quite simple. collectd manages plugins by means of
+\&\fBdispatch functions\fR which call the appropriate \fBcallback functions\fR
+registered by the plugins. Any plugin basically consists of the implementation
+of these callback functions and initializing code which registers the
+functions with collectd. See the section \*(L"\s-1EXAMPLES\*(R"\s0 below for a really basic
+example. The following types of \fBcallback functions\fR are known to collectd
+(all of them are optional):
+.IP "configuration functions" 4
+.IX Item "configuration functions"
+This type of functions is called during configuration if an appropriate
+\&\fBPlugin\fR block has been encountered. It is called once for each \fBPlugin\fR
+block which matches the name of the callback as provided with the
+\&\fBplugin_register\fR method \- see below.
+.IP "init functions" 4
+.IX Item "init functions"
+This type of functions is called once after loading the module and before any
+calls to the read and write functions. It should be used to initialize the
+internal state of the plugin (e.\ g. open sockets, ...). If the return
+value evaluates to \fBfalse\fR, the plugin will be disabled.
+.IP "read functions" 4
+.IX Item "read functions"
+This type of function is used to collect the actual data. It is called once
+per interval (see the \fBInterval\fR configuration option of collectd). Usually
+it will call \fBplugin_dispatch_values\fR to dispatch the values to collectd
+which will pass them on to all registered \fBwrite functions\fR. If the return
+value evaluates to \fBfalse\fR the plugin will be skipped for an increasing
+amount of time until it returns \fBtrue\fR again.
+.IP "write functions" 4
+.IX Item "write functions"
+This type of function is used to write the dispatched values. It is called
+once for each call to \fBplugin_dispatch_values\fR.
+.IP "flush functions" 4
+.IX Item "flush functions"
+This type of function is used to flush internal caches of plugins. It is
+usually triggered by the user only. Any plugin which caches data before
+writing it to disk should provide this kind of callback function.
+.IP "log functions" 4
+.IX Item "log functions"
+This type of function is used to pass messages of plugins or the daemon itself
+to the user.
+.IP "notification function" 4
+.IX Item "notification function"
+This type of function is used to act upon notifications. In general, a
+notification is a status message that may be associated with a data instance.
+Usually, a notification is generated by the daemon if a configured threshold
+has been exceeded (see the section \*(L"\s-1THRESHOLD CONFIGURATION\*(R"\s0 in
+\&\fIcollectd.conf\fR\|(5) for more details), but any plugin may dispatch
+notifications as well.
+.IP "shutdown functions" 4
+.IX Item "shutdown functions"
+This type of function is called once before the daemon shuts down. It should
+be used to clean up the plugin (e.g. close sockets, ...).
+.PP
+Any function (except log functions) may set the \fB$@\fR variable to describe
+errors in more detail. The message will be passed on to the user using
+collectd's logging mechanism.
+.PP
+See the documentation of the \fBplugin_register\fR method in the section
+\&\*(L"\s-1METHODS\*(R"\s0 below for the number and types of arguments passed to each
+\&\fBcallback function\fR. This section also explains how to register \fBcallback
+functions\fR with collectd.
+.PP
+To enable a plugin, copy it to a place where Perl can find it (i.\ e. a
+directory listed in the \fB\f(CB@INC\fB\fR array) just as any other Perl plugin and add
+an appropriate \fBLoadPlugin\fR option to the configuration file. After
+restarting collectd you're done.
+.SH "DATA TYPES"
+.IX Header "DATA TYPES"
+The following complex types are used to pass values between the Perl plugin
+and collectd:
+.IP "Config-Item" 4
+.IX Item "Config-Item"
+A config-item is one structure which keeps the information 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.
+.Sp
+.Vb 5
+\& {
+\& key => key,
+\& values => [ val1, val2, ... ],
+\& children => [ { ... }, { ... }, ... ]
+\& }
+.Ve
+.IP "Data-Set" 4
+.IX Item "Data-Set"
+A data-set is a list of one or more data-sources. Each data-source defines a
+name, type, min\- and max-value and the data-set wraps them up into one
+structure. The general layout looks like this:
+.Sp
+.Vb 6
+\& [{
+\& name => \*(Aqdata_source_name\*(Aq,
+\& type => DS_TYPE_COUNTER || DS_TYPE_GAUGE || DS_TYPE_DERIVE || DS_TYPE_ABSOLUTE,
+\& min => value || undef,
+\& max => value || undef
+\& }, ...]
+.Ve
+.IP "Value-List" 4
+.IX Item "Value-List"
+A value-list is one structure which features an array of values and fields to
+identify the values, i.\ e. time and host, plugin name and
+plugin-instance as well as a type and type-instance. Since the \*(L"type\*(R" is not
+included in the value-list but is passed as an extra argument, the general
+layout looks like this:
+.Sp
+.Vb 10
+\& {
+\& values => [123, 0.5],
+\& time => time (),
+\& interval => plugin_get_interval (),
+\& host => $hostname_g,
+\& plugin => \*(Aqmyplugin\*(Aq,
+\& type => \*(Aqmyplugin\*(Aq,
+\& plugin_instance => \*(Aq\*(Aq,
+\& type_instance => \*(Aq\*(Aq
+\& }
+.Ve
+.IP "Notification" 4
+.IX 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. Also, it
+includes an optional list of user-defined meta information represented as
+(name, value) pairs:
+.Sp
+.Vb 11
+\& {
+\& severity => NOTIF_FAILURE || NOTIF_WARNING || NOTIF_OKAY,
+\& time => time (),
+\& message => \*(Aqstatus message\*(Aq,
+\& host => $hostname_g,
+\& plugin => \*(Aqmyplugin\*(Aq,
+\& type => \*(Aqmytype\*(Aq,
+\& plugin_instance => \*(Aq\*(Aq,
+\& type_instance => \*(Aq\*(Aq,
+\& meta => [ { name => <name>, value => <value> }, ... ]
+\& }
+.Ve
+.IP "Match-Proc" 4
+.IX Item "Match-Proc"
+A match-proc is one structure storing the callbacks of a \*(L"match\*(R" of the filter
+chain infrastructure. The general layout looks like this:
+.Sp
+.Vb 5
+\& {
+\& create => \*(Aqmy_create\*(Aq,
+\& destroy => \*(Aqmy_destroy\*(Aq,
+\& match => \*(Aqmy_match\*(Aq
+\& }
+.Ve
+.IP "Target-Proc" 4
+.IX Item "Target-Proc"
+A target-proc is one structure storing the callbacks of a \*(L"target\*(R" of the
+filter chain infrastructure. The general layout looks like this:
+.Sp
+.Vb 5
+\& {
+\& create => \*(Aqmy_create\*(Aq,
+\& destroy => \*(Aqmy_destroy\*(Aq,
+\& invoke => \*(Aqmy_invoke\*(Aq
+\& }
+.Ve
+.SH "METHODS"
+.IX Header "METHODS"
+The following functions provide the C\-interface to Perl-modules. They are
+exported by the \*(L":plugin\*(R" export tag (see the section \*(L"\s-1EXPORTS\*(R"\s0 below).
+.IP "\fBplugin_register\fR (\fItype\fR, \fIname\fR, \fIdata\fR)" 4
+.IX Item "plugin_register (type, name, data)"
+Registers a callback-function or data-set.
+.Sp
+\&\fItype\fR can be one of:
+.RS 4
+.IP "\s-1TYPE_CONFIG\s0" 4
+.IX Item "TYPE_CONFIG"
+.PD 0
+.IP "\s-1TYPE_INIT\s0" 4
+.IX Item "TYPE_INIT"
+.IP "\s-1TYPE_READ\s0" 4
+.IX Item "TYPE_READ"
+.IP "\s-1TYPE_WRITE\s0" 4
+.IX Item "TYPE_WRITE"
+.IP "\s-1TYPE_FLUSH\s0" 4
+.IX Item "TYPE_FLUSH"
+.IP "\s-1TYPE_LOG\s0" 4
+.IX Item "TYPE_LOG"
+.IP "\s-1TYPE_NOTIF\s0" 4
+.IX Item "TYPE_NOTIF"
+.IP "\s-1TYPE_SHUTDOWN\s0" 4
+.IX Item "TYPE_SHUTDOWN"
+.IP "\s-1TYPE_DATASET\s0" 4
+.IX Item "TYPE_DATASET"
+.RE
+.RS 4
+.PD
+.Sp
+\&\fIname\fR is the name of the callback-function or the type of the data-set,
+depending on the value of \fItype\fR. (Please note that the type of the data-set
+is the value passed as \fIname\fR here and has nothing to do with the \fItype\fR
+argument which simply tells \fBplugin_register\fR what is being registered.)
+.Sp
+The last argument, \fIdata\fR, is either a function name or an array-reference.
+If \fItype\fR is \fB\s-1TYPE_DATASET\s0\fR, then the \fIdata\fR argument must be an
+array-reference which points to an array of hashes. Each hash describes one
+data-set. For the exact layout see \fBData-Set\fR above. Please note that
+there is a large number of predefined data-sets available in the \fBtypes.db\fR
+file which are automatically registered with collectd \- see \fItypes.db\fR\|(5) for
+a description of the format of this file.
+.Sp
+\&\fBNote\fR: Using \fBplugin_register\fR to register a data-set is deprecated. Add
+the new type to a custom \fItypes.db\fR\|(5) file instead. This functionality might
+be removed in a future version of collectd.
+.Sp
+If the \fItype\fR argument is any of the other types (\fB\s-1TYPE_INIT\s0\fR, \fB\s-1TYPE_READ\s0\fR,
+\&...) then \fIdata\fR is expected to be a function name. If the name is not
+prefixed with the plugin's package name collectd will add it automatically.
+The interface slightly differs from the C interface (which expects a function
+pointer instead) because Perl does not support to share references to
+subroutines between threads.
+.Sp
+These functions are called in the various stages of the daemon (see the
+section \*(L"\s-1WRITING YOUR OWN PLUGINS\*(R"\s0 above) and are passed the following
+arguments:
+.IP "\s-1TYPE_CONFIG\s0" 4
+.IX Item "TYPE_CONFIG"
+The only argument passed is \fIconfig-item\fR. See above for the layout of this
+data type.
+.IP "\s-1TYPE_INIT\s0" 4
+.IX Item "TYPE_INIT"
+.PD 0
+.IP "\s-1TYPE_READ\s0" 4
+.IX Item "TYPE_READ"
+.IP "\s-1TYPE_SHUTDOWN\s0" 4
+.IX Item "TYPE_SHUTDOWN"
+.PD
+No arguments are passed.
+.IP "\s-1TYPE_WRITE\s0" 4
+.IX Item "TYPE_WRITE"
+The arguments passed are \fItype\fR, \fIdata-set\fR, and \fIvalue-list\fR. \fItype\fR is a
+string. For the layout of \fIdata-set\fR and \fIvalue-list\fR see above.
+.IP "\s-1TYPE_FLUSH\s0" 4
+.IX Item "TYPE_FLUSH"
+The arguments passed are \fItimeout\fR and \fIidentifier\fR. \fItimeout\fR indicates
+that only data older than \fItimeout\fR seconds is to be flushed. \fIidentifier\fR
+specifies which values are to be flushed.
+.IP "\s-1TYPE_LOG\s0" 4
+.IX Item "TYPE_LOG"
+The arguments are \fIlog-level\fR and \fImessage\fR. The log level is small for
+important messages and high for less important messages. The least important
+level is \fB\s-1LOG_DEBUG\s0\fR, the most important level is \fB\s-1LOG_ERR\s0\fR. In between there
+are (from least to most important): \fB\s-1LOG_INFO\s0\fR, \fB\s-1LOG_NOTICE\s0\fR, and
+\&\fB\s-1LOG_WARNING\s0\fR. \fImessage\fR is simply a string \fBwithout\fR a newline at the end.
+.IP "\s-1TYPE_NOTIF\s0" 4
+.IX Item "TYPE_NOTIF"
+The only argument passed is \fInotification\fR. See above for the layout of this
+data type.
+.RE
+.RS 4
+.RE
+.IP "\fBplugin_unregister\fR (\fItype\fR, \fIplugin\fR)" 4
+.IX Item "plugin_unregister (type, plugin)"
+Removes a callback or data-set from collectd's internal list of
+functions\ / datasets.
+.IP "\fBplugin_dispatch_values\fR (\fIvalue-list\fR)" 4
+.IX Item "plugin_dispatch_values (value-list)"
+Submits a \fIvalue-list\fR to the daemon. If the data-set identified by
+\&\fIvalue-list\fR\->{\fItype\fR}
+is found (and the number of values matches the number of data-sources) then the
+type, data-set and value-list is passed to all write-callbacks that are
+registered with the daemon.
+.IP "\fBplugin_write\fR ([\fBplugins\fR => \fI...\fR][, \fBdatasets\fR => \fI...\fR], \fBvaluelists\fR => \fI...\fR)" 4
+.IX Item "plugin_write ([plugins => ...][, datasets => ...], valuelists => ...)"
+Calls the write function of the given \fIplugins\fR with the provided \fIdata
+sets\fR and \fIvalue lists\fR. In contrast to \fBplugin_dispatch_values\fR, it does
+not update collectd's internal cache and bypasses the filter mechanism (see
+\&\fIcollectd.conf\fR\|(5) for details). If the \fBplugins\fR argument has been omitted,
+the values will be dispatched to all registered write plugins. If the
+\&\fBdatasets\fR argument has been omitted, the required data sets are looked up
+according to the \f(CW\*(C`type\*(C'\fR 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 \fBdatasets\fR argument has been specified, the number of data sets has to
+equal the number of specified value lists.
+.IP "\fBplugin_flush\fR ([\fBtimeout\fR => \fItimeout\fR][, \fBplugins\fR => \fI...\fR][, \fBidentifiers\fR => \fI...\fR])" 4
+.IX Item "plugin_flush ([timeout => timeout][, plugins => ...][, identifiers => ...])"
+Flush one or more plugins. \fItimeout\fR and the specified \fIidentifiers\fR are
+passed on to the registered flush-callbacks. If omitted, the timeout defaults
+to \f(CW\*(C`\-1\*(C'\fR. The identifier defaults to the undefined value. If the \fBplugins\fR
+argument has been specified, only named plugins will be flushed. The value of
+the \fBplugins\fR and \fBidentifiers\fR arguments may either be a string or a
+reference to an array of strings.
+.IP "\fBplugin_dispatch_notification\fR (\fInotification\fR)" 4
+.IX Item "plugin_dispatch_notification (notification)"
+Submits a \fInotification\fR to the daemon which will then pass it to all
+notification-callbacks that are registered.
+.IP "\fBplugin_log\fR (\fIlog-level\fR, \fImessage\fR)" 4
+.IX Item "plugin_log (log-level, message)"
+Submits a \fImessage\fR of level \fIlog-level\fR to collectd's logging mechanism.
+The message is passed to all log-callbacks that are registered with collectd.
+.IP "\fB\s-1ERROR\s0\fR, \fB\s-1WARNING\s0\fR, \fB\s-1NOTICE\s0\fR, \fB\s-1INFO\s0\fR, \fB\s-1DEBUG\s0\fR (\fImessage\fR)" 4
+.IX Item "ERROR, WARNING, NOTICE, INFO, DEBUG (message)"
+Wrappers around \fBplugin_log\fR, using \fB\s-1LOG_ERR\s0\fR, \fB\s-1LOG_WARNING\s0\fR,
+\&\fB\s-1LOG_NOTICE\s0\fR, \fB\s-1LOG_INFO\s0\fR and \fB\s-1LOG_DEBUG\s0\fR respectively as \fIlog-level\fR.
+.IP "\fBplugin_get_interval\fR ()" 4
+.IX Item "plugin_get_interval ()"
+Returns the interval of the current plugin as a floating point number in
+seconds. This value depends on the interval configured within the
+\&\f(CW\*(C`LoadPlugin perl\*(C'\fR block or the global interval (see \fIcollectd.conf\fR\|(5) for
+details).
+.PP
+The following function provides the filter chain C\-interface to Perl-modules.
+It is exported by the \*(L":filter_chain\*(R" export tag (see the section \*(L"\s-1EXPORTS\*(R"\s0
+below).
+.IP "\fBfc_register\fR (\fItype\fR, \fIname\fR, \fIproc\fR)" 4
+.IX Item "fc_register (type, name, proc)"
+Registers filter chain callbacks with collectd.
+.Sp
+\&\fItype\fR may be any of:
+.RS 4
+.IP "\s-1FC_MATCH\s0" 4
+.IX Item "FC_MATCH"
+.PD 0
+.IP "\s-1FC_TARGET\s0" 4
+.IX Item "FC_TARGET"
+.RE
+.RS 4
+.PD
+.Sp
+\&\fIname\fR is the name of the match or target. By this name, the callbacks are
+identified in the configuration file when specifying a \fBMatch\fR or \fBTarget\fR
+block (see \fIcollectd.conf\fR\|(5) for details).
+.Sp
+\&\fIproc\fR is a hash reference. The hash includes up to three callbacks: an
+optional constructor (\fBcreate\fR) and destructor (\fBdestroy\fR) and a mandatory
+\&\fBmatch\fR or \fBinvoke\fR callback. \fBmatch\fR is called whenever processing an
+appropriate match, while \fBinvoke\fR is called whenever processing an
+appropriate target (see the section \*(L"\s-1FILTER CONFIGURATION\*(R"\s0 in
+\&\fIcollectd.conf\fR\|(5) for details). Just like any other callbacks, filter chain
+callbacks are identified by the function name rather than a function pointer
+because Perl does not support to share references to subroutines between
+threads. The following arguments are passed to the callbacks:
+.IP "create" 4
+.IX Item "create"
+The arguments passed are \fIconfig-item\fR and \fIuser-data\fR. See above for the
+layout of the config-item data-type. \fIuser-data\fR is a reference to a scalar
+value that may be used to store any information specific to this particular
+instance. The daemon does not care about this information at all. It's for the
+plugin's use only.
+.IP "destroy" 4
+.IX Item "destroy"
+The only argument passed is \fIuser-data\fR which is a reference to the user data
+initialized in the \fBcreate\fR callback. This callback may be used to cleanup
+instance-specific information and settings.
+.IP "match, invoke" 4
+.IX Item "match, invoke"
+The arguments passed are \fIdata-set\fR, \fIvalue-list\fR, \fImeta\fR and \fIuser-data\fR.
+See above for the layout of the data-set and value-list data-types. \fImeta\fR is
+a pointer to an array of meta information, just like the \fBmeta\fR member of the
+notification data-type (see above). \fIuser-data\fR is a reference to the user
+data initialized in the \fBcreate\fR callback.
+.RE
+.RS 4
+.RE
+.SH "GLOBAL VARIABLES"
+.IX Header "GLOBAL VARIABLES"
+.ie n .IP "\fB\fB$hostname_g\fB\fR" 4
+.el .IP "\fB\f(CB$hostname_g\fB\fR" 4
+.IX Item "$hostname_g"
+As the name suggests this variable keeps the hostname of the system collectd
+is running on. The value might be influenced by the \fBHostname\fR or
+\&\fBFQDNLookup\fR configuration options (see \fIcollectd.conf\fR\|(5) for details).
+.ie n .IP "\fB\fB$interval_g\fB\fR" 4
+.el .IP "\fB\f(CB$interval_g\fB\fR" 4
+.IX Item "$interval_g"
+This variable keeps the interval in seconds in which the read functions are
+queried (see the \fBInterval\fR configuration option).
+.Sp
+\&\fBNote:\fR This variable should no longer be used in favor of
+\&\f(CW\*(C`plugin_get_interval()\*(C'\fR (see above). This function takes any plugin-specific
+interval settings into account (see the \f(CW\*(C`Interval\*(C'\fR option of \f(CW\*(C`LoadPlugin\*(C'\fR in
+\&\fIcollectd.conf\fR\|(5) for details).
+.PP
+Any changes to these variables will be globally visible in collectd.
+.SH "EXPORTS"
+.IX Header "EXPORTS"
+By default no symbols are exported. However, the following export tags are
+available (\fB:all\fR will export all of them):
+.IP "\fB:plugin\fR" 4
+.IX Item ":plugin"
+.RS 4
+.PD 0
+.IP "\fBplugin_register\fR ()" 4
+.IX Item "plugin_register ()"
+.IP "\fBplugin_unregister\fR ()" 4
+.IX Item "plugin_unregister ()"
+.IP "\fBplugin_dispatch_values\fR ()" 4
+.IX Item "plugin_dispatch_values ()"
+.IP "\fBplugin_flush\fR ()" 4
+.IX Item "plugin_flush ()"
+.IP "\fBplugin_flush_one\fR ()" 4
+.IX Item "plugin_flush_one ()"
+.IP "\fBplugin_flush_all\fR ()" 4
+.IX Item "plugin_flush_all ()"
+.IP "\fBplugin_dispatch_notification\fR ()" 4
+.IX Item "plugin_dispatch_notification ()"
+.IP "\fBplugin_log\fR ()" 4
+.IX Item "plugin_log ()"
+.RE
+.RS 4
+.RE
+.IP "\fB:types\fR" 4
+.IX Item ":types"
+.RS 4
+.IP "\fB\s-1TYPE_CONFIG\s0\fR" 4
+.IX Item "TYPE_CONFIG"
+.IP "\fB\s-1TYPE_INIT\s0\fR" 4
+.IX Item "TYPE_INIT"
+.IP "\fB\s-1TYPE_READ\s0\fR" 4
+.IX Item "TYPE_READ"
+.IP "\fB\s-1TYPE_WRITE\s0\fR" 4
+.IX Item "TYPE_WRITE"
+.IP "\fB\s-1TYPE_FLUSH\s0\fR" 4
+.IX Item "TYPE_FLUSH"
+.IP "\fB\s-1TYPE_SHUTDOWN\s0\fR" 4
+.IX Item "TYPE_SHUTDOWN"
+.IP "\fB\s-1TYPE_LOG\s0\fR" 4
+.IX Item "TYPE_LOG"
+.IP "\fB\s-1TYPE_DATASET\s0\fR" 4
+.IX Item "TYPE_DATASET"
+.RE
+.RS 4
+.RE
+.IP "\fB:ds_types\fR" 4
+.IX Item ":ds_types"
+.RS 4
+.IP "\fB\s-1DS_TYPE_COUNTER\s0\fR" 4
+.IX Item "DS_TYPE_COUNTER"
+.IP "\fB\s-1DS_TYPE_GAUGE\s0\fR" 4
+.IX Item "DS_TYPE_GAUGE"
+.IP "\fB\s-1DS_TYPE_DERIVE\s0\fR" 4
+.IX Item "DS_TYPE_DERIVE"
+.IP "\fB\s-1DS_TYPE_ABSOLUTE\s0\fR" 4
+.IX Item "DS_TYPE_ABSOLUTE"
+.RE
+.RS 4
+.RE
+.IP "\fB:log\fR" 4
+.IX Item ":log"
+.RS 4
+.IP "\fB\s-1ERROR\s0\fR ()" 4
+.IX Item "ERROR ()"
+.IP "\fB\s-1WARNING\s0\fR ()" 4
+.IX Item "WARNING ()"
+.IP "\fB\s-1NOTICE\s0\fR ()" 4
+.IX Item "NOTICE ()"
+.IP "\fB\s-1INFO\s0\fR ()" 4
+.IX Item "INFO ()"
+.IP "\fB\s-1DEBUG\s0\fR ()" 4
+.IX Item "DEBUG ()"
+.IP "\fB\s-1LOG_ERR\s0\fR" 4
+.IX Item "LOG_ERR"
+.IP "\fB\s-1LOG_WARNING\s0\fR" 4
+.IX Item "LOG_WARNING"
+.IP "\fB\s-1LOG_NOTICE\s0\fR" 4
+.IX Item "LOG_NOTICE"
+.IP "\fB\s-1LOG_INFO\s0\fR" 4
+.IX Item "LOG_INFO"
+.IP "\fB\s-1LOG_DEBUG\s0\fR" 4
+.IX Item "LOG_DEBUG"
+.RE
+.RS 4
+.RE
+.IP "\fB:filter_chain\fR" 4
+.IX Item ":filter_chain"
+.RS 4
+.IP "\fBfc_register\fR" 4
+.IX Item "fc_register"
+.IP "\fB\s-1FC_MATCH_NO_MATCH\s0\fR" 4
+.IX Item "FC_MATCH_NO_MATCH"
+.IP "\fB\s-1FC_MATCH_MATCHES\s0\fR" 4
+.IX Item "FC_MATCH_MATCHES"
+.IP "\fB\s-1FC_TARGET_CONTINUE\s0\fR" 4
+.IX Item "FC_TARGET_CONTINUE"
+.IP "\fB\s-1FC_TARGET_STOP\s0\fR" 4
+.IX Item "FC_TARGET_STOP"
+.IP "\fB\s-1FC_TARGET_RETURN\s0\fR" 4
+.IX Item "FC_TARGET_RETURN"
+.RE
+.RS 4
+.RE
+.IP "\fB:fc_types\fR" 4
+.IX Item ":fc_types"
+.RS 4
+.IP "\fB\s-1FC_MATCH\s0\fR" 4
+.IX Item "FC_MATCH"
+.IP "\fB\s-1FC_TARGET\s0\fR" 4
+.IX Item "FC_TARGET"
+.RE
+.RS 4
+.RE
+.IP "\fB:notif\fR" 4
+.IX Item ":notif"
+.RS 4
+.IP "\fB\s-1NOTIF_FAILURE\s0\fR" 4
+.IX Item "NOTIF_FAILURE"
+.IP "\fB\s-1NOTIF_WARNING\s0\fR" 4
+.IX Item "NOTIF_WARNING"
+.IP "\fB\s-1NOTIF_OKAY\s0\fR" 4
+.IX Item "NOTIF_OKAY"
+.RE
+.RS 4
+.RE
+.IP "\fB:globals\fR" 4
+.IX Item ":globals"
+.RS 4
+.ie n .IP "\fB\fB$hostname_g\fB\fR" 4
+.el .IP "\fB\f(CB$hostname_g\fB\fR" 4
+.IX Item "$hostname_g"
+.ie n .IP "\fB\fB$interval_g\fB\fR" 4
+.el .IP "\fB\f(CB$interval_g\fB\fR" 4
+.IX Item "$interval_g"
+.RE
+.RS 4
+.RE
+.PD
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+Any Perl plugin will start similar to:
+.PP
+.Vb 1
+\& package Collectd::Plugins::FooBar;
+\&
+\& use strict;
+\& use warnings;
+\&
+\& use Collectd qw( :all );
+.Ve
+.PP
+A very simple read function might look like:
+.PP
+.Vb 7
+\& sub foobar_read
+\& {
+\& my $vl = { plugin => \*(Aqfoobar\*(Aq, type => \*(Aqgauge\*(Aq };
+\& $vl\->{\*(Aqvalues\*(Aq} = [ rand(42) ];
+\& plugin_dispatch_values ($vl);
+\& return 1;
+\& }
+.Ve
+.PP
+A very simple write function might look like:
+.PP
+.Vb 8
+\& sub foobar_write
+\& {
+\& my ($type, $ds, $vl) = @_;
+\& for (my $i = 0; $i < scalar (@$ds); ++$i) {
+\& print "$vl\->{\*(Aqplugin\*(Aq} ($vl\->{\*(Aqtype\*(Aq}): $vl\->{\*(Aqvalues\*(Aq}\->[$i]\en";
+\& }
+\& return 1;
+\& }
+.Ve
+.PP
+A very simple match callback might look like:
+.PP
+.Vb 9
+\& sub foobar_match
+\& {
+\& my ($ds, $vl, $meta, $user_data) = @_;
+\& if (matches($ds, $vl)) {
+\& return FC_MATCH_MATCHES;
+\& } else {
+\& return FC_MATCH_NO_MATCH;
+\& }
+\& }
+.Ve
+.PP
+To register those functions with collectd:
+.PP
+.Vb 2
+\& plugin_register (TYPE_READ, "foobar", "foobar_read");
+\& plugin_register (TYPE_WRITE, "foobar", "foobar_write");
+\&
+\& fc_register (FC_MATCH, "foobar", "foobar_match");
+.Ve
+.PP
+See the section \*(L"\s-1DATA TYPES\*(R"\s0 above for a complete documentation of the data
+types used by the read, write and match functions.
+.SH "NOTES"
+.IX Header "NOTES"
+.IP "\(bu" 4
+Please feel free to send in new plugins to collectd's mailing list at
+<collectd\ at\ collectd.org> for review and, possibly,
+inclusion in the main distribution. In the latter case, we will take care of
+keeping the plugin up to date and adapting it to new versions of collectd.
+.Sp
+Before submitting your plugin, please take a look at
+<http://collectd.org/dev\-info.shtml>.
+.SH "CAVEATS"
+.IX Header "CAVEATS"
+.IP "\(bu" 4
+collectd is heavily multi-threaded. Each collectd thread accessing the perl
+plugin will be mapped to a Perl interpreter thread (see \fIthreads\fR\|(3perl)).
+Any such thread will be created and destroyed transparently and on-the-fly.
+.Sp
+Hence, any plugin has to be thread-safe if it provides several entry points
+from collectd (i.\ e. if it registers more than one callback or if a
+registered callback may be called more than once in parallel). Please note
+that no data is shared between threads by default. You have to use the
+\&\fBthreads::shared\fR module to do so.
+.IP "\(bu" 4
+Each function name registered with collectd has to be available before the
+first thread has been created (i.\ e. basically at compile time). This
+basically means that hacks (yes, I really consider this to be a hack) like
+\&\f(CW\*(C`*foo = \e&bar; plugin_register (TYPE_READ, "plugin", "foo");\*(C'\fR most likely
+will not work. This is due to the fact that the symbol table is not shared
+across different threads.
+.IP "\(bu" 4
+Each plugin is usually only loaded once and kept in memory for performance
+reasons. Therefore, \s-1END\s0 blocks are only executed once when collectd shuts
+down. You should not rely on \s-1END\s0 blocks anyway \- use \fBshutdown functions\fR
+instead.
+.IP "\(bu" 4
+The perl plugin exports the internal \s-1API\s0 of collectd which is considered
+unstable and subject to change at any time. We try hard to not break backwards
+compatibility in the Perl \s-1API\s0 during the life cycle of one major release.
+However, this cannot be guaranteed at all times. Watch out for warnings
+dispatched by the perl plugin after upgrades.
+.SH "KNOWN BUGS"
+.IX Header "KNOWN BUGS"
+.IP "\(bu" 4
+Currently, it is not possible to flush a single Perl plugin only. You can
+either flush all Perl plugins or none at all and you have to use \f(CW\*(C`perl\*(C'\fR as
+plugin name when doing so.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIcollectd\fR\|(1),
+\&\fIcollectd.conf\fR\|(5),
+\&\fIcollectd\-exec\fR\|(5),
+\&\fItypes.db\fR\|(5),
+\&\fIperl\fR\|(1),
+\&\fIthreads\fR\|(3perl),
+\&\fIthreads::shared\fR\|(3perl),
+\&\fIperldebug\fR\|(1)
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+The \f(CW\*(C`perl plugin\*(C'\fR has been written by Sebastian Harl
+<sh\ at\ tokkee.org>.
+.PP
+This manpage has been written by Florian Forster
+<octo\ at\ collectd.org> and Sebastian Harl
+<sh\ at\ tokkee.org>.