HOME

sh-3ll 1.0
DIR:/home/.cpan/build/Monitoring-Plugin-0.40-0/blib/man3/
Current File : /home/.cpan/build/Monitoring-Plugin-0.40-0/blib/man3/Monitoring::Plugin::Functions.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Monitoring::Plugin::Functions 3"
.TH Monitoring::Plugin::Functions 3 "2018-07-25" "perl v5.26.3" "User Contributed Perl Documentation"
.\" 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"
Monitoring::Plugin::Functions \- functions to simplify the creation of
Nagios plugins
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # Constants OK, WARNING, CRITICAL, and UNKNOWN exported by default
\&    use Monitoring::Plugin::Functions;
\&
\&    # plugin_exit( CODE, $message ) \- exit with error code CODE,
\&    # and message "PLUGIN CODE \- $message"
\&    plugin_exit( CRITICAL, $critical_error ) if $critical_error;
\&    plugin_exit( WARNING, $warning_error )   if $warning_error;
\&    plugin_exit( OK, $result );
\&
\&    # plugin_die( $message, [$CODE] ) \- just like plugin_exit(),
\&    # but CODE is optional, defaulting to UNKNOWN
\&    do_something()
\&      or plugin_die("do_something() failed horribly");
\&    do_something_critical()
\&      or plugin_die("do_something_critical() failed", CRITICAL);
\&
\&    # check_messages \- check a set of message arrays, returning a
\&    # CODE and/or a result message
\&    $code = check_messages(critical => \e@crit, warning => \e@warn);
\&    ($code, $message) = check_messages(
\&      critical => \e@crit, warning => \e@warn,
\&      ok => \e@ok );
\&
\&    # get_shortname \- return the default short name for this plugin
\&    #   (as used by plugin_exit/die; not exported by default)
\&    $shortname = get_shortname();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is part of the Monitoring::Plugin family, a set of modules
for simplifying the creation of Nagios plugins. This module exports
convenience functions for the class methods provided by
Monitoring::Plugin. It is intended for those who prefer a simpler
functional interface, and who do not need the additional
functionality of Monitoring::Plugin.
.SS "\s-1EXPORTS\s0"
.IX Subsection "EXPORTS"
Nagios status code constants are exported by default:
.PP
.Vb 5
\&    OK
\&    WARNING
\&    CRITICAL
\&    UNKNOWN
\&    DEPENDENT
.Ve
.PP
as are the following functions:
.PP
.Vb 3
\&    plugin_exit
\&    plugin_die
\&    check_messages
.Ve
.PP
The following variables and functions are exported only on request:
.PP
.Vb 5
\&    %ERRORS
\&    %STATUS_TEXT
\&    get_shortname
\&    max_state
\&    max_state_alt
.Ve
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
The following functions are supported:
.ie n .IP "plugin_exit( <\s-1CODE\s0>, $message )" 4
.el .IP "plugin_exit( <\s-1CODE\s0>, \f(CW$message\fR )" 4
.IX Item "plugin_exit( <CODE>, $message )"
Exit with return code \s-1CODE,\s0 and a standard nagios message of the
form \*(L"\s-1PLUGIN CODE\s0 \- \f(CW$message\fR\*(R".
.ie n .IP "plugin_die( $message, [\s-1CODE\s0] )" 4
.el .IP "plugin_die( \f(CW$message\fR, [\s-1CODE\s0] )" 4
.IX Item "plugin_die( $message, [CODE] )"
Same as \fBplugin_exit()\fR, except that \s-1CODE\s0 is optional, defaulting
to \s-1UNKNOWN.\s0  \s-1NOTE:\s0 exceptions are not raised by default to calling code.
Set \f(CW$_use_die\fR flag if this functionality is required (see test code).
.IP "check_messages( critical => \e@crit, warning => \e@warn )" 4
.IX Item "check_messages( critical => @crit, warning => @warn )"
Convenience function to check a set of message arrays and return
an appropriate nagios return code and/or a result message. Returns
only a return code in scalar context; returns a return code and an
error message in list context i.e.
.Sp
.Vb 4
\&    # Scalar context
\&    $code = check_messages(critical => \e@crit, warning => \e@warn);
\&    # List context
\&    ($code, $msg) = check_messages(critical => \e@crit, warning => \e@warn);
.Ve
.Sp
\&\fBcheck_messages()\fR accepts the following named arguments:
.RS 4
.IP "critical => \s-1ARRAYREF\s0" 4
.IX Item "critical => ARRAYREF"
An arrayref of critical error messages \- \fBcheck_messages()\fR returns
\&\s-1CRITICAL\s0 if this arrayref is non-empty. Mandatory.
.IP "warning => \s-1ARRAYREF\s0" 4
.IX Item "warning => ARRAYREF"
An arrayref of warning error messages \- \fBcheck_messages()\fR returns
\&\s-1WARNING\s0 if this arrayref is non-empty ('critical' is checked
first). Mandatory.
.IP "ok => \s-1ARRAYREF\s0 | \s-1SCALAR\s0" 4
.IX Item "ok => ARRAYREF | SCALAR"
An arrayref of informational messages (or a single scalar message),
used in list context if both the 'critical' and 'warning' arrayrefs
are empty. Optional.
.IP "join => \s-1SCALAR\s0" 4
.IX Item "join => SCALAR"
A string used to join the relevant array to generate the message
string returned in list context i.e. if the 'critical' array \f(CW@crit\fR
is non-empty, check_messages would return:
.Sp
.Vb 1
\&    join( $join, @crit )
.Ve
.Sp
as the result message. Optional; default: ' ' (space).
.IP "join_all => \s-1SCALAR\s0" 4
.IX Item "join_all => SCALAR"
By default, only one set of messages are joined and returned in the
result message i.e. if the result is \s-1CRITICAL,\s0 only the 'critical'
messages are included in the result; if \s-1WARNING,\s0 only the 'warning'
messages are included; if \s-1OK,\s0 the 'ok' messages are included (if
supplied) i.e. the default is to return an 'errors\-only' type
message.
.Sp
If join_all is supplied, however, it will be used as a string to
join the resultant critical, warning, and ok messages together i.e.
all messages are joined and returned.
.RE
.RS 4
.RE
.IP "get_shortname" 4
.IX Item "get_shortname"
Return the default shortname used for this plugin i.e. the first
token reported by plugin_exit/plugin_die. The default is basically
.Sp
.Vb 1
\&    uc basename( $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0 )
.Ve
.Sp
with any leading '\s-1CHECK_\s0' and trailing file suffixes removed.
.Sp
get_shortname is not exported by default, so must be explicitly
imported.
.IP "max_state(@a)" 4
.IX Item "max_state(@a)"
Returns the worst state in the array. Order is: \s-1CRITICAL, WARNING, OK, UNKNOWN,
DEPENDENT\s0
.Sp
The typical usage of max_state is to initialise the state as \s-1UNKNOWN\s0 and use
it on the result of various test. If no test were performed successfully the
state will still be \s-1UNKNOWN.\s0
.IP "max_state_alt(@a)" 4
.IX Item "max_state_alt(@a)"
Returns the worst state in the array. Order is: \s-1CRITICAL, WARNING, UNKNOWN,
DEPENDENT, OK\s0
.Sp
This is a true definition of a max state (\s-1OK\s0 last) and should be used if the
internal tests performed can return \s-1UNKNOWN.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Monitoring::Plugin; the nagios plugin developer guidelines at
https://www.monitoring\-plugins.org/doc/guidelines.html.
.SH "AUTHOR"
.IX Header "AUTHOR"
This code is maintained by the Monitoring Plugin Development Team: see
https://monitoring\-plugins.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2014      by Monitoring Plugin Team
Copyright (C) 2006\-2014 by Nagios Plugin Development Team
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.