1 files changed, 116 insertions, 0 deletions

diff --git a/web/input/doc/faq/private-c-api.md b/web/input/doc/faq/private-c-api.md
new file mode 100644
index 0000000..585ca42
--- /dev/null
+++ b/web/input/doc/faq/private-c-api.md
@@ -0,0 +1,116 @@
+title: Private C APIs
+parent: FAQ
+---
+
+# 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][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.
+
+### 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 "Nagios Plugin Development Guidelines"
+[extra-opts]: doc/extra-opts.html "Extra-Opts"
+
+<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->