NAME

       Monitoring::Plugin::Functions - functions to simplify the creation of Nagios plugins

SYNOPSIS

           # 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 => \@crit, warning => \@warn);
           ($code, $message) = check_messages(
             critical => \@crit, warning => \@warn,
             ok => \@ok );

           # get_shortname - return the default short name for this plugin
           #   (as used by plugin_exit/die; not exported by default)
           $shortname = get_shortname();

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.

   EXPORTS
       Nagios status code constants are exported by default:

           OK
           WARNING
           CRITICAL
           UNKNOWN
           DEPENDENT

       as are the following functions:

           plugin_exit
           plugin_die
           check_messages

       The following variables and functions are exported only on request:

           %ERRORS
           %STATUS_TEXT
           get_shortname
           max_state
           max_state_alt

   FUNCTIONS
       The following functions are supported:

       plugin_exit( <CODE>, $message )
           Exit with return code CODE, and a standard nagios message of the form "PLUGIN CODE - $message".

       plugin_die( $message, [CODE] )
           Same as plugin_exit(), except that CODE is optional, defaulting to UNKNOWN.  NOTE: exceptions are not
           raised by default to calling code.  Set $_use_die flag if this functionality is required (see test
           code).

       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.

               # Scalar context
               $code = check_messages(critical => \@crit, warning => \@warn);
               # List context
               ($code, $msg) = check_messages(critical => \@crit, warning => \@warn);

           check_messages() accepts the following named arguments:

           critical => ARRAYREF
               An arrayref of critical error messages - check_messages() returns CRITICAL if this arrayref is
               non-empty. Mandatory.

           warning => ARRAYREF
               An arrayref of warning error messages - check_messages() returns WARNING if this arrayref is non-
               empty ('critical' is checked first). Mandatory.

           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.

           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 @crit is non-empty, check_messages would return:

                   join( $join, @crit )

               as the result message. Optional; default: ' ' (space).

           join_all => SCALAR
               By default, only one set of messages are joined and returned in the result message i.e. if the
               result is CRITICAL, only the 'critical' messages are included in the result; if WARNING, only the
               'warning' messages are included; if OK, the 'ok' messages are included (if supplied) i.e. the
               default is to return an 'errors-only' type message.

               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.

       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

               uc basename( $ENV{PLUGIN_NAME} || $ENV{NAGIOS_PLUGIN} || $0 )

           with any leading 'CHECK_' and trailing file suffixes removed.

           get_shortname is not exported by default, so must be explicitly imported.

       max_state(@a)
           Returns the worst state in the array. Order is: CRITICAL, WARNING, OK, UNKNOWN, DEPENDENT

           The typical usage of max_state is to initialise the state as UNKNOWN and use it on the result of
           various test. If no test were performed successfully the state will still be UNKNOWN.

       max_state_alt(@a)
           Returns the worst state in the array. Order is: CRITICAL, WARNING, UNKNOWN, DEPENDENT, OK

           This is a true definition of a max state (OK last) and should be used if the internal tests performed
           can return UNKNOWN.

SEE ALSO

       Monitoring::Plugin; the nagios plugin developer guidelines at
       https://www.monitoring-plugins.org/doc/guidelines.html.

AUTHOR

       This code is maintained by the Monitoring Plugin Development Team: see https://monitoring-plugins.org

COPYRIGHT AND LICENSE

       Copyright (C) 2014      by Monitoring Plugin Team Copyright (C) 2006-2014 by Nagios Plugin Development
       Team

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.