title: Private C APIs
parent: FAQ
---

# Private C APIs

This page describes the Monitoring 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][guidelines].

## Basic Functions

### np\_init(char \*plugin\_name, int argc, char \*\*argv)

Initialize the Monitoring 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.

### np\_cleanup(void)

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:

* 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 (e.g., 32 or 64 bit).
* Binary data may include a structure containing a pointer.  Pointer values
  may not be used in the reading program - i.e., you need to overwrite the
  value with something `malloc(3)`ed 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}`.

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][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`.

### np\_state\_read(void)

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

[guidelines]: doc/guidelines.html "Monitoring Plugin Development Guidelines"
[extra-opts]: doc/extra-opts.html "Extra-Opts"

<!--% # vim:set filetype=markdown textwidth=78 joinspaces expandtab: # %-->