Import most FAQ items from old web site

Import most of the FAQ entries from our old web site.  A few outdated
questions have been omitted, many of the imported ones were updated in
one way or another, and the order of the development-related questions
has been changed.  Also, the phrasing of some questions has been
modified (just to make the headings shorter).

For the record, this is the original list of questions from the old web
site:

General
-------

* Who controls the Nagios Plugins project?
* What license is Nagios Plugins distributed under?
* Who owns the copyright for the Nagios Plugin code?
* Can I submit a patch to this project?
* Do you accept donations?

Compiling
---------

* ./configure appears to hang
* check_ldap, check_radius or check_pgsql don't compile even though
  configure output says the required libraries are present
* How come check_http/check_tcp doesn't work with --ssl?
* How do I compile the Nagios::Plugin perl module?
* I can't compile check_mysql on solaris
* I get '":types" is not exported by the Params::Validate module' when
  running tests
* Why does Solaris use pst3 for check_procs?

Installing
----------

* Some of the root plugins (check_dhcp and check_icmp) haven't been
  installed.  What's happening?
* Why aren't my plugins installed as the nagios user?  And what about
  root plugins?

Development
-----------

* How do I use Git?
* Can I add extra tests to the C routines?
* Can I use the Nagios Plugins in my own project?
* How can I find out more about writing a plugin?
* How do I make changes on nagiosmib?
* How do I prove the C routines work?
* How do I use and update Gnulib?
* How do I use the Nagios::Plugin perl module?
* How do the test parameters in NPTest.pm work?
* Private C APIs

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: # %-->