head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	2002.07.09.08.50.12;	author rse;	state dead;
branches;
next	1.2;

1.2
date	2002.07.02.09.50.51;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2002.06.27.09.24.40;	author thl;	state Exp;
branches;
next	;


desc
@@


1.3
log
@axe out l2syslog stuff (will occur on OSSP fsl soon)
@
text
@##
##  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
@


1.2
log
@try to understand the spec and do cleanups in parallel ;)
@
text
@@


1.1
log
@write down what we expect from this utility
@
text
@d34 1
a34 1
B<l2_syslog> - L2 syslog replacement
d42 3
a44 9
=over 4

CPPFLAGS="-I /FIXME/include"

LDFLAGS="-L /FIXME/lib"

LIBS="-Ll2syslog -Ll2"

=back
d48 7
a54 6
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.
d58 4
a61 4
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=...'.
d65 21
a85 15
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.
d89 3
a91 7
=over 4

%ident sendmail/.* {

    debug:
        prefix(
            prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ",
d93 2
a94 5
        -> file(
            path="sendmail.debug.log",
            append=0,perm=432)

}
a95 1
=back
d99 2
a100 2
OpenPKG RPM packages must require "l2" for both %BuildPreReq and
%PreReq.
@