##
##  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<OSSP l2syslog> - L2 based syslog(3) replacement

=head1 VERSION

OSSP L2 L2_VERSION_STR

=head1 SYNOPSIS

 LDFLAGS=`l2-config --ldflags` \
 LIBS="-ll2syslog -ll2" \
 ./configure [...]

=head1 DESCRIPTION

B<OSSP l2syslog> is a companion library to B<OSSP l2>, offering the
syslog(3) API otherwise provided by the Standard C Library (F<libc>).
Instead of writing to the syslogd(8) process, it uses the powerful
B<OSSP l2> logging capabilities. It is a drop-in link-time replacement
which enables any syslog(3) consumer to take advantage of B<OSSP l2>
by just linking this library in before F<libc>. The source code of the
program remains unchanged.

=head1 FILES

The B<OSSP l2syslog> 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
C<--with-cfgdir=>I<cfgdir>.

=head1 OPERATION

If an application calls openlog(3) it passes an identification string
(I<ident>) and a logging facility (I<facility>) along. B<OSSP l2syslog>
tries to read the file "C<cfgdir>C</l2.>I<ident>". If the file is not
readable, all files matching I<cfgdir>C</l2.*> are read.

In both cases, all data that has been read in is then parsed for
configuration sections. These are identified by "C<ident >I<match>"
at the beginning of a 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 an B<OSSP l2> specification enclosed
in curly brackets where the closing bracket must be placed on the
beginning of a line and terminated with a semicolon. The B<OSSP l2>
specification may contain $1, $2, ... variables which are filled in from
the I<match> regex parts enclosed in round brackets.

An B<OSSP l2> channel tree is build from each matching section and all
found trees are merged together with a "null" channel to form a single
tree. Further calls to syslog(3) will then inject log messages into this
channel tree.

=head1 EXAMPLE

 ident sendmail/.* {
   debug:
     prefix(prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ",
            timezone=local)
     -> file(path="sendmail.debug.log", append=0,perm=432)
 };


=head1 OPENPKG

OpenPKG RPM packages must require the package "l2" in both C<BuildPreReq> and
C<PreReq> and force the packaged application to link against F<libl2syslog.a>.

=head1 SEE ALSO

syslog(3).

=head1 AUTHOR

Thomas Lotterer <thl@ossp.org>

=cut