Private C APIs

This page describes the Nagios Plugins routines that can be accessed from the internal library.

This page is in development, so these are not guaranteed to be available. As the API matures and is available in libraries, this information will be migrated to the Development Guidelines.

Basic Functions

np_init(char *plugin_name, int argc, char **argv)

Initialize the Nagios Plugins routines. Pass the plugin name and argc and argv from main().

A variable nagios_plugin will be created for internal use.

np_set_args(int argc, char **argv)

Sets the internally held argc and argv values.

Shouldn't really need this, but due to np_extra_opts(), this is set after that call.


Used to clean up allocated memory by the nagios_plugin variable. This is called by the die() routine before exiting.

State Information

Saving and restoring state allows a plugin to know the last results and thus work out differences. This is especially useful when a plugin is capturing counter information, which increases with every request.

This currently works by saving state information to a file, though the API doesn't care what the backend implementation is.

Note: Binary data is not currently supported.

Some things to be aware of, if you use state information:

np_enable_state(char *keyname, int data_version)

Enables the plugin state retention routines. Will set the filename for the state file to be .../{keyname}.

The keyname will have any non alphanumerics replaced with "_".

If keyname is NULL, will generate an SHA1 keyname based on the argv of the plugin (using the Extra-Opts parsed version, if applicable).

Note: The keyname should be uniquely defined for a particular service, to avoid a second invocation of the plugin to use the state information from a different invocation. If in doubt, set keyname=NULL and allow the routine to calculate the keyname.


Reads the state file and returns a state_data variable.

This routine will call die() with UNKNOWN if:

Returns NULL if:

Your plugin should always check for NULL. It is recommended that your plugin returns OK on NULL as this is similar to a "first run".

If valid data was read, a pointer will be returned which points to a struct of:

typedef struct state_data_struct {
    time_t time;
    void *data;
    int length; /* Of binary data. */
} state_data;

np_state_write_string(time_t data_time, char *string)

If data_time==0, use current time. Creates state file, with state format version. Writes data version, time, and data. Creates a temporary file and then renames into place. There is a possible loss of data if two things writing to same key at same time, but there will not be a corrupted state file.

np_state_write_binary(time_t data_time, char *start, int length)

Same as np_state_write_string(), but writes binary data. Currently unimplemented.