Add a manual page.

Wrote a manual page explaining the new functions, and also mentioning
the few we override.

Signed-off-by: Gergely Nagy <algernon@balabit.hu>

3 files changed, 220 insertions, 2 deletions

diff --git a/TODO.org b/TODO.org
index efbf304..664b91c 100644
--- a/TODO.org
+++ b/TODO.org
@@ -34,8 +34,13 @@ should we add the timestamp as a ts_sec & ts_nsec pair?
 
 It's probably best to stay with the string, though.
 
-* WIP Documentation
-** TODO cee-syslog(3)
+* DONE Documentation
+CLOSED: [2012-03-22 Thu 12:27]
+- CLOSING NOTE [2012-03-22 Thu 12:27]
+** DONE cee-syslog(3)
+CLOSED: [2012-03-22 Thu 12:27]
+- CLOSING NOTE [2012-03-22 Thu 12:27] \\
+  Manual page is now complete.
 The main entry point of the documentation, will detail the purpose and
 goals of the library, along with the functions and constants it
 provides. cee_syslog(), cee_vsyslog(), cee_legacy_*(), cee_openlog()
diff --git a/lib/Makefile.am b/lib/Makefile.am
index d5c99a3..54e2914 100644
--- a/lib/Makefile.am
+++ b/lib/Makefile.am
@@ -15,3 +15,5 @@ libcee_syslog_include_HEADERS	= \
 
 pkgconfigdir			= $(libdir)/pkgconfig
 pkgconfig_DATA			= libcee-syslog.pc
+
+man3_MANS			= cee_syslog.3
diff --git a/lib/cee-syslog.3 b/lib/cee-syslog.3
new file mode 100644
index 0000000..f8e9dd2
--- /dev/null
+++ b/lib/cee-syslog.3
@@ -0,0 +1,211 @@
+.\" cee-syslog.3 -- CEE-enhanced syslog manual
+.\"
+.\" Copyright (c) 2012 BalaBit IT Security Ltd.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY BALABIT AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL BALABIT OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.TH CEE_SYSLOG 3 2012-03-22 "cee\-syslog" "CEE\-enhanced syslog Manual"
+
+.SH NAME
+cee_openlog, cee_syslog, cee_vsyslog, cee_legacy_syslog,
+cee_legacy_vsyslog \- send CEE-enhanced messages to the system logger
+.br
+cee_format, cee_vformat \- format CEE\-enhanced messages, without
+sending them to the system logger
+
+.SH SYNOPSIS
+.B #include <cee/cee\-syslog.h>
+.sp
+.BI "void cee_openlog(const char *" ident ", int " option ", int " facility );
+.br
+
+.br
+.BI "void cee_syslog(int " priority ", const char *" format ", ...);"
+.br
+.BI "void cee_vsyslog(int " priority ", const char *" format ", va_list " ap );
+.br
+
+.br
+.BI "void cee_legacy_syslog(int " priority ", const char *" format ", ...);"
+.br
+.BI "void cee_legacy_vsyslog(int " priority ", const char *" format ", va_list " ap );
+.br
+
+.br
+.BI "char *cee_format(int " priority ", const char *" format ", ...);"
+.br
+.BI "char *cee_vformat(int " priority ", const char *" format ", va_list " ap );
+
+.SH DESCRIPTION
+.BR cee_openlog (),
+(also aliased to
+.BR openlog ())
+is a wrapper around the original
+.BR openlog ()
+function, which opens a connection to the system logger for a
+program. The updated version adds support for a number of new option
+flags, described below.
+
+.sp
+.BR cee_legacy_syslog ()
+and
+.BR cee_legacy_vsyslog ()
+are both thin layers over the original
+.BR syslog ()
+and
+.BR vsyslog ()
+functions, and the library overrides the original functions with this
+two. The only change these functions bring, are that the message they
+generate will be a CEE\-enhanced message, with a JSON payload. See
+below for an explanation on what this means.
+
+.sp
+.BR cee_syslog ()
+and
+.BR cee_vsyslog ()
+are two new functions provided by the library, that have similar
+interface to the legacy
+.BR syslog ()
+functions, but they can be used to add arbitrary key-value pairs to
+the emitted message. After the
+.I msg_format
+format string, and any other parameters it refers to, there must be a
+NULL-terminated list of
+.IR key ", " "value format" ", " "format parameters" .
+Each of these pairs, constructed from the
+.I key
+and the
+.BR printf (3)-style
+.I value format
+will be added to the generated message.
+
+.sp
+.BR cee_format ()
+and
+.BR cee_vformat ()
+do the same as the syslog variants above, except the formatted payload
+is not sent to syslog, but returned as a newly allocated string.
+
+.SH "CEE PAYLOAD"
+
+All of the improved
+.BR syslog ()
+functions, the legacy and overridden ones and the new ones too turn
+the original syslog message into a CEE\-enabled JSON payload, with the
+original message put into the
+.I msg
+field, and any additional fields put into the same structure.
+
+By default, unless the
+.B LOG_CEE_NODISCOVER
+option flag is set, all of these functions will also add a few
+automatically discovered fields into the payload:
+
+.TP 15
+.I pid
+The process ID of the program, as returned by
+.BR getpid ().
+The value of this is \- by default \- determined at the time of
+calling
+.BR cee_openlog (),
+but if caching is disabled, it will be rechecked every time.
+.TP
+.IR facility " and " priority
+The syslog facility and priority as a text string.
+.TP
+.I program
+The identification set at the time of
+.BR cee_openlog ().
+.TP
+.IR uid " and " gid
+The user and group ID of the process, determined at
+.BR cee_openlog ()
+time by default, unless caching is disabled.
+.TP
+.I host
+The name of the originating host, determined at
+.BR cee_openlog ()
+time by default, using
+.BR gethostname ().
+.TP
+.I timestamp
+High\-precision timestamp, in textual format. Included by default, but
+can be controlled by the
+.B LOG_CEE_NOTIME
+option flag at
+.BR cee_openlog ()
+time.
+.PP
+
+.SH "EXTRA OPTION FLAGS"
+The
+.I option
+argument to
+.BR cee_openlog ()
+is an OR of any of the original
+.BR openlog ()
+flags, and these:
+.TP 15
+.B LOG_CEE_NODISCOVER
+Disable all automatic\-discovery, and only include the
+.I message
+and any specified
+.I key\-value
+pairs in the generated message.
+.TP
+.B LOG_CEE_NOCACHE
+When automatic discovery is enabled, disable caching certain
+properties, that might change between the call to
+.BR openlog ()
+and the
+.BR cee_syslog ()
+invocation.
+.TP
+.B LOG_CEE_NOCACHE_UID
+Disable caching the
+.IR uid " and " gid
+caching when automatic discovery is enabled, but do cache the rest.
+.TP
+.B LOG_CEE_NOTIME
+Do not add a high\-precision timestamp to the generated message when
+automatic discovery is enabled.
+.PP
+
+.SH EXAMPLES
+.nf
+
+    cee_syslog(LOG_NOTICE, "Logged in user: %s", username,
+               "service", "%s", service,
+               "auth-method", "%s", auth_method,
+               "sessionid", "%d", session_id,
+               NULL);
+.fi
+
+.SH "SEE ALSO"
+.BR syslog (1)
+
+.SH COLOPHON
+This page is part of the
+.I libcee\-syslog
+project, and is available under the same 2-clause BSD license as the
+rest of the project.