Private C APIs

This page describes the Nagios Plugin 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 developer guidelines.

Basic functions

np_init(char *plugin_name, argc, argv)

Initialise the nagios plugin routines. Pass the plugin name and argc and argv from main().

A variable nagios_plugin will be created for internal use.

np_set_args(argc, 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.

np_cleanup()

Used to cleanup 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:

  • There will be problems if a remote host is checked from two different Nagios instances, as the state file on the remote host will be updated twice as often
  • binary data may not restore on a program compiled with different options from the program that saved it, eg 32 or 64 bit
  • binary data may include a structure containing a pointer. Pointer values may not be used in the reading program - ie you need to overwrite the value with something malloced in the current run of the program
  • State files could be left lying around. We recommend you run a regular job to remove unmodified state files older than 1 week

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}.

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 2nd 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.

np_state_read()

Reads the state file and returns a state_data variable.

This routine will call die() with UNKNOWN if:

  • There was a problem reading the state file

Returns NULL if:

  • No state file exists - this is possible on the first run
  • The state file format (internally held by the plugin) does not match
  • The state data format (passed in np_enable_state) does not match

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 pointed 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.