ossp-pkg/l2/l2_syslog.pod
1.1
##
## L2 - OSSP Logging Library
## Copyright (c) 2001-2002 The OSSP Project (http://www.ossp.org/)
## Copyright (c) 2001-2002 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
## This file is part of OSSP L2, a flexible logging library which
## can be found at http://www.ossp.org/pkg/l2/.
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED 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 THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## 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.
##
## l2_syslog.pod: L2 syslog replacement manual page
##
=pod
=head1 NAME
B<l2_syslog> - L2 syslog replacement
=head1 VERSION
OSSP L2 L2_VERSION_STR
=head1 SYNOPSIS
=over 4
CPPFLAGS="-I /FIXME/include"
LDFLAGS="-L /FIXME/lib"
LIBS="-Ll2syslog -Ll2"
=back
=head1 DESCRIPTION
The B<l2_syslog> is a library offering the syslog(3) API otherwise
provided by the Standard C Library. Instead of writing dump log files
it uses the powerful L2 logging capabilities. It is a drop-in
replacement which enables any syslog(3) consumer to take advantage of L2
by just linking this library against an existing object. The source code
remains unchanged.
=head1 FILES
The B<l2_syslog> library reads configuration sections located in one or
more files. The path to the directory containing these file(s) is
specified at compile time and is given to the configure script via
'--with-syslog-cfgdir=...'.
=head1 OPERATION
When an application calles openlog(3) it passes an ident string and a
log facility along. B<l2_syslog> tries to read the file
C<syslog-cfgdir/>I<ident>. If the file is not readable, all files
matching C<syslog-cfgdir/l2*> are read. All data that has been read in
is then parsed for configuration sections. These are identified by
'%ident I<match>' at the beginning of line. The I<match> argument is a
PCRE (Perl Compatible Regular Expression) that is matched against a
string concatenated from I<ident>/I<facility> given to the openlog(3)
call. The configuration section contains a L2 specification enclosed in
curly brackets where the closing bracket must be placed on the beginning
of a line. The L2 specification may contain $1, $2 ... variables
which are filled from regex matches enclosed in round brackets. A
channel tree is build from each matching section and all trees form a
single metatree. Further calls to syslog(3) will then inject log
messages into this metatree.
=head1 EXAMPLE
=over 4
%ident sendmail/.* {
debug:
prefix(
prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ",
timezone=local)
-> file(
path="sendmail.debug.log",
append=0,perm=432)
}
=back
=head1 OPENPKG
OpenPKG RPM packages must require "l2" for both %BuildPreReq and
%PreReq.
=head1 SEE ALSO
syslog(3).
=head1 AUTHOR
Thomas Lotterer <thl@ossp.org>
=cut
