From 375950b38def08f52fc3c3e48dabd70465199947 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Thu, 22 Mar 2012 12:43:19 +0100 Subject: Rename the manual page to libcee-syslog.3 Signed-off-by: Gergely Nagy --- lib/Makefile.am | 2 +- lib/cee-syslog.3 | 211 ---------------------------------------------------- lib/libcee-syslog.3 | 211 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+), 212 deletions(-) delete mode 100644 lib/cee-syslog.3 create mode 100644 lib/libcee-syslog.3 diff --git a/lib/Makefile.am b/lib/Makefile.am index 54e2914..ab40994 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -16,4 +16,4 @@ libcee_syslog_include_HEADERS = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libcee-syslog.pc -man3_MANS = cee_syslog.3 +man3_MANS = libcee-syslog.3 diff --git a/lib/cee-syslog.3 b/lib/cee-syslog.3 deleted file mode 100644 index f8e9dd2..0000000 --- a/lib/cee-syslog.3 +++ /dev/null @@ -1,211 +0,0 @@ -.\" 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 -.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. diff --git a/lib/libcee-syslog.3 b/lib/libcee-syslog.3 new file mode 100644 index 0000000..f8e9dd2 --- /dev/null +++ b/lib/libcee-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 +.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. -- cgit