.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "l2 3" .TH l2 3 "L2 0.9.13" "08-Jun-2007" "Flexible Logging" .SH "NAME" \&\fBOSSP l2\fR \- Flexible Logging .SH "VERSION" .IX Header "VERSION" \&\s-1OSSP\s0 l2 0.9.13 (08-Jun-2007) .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&... .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fB\s-1OSSP\s0 l2\fR is a C library providing a very flexible and sophisticated Unix logging facility. It is based on the model of arbitrary number of channels, stacked together in a top-down data flow tree structure with filtering channels in internal nodes and output channels on the leave nodes. .PP Channel trees can be either constructed manually through lower-level \&\s-1API\s0 functions or all at once with a single \s-1API\s0 function controlled by a compact syntactical description of the channel tree. For generating log messages a printf-style formatting engine is provided which can be extended through callback functions. The data flow inside the channel tree is controlled by (eight fixed and nine custom) logging message severity levels which are assigned to each individual channel. .PP Channels are implemented by channel handlers which can be even customer supplied for creating own channels which seamlessly integrate into the framework. For convenience reasons, \fB\s-1OSSP\s0 l2\fR already ships with pre-implemented filtering (noop, filter, prefix, buffer) and output (null, fd, file, pipe, socket, syslog, smtp) channels which already cover mostly all use cases of logging. .PP A language is provided to allow for channel specification and configuration. Thus, the channel tree can be constructed either by the \s-1API\s0 and its \s-1ANSI\s0 C bindings or through the use of this \fB\s-1OSSP\s0 l2\fR channel definition language. Applying the \s-1API\s0 allows fine grained control of the channel tree. Additionally, the \&\s-1API\s0 allows for a more interactive channel definition. However, using the channel definition language to define the channel tree is more convenient, and takes less coding effort. The channel definition language is almost always sufficient for an application using \fB\s-1OSSP\s0 l2\fR. .SH "LOGGING LEVELS" .IX Header "LOGGING LEVELS" \&\s-1PANIC\s0 fatal error \-> immediate abort (\s-1SIGBUS\s0, \s-1SIGSEGV\s0) \&\s-1CRITICAL\s0 temporary failure \-> sleep, retry possible (malloc == \s-1NULL\s0) \&\s-1ERROR\s0 functionality error \&\s-1WARNING\s0 functionality successful \&\s-1NOTICE\s0 operation, statistics, start/stop \&\-\-\- border line production/testing \-\-\- \&\s-1INFO\s0 step-by-step \&\s-1TRACE\s0 I/O tracing \&\-\-\- border line end\-user/developer \&\s-1DEBUG\s0 debugging messages .SH "CHANNEL TREE SPECIFICATION" .IX Header "CHANNEL TREE SPECIFICATION" An \fB\s-1OSSP\s0 l2\fR channel tree can be descriped by a textual specification according to the following Backus-Naur-Form (\s-1BNF\s0): .PP .Vb 20 \& tree ::= stream \& stream ::= channel \& | channel "->" stream \& | channel "->" "{" streams "}" \& streams ::= stream \& | stream ";" streams \& channel ::= channel_level "/" channel_level ":" channel_cons \& | channel_level ":" channel_cons \& | channel_cons \& channel_level ::= IDENTIFIER \& | "(" channel_level_mask ")" \& channel_level_mask ::= IDENTIFIER \& | IDENTIFIER "|" channel_level_mask \& channel_cons ::= IDENTIFIER channel_params \& channel_params ::= EMPTY \& | "(" channel_param_list ")" \& channel_param_list ::= EMPTY \& | channel_param \& | channel_param "," channel_param_list \& channel_param ::= IDENTIFIER "=" PARAMETER .Ve .PP An example of such a channel tree specification is: .PP .Vb 10 \& noop -> { \& debug: prefix(prefix="[%d-%m-%Y/%H:%M:%S] ") \& -> buffer(size=16384) \& -> file(path=foo.log, trunc=0); \& error: syslog(ident=foo, facility=user, \& remotehost=syslog.example.com, \& target=remote); \& panic: smtp(host=mail.example.com, \& rcpt=foo@example.com); \& } .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" The following functions are provided by the \fB\s-1OSSP\s0 l2\fR \s-1API:\s0 .SH "AVAILABLE CHANNEL HANDLERS" .IX Header "AVAILABLE CHANNEL HANDLERS" .Sh "Syslog Output Channel Handler (l2_handler_syslog)" .IX Subsection "Syslog Output Channel Handler (l2_handler_syslog)" The Syslog output channel handler \f(CW\*(C`l2_handler_syslog\*(C'\fR sends the incoming message either via \fIsyslog\fR\|(3) to a local \fIsyslogd\fR\|(8) or via \s-1BSD\s0 Syslog protocol to a remote Syslog service. It conforms to \s-1RFC\s0 3164 (The \&\s-1BSD\s0 syslog Protocol; C. Lonvick; August 2001). .PP It provides the following channel parameters: .ie n .IP "\fBtarget\fR (optional, ""char *"")" 4 .el .IP "\fBtarget\fR (optional, \f(CWchar *\fR)" 4 .IX Item "target (optional, char *)" Sets the location of the target Syslog service. Possible values are \f(CW\*(C`local\*(C'\fR (the default) or \f(CW\*(C`remote\*(C'\fR. If \f(CW\*(C`remote\*(C'\fR is used, the parameters \f(CW\*(C`remotehost\*(C'\fR has to be set, too. .ie n .IP "\fBremotehost\fR (optional, ""char *"")" 4 .el .IP "\fBremotehost\fR (optional, \f(CWchar *\fR)" 4 .IX Item "remotehost (optional, char *)" Host name or \s-1IP\s0 address of the remote Syslog service. No default exists, user has to provide value. .ie n .IP "\fBremoteport\fR (optional, ""int"")" 4 .el .IP "\fBremoteport\fR (optional, \f(CWint\fR)" 4 .IX Item "remoteport (optional, int)" Port number of the remote \s-1SMTP\s0 service. Default is \f(CW514\fR. .ie n .IP "\fBlocalhost\fR (optional, ""char *"")" 4 .el .IP "\fBlocalhost\fR (optional, \f(CWchar *\fR)" 4 .IX Item "localhost (optional, char *)" The name of the local host, \fIwithout\fR any domain appended. .ie n .IP "\fBfacility\fR (optional, ""char *"")" 4 .el .IP "\fBfacility\fR (optional, \f(CWchar *\fR)" 4 .IX Item "facility (optional, char *)" The Syslog facility used for all messages. It has to be one of the following: \f(CW\*(C`kern\*(C'\fR, \f(CW\*(C`user\*(C'\fR, \f(CW\*(C`mail\*(C'\fR, \f(CW\*(C`daemon\*(C'\fR, \f(CW\*(C`auth\*(C'\fR, \f(CW\*(C`syslog\*(C'\fR, \&\f(CW\*(C`lpr\*(C'\fR, \f(CW\*(C`news\*(C'\fR, \f(CW\*(C`uucp\*(C'\fR, \f(CW\*(C`cron\*(C'\fR, \f(CW\*(C`authpriv\*(C'\fR, \f(CW\*(C`ftp\*(C'\fR, \f(CW\*(C`ntp\*(C'\fR, \&\f(CW\*(C`security\*(C'\fR, \f(CW\*(C`console\*(C'\fR, \f(CW\*(C`clock\*(C'\fR, \f(CW\*(C`local0\*(C'\fR, \f(CW\*(C`local1\*(C'\fR, \f(CW\*(C`local2\*(C'\fR, \&\f(CW\*(C`local3\*(C'\fR, \f(CW\*(C`local4\*(C'\fR, \f(CW\*(C`local5\*(C'\fR, \f(CW\*(C`local6\*(C'\fR, \f(CW\*(C`local7\*(C'\fR. .ie n .IP "\fBident\fR (\fImandatory\fR, ""char *"")" 4 .el .IP "\fBident\fR (\fImandatory\fR, \f(CWchar *\fR)" 4 .IX Item "ident (mandatory, char *)" Arbitrary string identifying the program. There is no default, user has to provide value. .ie n .IP "\fBlogpid\fR (optional, ""int"")" 4 .el .IP "\fBlogpid\fR (optional, \f(CWint\fR)" 4 .IX Item "logpid (optional, int)" Boolean flag whether to add the Process \s-1ID\s0 (pid) to the \fBident\fR tag in messages. Default is \f(CW0\fR. .Sh "Pipe Output Channel Handler (l2_handler_pipe)" .IX Subsection "Pipe Output Channel Handler (l2_handler_pipe)" The Pipe output channel handler \f(CW\*(C`l2_handler_pipe\*(C'\fR sends the incoming message to the standard input of a chosen command, passed to the l2 library as a parameter when calling l2_configure. .PP Any command that operates on the standard input (c language descriptor stdin) can be used, but attention is advised due to the wide variety of commands and their particular exit behaviours. .PP Attention! Commands that exit on their own and with a success return value will not be restarted, however those returning with non-zero exit codes will be restarted. \fB\s-1OSSP\s0 l2\fR reopens closed pipe channels due to faulted command processes in this way. Should such a reconnection be required after a command's successful self\-termination, \fIl2_channel_open()\fR may be called again on the same pipe channel pointer previously used. Stream logging will then write to the pipe channel handler, which will forward the log messages to the given command as always. To find out if a pipe channel has closed due to the behaviour of its command process, the \fIl2_channel_write()\fR operation may be called on it with a non-NULL message parameter, and 0 as the buffsize parameter. The return result will be L2_OK if the channel is open. Using the C language, such a check might look like: .PP \&\s-1TODO\s0 \s-1NOTE\s0 \s-1FROM\s0 \s-1MICHAEL:\s0 This info will change once the pipe channel handler is redesigned to allow for proper process termination, signal handling of such processes, and subsequent channel closing!!!!!!!!!!! .PP .Vb 3 \& if (l2_channel_write(pPipechannel, L2_LEVEL_NOTICE, "", 0) != L2_OK) \& if (l2_channel_open(pPipechannel) != L2_OK) \& exit(1); /* failure */ .Ve .PP The command passed to the pipe channel handler may also be stopped while still using a \fB\s-1OSSP\s0 l2\fR stream log. If a command process is stopped no action is taken until further logging occurs. As soon as the pipe channel handler receives a message due to a l2_stream_log operation, it will attempt to restart the stopped command process and write to its standard input. If the effort to restart the command process fails then the command process is considered dead, and \fB\s-1OSSP\s0 l2\fR will terminate the process and close the channel. A \&\fIl2_channel_open()\fR will then reopen the pipe channel using configuration information previously entered with \fIl2_channel_configure()\fR. .PP It provides the following channel parameters: .ie n .IP "\fBcommand\fR (optional, ""char *"")" 4 .el .IP "\fBcommand\fR (optional, \f(CWchar *\fR)" 4 .IX Item "command (optional, char *)" \&\fB\s-1OSSP\s0 l2\fR will execute the command at this user-provided path, and pipe messages to its standard input when l2_stream_log operations are called. .Sh "\s-1SMTP\s0 Output Channel Handler (l2_handler_smtp)" .IX Subsection "SMTP Output Channel Handler (l2_handler_smtp)" The \s-1SMTP\s0 output channel handler \f(CW\*(C`l2_handler_smtp\*(C'\fR sends the incoming message via Simple Mail Transfer Protocol (\s-1SMTP\s0) as an Email to a remote mail service. It conforms to \s-1RFC\s0 2821 (Simple Mail Transfer Protocol; J. Klensin; April 2001) and \s-1RFC\s0 2822 (Internet Message Format; P. Resnick; April 2001). .PP It provides the following channel parameters: .ie n .IP "\fBprogname\fR (optional, ""char *"")" 4 .el .IP "\fBprogname\fR (optional, \f(CWchar *\fR)" 4 .IX Item "progname (optional, char *)" Arbitrary string identifying the program using \fB\s-1OSSP\s0 l2\fR. Default is \f(CW\*(C`NULL\*(C'\fR which means no program identification. .ie n .IP "\fBlocalhost\fR (optional, ""char *"")" 4 .el .IP "\fBlocalhost\fR (optional, \f(CWchar *\fR)" 4 .IX Item "localhost (optional, char *)" Hostname of the underlying machine. Default is set through \fIuname\fR\|(3) or \f(CW\*(C`localhost\*(C'\fR. .ie n .IP "\fBlocaluser\fR (optional, ""char *"")" 4 .el .IP "\fBlocaluser\fR (optional, \f(CWchar *\fR)" 4 .IX Item "localuser (optional, char *)" Username corresponding to the \s-1UID\s0 of the underlying process. Default is set through resolving \fIgetuid\fR\|(2) or \f(CW\*(C`uid#N\*(C'\fR. .ie n .IP "\fBfrom\fR (optional, ""char *"")" 4 .el .IP "\fBfrom\fR (optional, \f(CWchar *\fR)" 4 .IX Item "from (optional, char *)" Sender Email address for outgoing mails. Default is set through \fBlocaluser\fR and \fBlocalhost\fR. .ie n .IP "\fBrcpt\fR (\fImandatory\fR, ""char *"")" 4 .el .IP "\fBrcpt\fR (\fImandatory\fR, \f(CWchar *\fR)" 4 .IX Item "rcpt (mandatory, char *)" Recipient Email address for outgoing mails. No default exists, user has to provide value. .ie n .IP "\fBsubject\fR (optional, ""char *"")" 4 .el .IP "\fBsubject\fR (optional, \f(CWchar *\fR)" 4 .IX Item "subject (optional, char *)" Arbitrary string identifying the generated Email message. Default is \f(CW\*(C`[L2] log channel output on {localhost}\*(C'\fR. .ie n .IP "\fBhost\fR (\fImandatory\fR, ""char *"")" 4 .el .IP "\fBhost\fR (\fImandatory\fR, \f(CWchar *\fR)" 4 .IX Item "host (mandatory, char *)" Host name or \s-1IP\s0 address of the remote \s-1SMTP\s0 service. No default exists, user has to provide value. .ie n .IP "\fBport\fR (optional, ""char *"")" 4 .el .IP "\fBport\fR (optional, \f(CWchar *\fR)" 4 .IX Item "port (optional, char *)" Port name or number of the remote \s-1SMTP\s0 service. Default is \f(CW\*(C`smtp\*(C'\fR (25). .ie n .IP "\fBtimeout\fR (optional, ""int"")" 4 .el .IP "\fBtimeout\fR (optional, \f(CWint\fR)" 4 .IX Item "timeout (optional, int)" Timeout in seconds for all I/O operations. Default is \f(CW30\fR.