--- fsl.pod 2002/07/27 15:37:21 1.12
+++ fsl.pod 2002/07/27 18:13:32 1.13
@@ -40,9 +40,9 @@
=head1 SYNOPSIS
- LDFLAGS="`fsl-config --all --ldflags`" \
- LIBS="`fsl-config --all --libs`" \
- ./configure [...]
+LDFLAGS=`B<fsl-config --all --ldflags>`
+LIBS=`B<fsl-config --all --libs>`
+./configure [...]
=head1 DESCRIPTION
@@ -56,50 +56,58 @@
=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</fsl.>I<ident>". If the file is not
-readable, all files matching I<cfgdir>C</fsl.*> 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 and terminated with a semicolon. The B<OSSP l2>
-specification may contain $1 ... $9 variables which are filled in from
-the I<match> regex parts enclosed in round brackets. The $0 variable
-captures the wholly match and $$ diverts to a single escaped $.
-
-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 L2SPEC
-
-The "logging library" (L2) builds its working configuration using a
-global environment object and channels which are interconnected to form
-a tree. The environment object holds general internal information and
-maintains the registration of formatters. The channels are used to
-process the logging message and use formatters to transform it. The
-root channel of the tree and each intermediate channel might have one or
-more children below it, passing the processed message down the tree. The
-leafs of the tree are constructed by channels specifically designed for
-outputting the message. Every logging message is injected into a
-channel, most likely the uppermost one, and traverses down the tree
-where channels with multiple children duplicate the message. L2 allows
-a developer to build this tree programmatically. In addition, L2 also
-supports building up the channel tree using a text based specification
-called the l2spec. The l2spec offers maximum flexibility as a program
-can read a l2spec created by a system administrator and pass it to L2
-verbatim without even knowing anything about existing channels. When
-this approach is used, a newly designed channel can be used by an
-existing program by just linking in the latest lib_l2. The main program
-remains unmodified.
+(I<ident>) and a logging facility (I<facility>) along. B<OSSP fsl>
+tries to read the file "I<cfgdir>C</fsl.>I<ident>". If the file is not
+readable, all files matching "I<cfgdir>C</fsl.*>" are read.
+
+In both cases, all data that has been read in is parsed for
+configuration sections via B<OSSP cfg>. These are identified by "C<ident
+>I<match>C< >I<l2-spec>C<;>" directives. The I<match> argument is an B<OSSP
+pcre> (Perl-compatible) regular expression that is matched against a
+string concatenated from "I<ident>/I<facility>" given to the openlog(3)
+call.
+
+The I<l2-spec> (single) argument is an B<OSSP l2> channel tree
+specification, usually quoted with B<OSSP cfg> flexible quotes (to make
+it a single B<OSSP cfg> argument) like "C<q{...}>". The I<l2-spec>
+may contain "C<$1>", ..., "C<$9>" variables which are filled in from
+the I<match> regular expression parts enclosed in round brackets. The
+"C<$0>" variable captures the wholly match and "C<$$>" diverts to a
+single escaped "C<$>".
+
+An B<OSSP l2> channel tree is build from all I<l2-spec> on each matching
+"C<ident>" directives and all found trees are merged together with a
+top "C<noop>" channel to form a single channel tree. Further calls to
+syslog(3) will then inject log messages into this channel tree.
+
+=head1 OSSP L2 CHANNEL TREE SPECIFICATION
+
+B<OSSP l2> builds its working configuration using a global environment
+object and channels which are interconnected to form a channel tree.
+The environment object holds general internal information and maintains
+the registration of formatters. The channels are used to process the
+logging message and use formatters to transform it. The root channel of
+the tree and each intermediate channel might have one or more children
+below it, passing the processed message down the tree. The leafs of the
+tree are constructed by channels specifically designed for outputting
+the message.
+
+Every logging message is injected into a channel, most likely the
+uppermost one, and traverses down the tree where channels with
+multiple children duplicate the message. B<OSSP l2> allows a developer
+to build this tree programmatically. In addition, B<OSSP l2> also
+supports building up the channel tree using a text based "channel tree
+specification" language. This declarative language offers maximum
+flexibility as a program can read a specification created by a system
+administrator and pass it to B<OSSP l2> verbatim without even knowing
+anything about existing channels. If this approach is used, a newly
+designed channel can be used by an existing program by just linking in
+the latest B<OSSP l2> version. The main program remains unmodified.
-B<tree> ::= B<stream>
+An B<OSSP l2> channel tree specification is defined by the following
+context-free grammar:
+
+B<l2-spec> ::= B<stream>
B<stream> ::= I<empty>
| B<channel>
@@ -159,151 +167,182 @@
B<param_value> ::= single-quoted, double-quoted
or unquoted text
-Here is a description of all available channels. The table lists their
-B<channel_name> prefixed with an 'o' or a 'f' indicating it's operating
-as an output or a filter channel. All parameters are B<param_names>
-listed, including the type of each parameter which is either a string
-(STR) or integer (INT) and an 'm' or 'o' indicating the paramter is
-optional or mandatory. Also, the default value for each paramter is
-listed, if there is one.
+=head1 AVAILABLE OSSP L2 CHANNELS
-The "buffer" channel buffers messages poured in from upper channels. It
-flushes the messages down to the lower channels when the buffered space
-exceeds the buffer size, when a given time interval is reached (0
-disables this feature) or when a newly arrived message has a level that
-matches the levelflush mask.
+B<OSSP l2> provides various channels. The following lists their
+B<channel_name> prefixed with an 'C<o>' or a 'C<f>' indicating whether
+it is operating as an output or filter channel. All parameters to
+B<param_names> are listed, including the type of each parameter which
+is either a string (C<STR>) or integer (C<INT>) and an 'C<m>' or 'C<o>'
+indicating the paramter is optional or mandatory. Also, the default
+value for each paramter is listed, if there is one.
- f buffer (INT size o [bytes] =4096
- INT interval o [sec] =0 (disabled)
- INT levelflush o [level] =0 (none)
- );
-
-The "fd" channel passes messages poured in from upper channels to
-the open file identified by the given filedescriptor. Note that UNIX
-usually alloctes 1 for STDOUT and 2 for STDERR.
-
- o fd (INT filedescriptor m
- );
+=head2 Buffering Filter Channel (buffer)
-The "file" channel opens a file at the given path and passes messages
-poured in from upper channels to this file. If the file at the given
-path already exists, additional data is either appended (append=1) or
-the existing file is truncated (append=0). The desired permissions of
-the file can be set. Note that due to a limitation of the current parser
-only decimal numbers are accepted, so have fun doing octal to decimal
-conversion. Here're some hints
-
- rw-rw-rw- \0666 =438 rw-r--r-- \0644 =420
- rw-rw-r-- \0664 =436 rw-r----- \0640 =416
- rw-rw---- \0660 =432 rw------- \0600 =384
-
- o file (STR path m
- INT append o [0=truncate|1=append] =1
- INT perm o [decimal] =420
- );
+The B<buffer> channel buffers messages poured in from upper channels. It
+flushes the messages down to the lower channels when the buffered space
+exceeds the buffer I<size>, when a given time I<interval> is reached (0
+disables this feature) or when a newly arrived message has a level that
+matches the I<levelflush> mask.
-The "filter" channel filters messages poured in from upper channels. A
-regex is used against the incoming message and the normal operation is
-that only matching messages are passed down the tree. Setting negate
-reverses the matching decision. Comparisons are case sensitive unless
-nocase is set.
-
- f filter (STR regex m [PCRE]
- INT negate o [0=normal,1=negate] =0
- INT nocase o [0=case,1=nocase] =0
- );
+ f buffer (INT size o [bytes] =4096
+ INT interval o [sec] =0 (disabled)
+ INT levelflush o [level] =0 (none)
+ )
+
+=head2 Filedescriptor Output Channel (fd)
+
+The B<fd> channel passes messages poured in from upper channels to the
+open file identified by the given I<filedescriptor>. Note that Unix
+usually allocates C<1> for F<stdout> and C<2> for F<stderr>.
+
+ o fd (INT filedescriptor m
+ )
+
+=head2 File Output Channel (file)
+
+The B<file> channel opens a file at the given I<path> and passes
+messages poured in from upper channels to this file. If the file at
+the given path already exists, additional data is either appended
+(I<append>=1) or the existing file is truncated (I<append>=0). The
+desired permissions of the file can be set.
+
+ o file (STR path m
+ INT append o [0=truncate|1=append] =1
+ INT perm o [decimal] =420
+ )
+
+Notice: due to a limitation of the current parser only decimal numbers
+are accepted, so have fun doing octal to decimal conversion. Here're
+some hints:
+
+ rw-rw-rw- \0666 =438 rw-r--r-- \0644 =420
+ rw-rw-r-- \0664 =436 rw-r----- \0640 =416
+ rw-rw---- \0660 =432 rw------- \0600 =384
+
+=head2 Filtering Channel (filter)
+
+The B<filter> channel filters messages poured in from upper channels.
+A regular expression is applied against the incoming message and the
+normal operation is that only matching messages are passed down the
+tree. Setting I<negate> reverses the matching decision. Comparisons are
+case sensitive unless I<nocase> is set.
+
+ f filter (STR regex m [PCRE]
+ INT negate o [0=normal,1=negate] =0
+ INT nocase o [0=case,1=nocase] =0
+ )
+
+=head2 Internet Relay Chat Output Channel (irc)
+
+The B<irc> channel opens a connection to a given IRC channel and
+passes messages poured in from upper channels to this IRC channel. If
+configured, the message posted to IRC channel contains the I<progname>
+for easy identification of the sending host.
+
+ o irc (STR progname o [string]
+ STR localhost o [hostname|address] =nodename or "localhost"
+ STR localuser o [string] =name or "uid#"num
+ STR nickname o [string] =localuser
+ STR username o [string] =localuser"@"localhost
+ STR realname o [string] =username
+ STR channel o [string] ="#l2"
+ INT join o [01] =1 use JOIN/PART
+ STR host m [hostname|address]
+ STR port o [tcpport] =6667
+ INT timeout o [sec] =30
+ )
-The "irc" channel opens a connection to a given IRC channel and passes
-messages poured in from upper channels to this IRC channel. If
-configured, the message posted to IRC channel contains the progname for
-easy identification of the sending host.
-
- o irc (STR progname o [string]
- STR localhost o [hostname|address] =nodename or "localhost"
- STR localuser o [string] =name or "uid#"num
- STR nickname o [string] =localuser
- STR username o [string] =localuser"@"localhost
- STR realname o [string] =username
- STR channel o [string] ="#l2"
- INT join o [01] =1 use JOIN/PART
- STR host m [hostname|address]
- STR port o [tcpport] =6667
- INT timeout o [sec] =30
- );
+=head2 No Operation Filtering Channel (noop)
-The "noop" channel can be used to divert incoming messages to multiple
+The B<noop> channel can be used to divert incoming messages to multiple
pathes down the tree. Otherwise is does not do anything put passing the
-messages along. It has no configuration parameters.
+messages along. It has no configuration parameters at all.
+
+ f noop ()
- f noop ()
+=head2 No Operation Output Channel (null)
-The "null" channel discards any incoming messages and creates no output
+The B<null> channel discards any incoming messages and creates no output
at all. It has no configuration parameters.
- o null ()
+ o null ()
-The "pipe" channel executes a given command and pipes messages poured in
-from upper channels to the commands stdin. The command can be executed
-directly or run by "/bin/sh -c". The lifetime of the connection can be
-adjusted by setting runtime to either "cont" for a continuous
-pipethrough with command restart after termination or "one" for oneshot
-where the connection is broken when the command terminates.
-
- o pipe (STR execmode m [direct|shell]
- STR runtime m [cont|one]
- STR path m [dir/file]
- );
+=head2 Command Pipe Output Channel (pipe)
-The "prefix" channel prefixes messages poured in from upper channels.
-The format string may contain variables prefixed with a '%'. These are
-expanded using the internal formatters
-
- L loglevel
- N nodename
- P pid
+The B<pipe> channel executes a given command and pipes messages poured
+in from upper channels to the commands F<stdin>. The command can be
+executed directly or run by "C</bin/sh -c>". The lifetime of the
+connection can be adjusted by setting I<runtime> to either "C<cont>"
+for a continuous pipe-through with command restart after termination or
+"C<one>" for one-shot where the connection is dropped when the command
+terminates.
+
+ o pipe (STR execmode m [direct|shell]
+ STR runtime m [cont|one]
+ STR path m [dir/file]
+ )
+
+=head2 Prefixing Filtering Channel (prefix)
+
+The B<prefix> channel prefixes messages poured in from upper channels.
+The I<prefix> format string may contain formatting variables prefixed
+with a 'C<%>'. These are expanded using the internal B<OSSP fsl>
+formatters
+
+ L loglevel
+ N nodename
+ P pid
then expansion continues to use application specific formatters where
-FSL offers
+B<OSSP l2> offers
- D dump
- S string
- m errno
+ D dump
+ S string
+ m errno
and finally remaining variables are expaned by strftime(3).
- f prefix (STR prefix m [string]
- STR timezone o [local|utc] =local
- );
+ f prefix (STR prefix m [string]
+ STR timezone o [local|utc] =local
+ )
-The "smtp" channel forwards messages poured in from upper channels to
-remote hosts using the Simple Mail Transfer Protocol. It is possible to
-specify the local address to bind to which is useful for multihomed
-hosts.
+=head2 Simple Mail Transfer Protocol Output Channel (smtp)
- o smtp (STR progname o [string]
- STR localhost o [hostname|address] =nodename or "localhost"
- STR localuser o [string] =name or "uid#"num
- STR from o [string] =localuser"@"localhost
- STR rcpt m [string]
- STR subject o [string] ="[L2] ..."
- STR host m [hostname|address]
- STR port o [tcpport] ="smtp"
- INT timeout o [sec] =30
- );
+The B<smtp> channel forwards messages poured in from upper channels
+to remote hosts using the Simple Mail Transfer Protocol (SMTP). It is
+possible to specify the local address to bind to which is useful for
+multi-homed hosts.
-The "socket" channel forwards messages poured in from upper channels to
-daemons on remote hosts using raw UDP communication or TCP connections.
+ o smtp (STR progname o [string]
+ STR localhost o [hostname|address] =nodename or "localhost"
+ STR localuser o [string] =name or "uid#"num
+ STR from o [string] =localuser"@"localhost
+ STR rcpt m [string]
+ STR subject o [string] ="[L2] ..."
+ STR host m [hostname|address]
+ STR port o [tcpport] ="smtp"
+ INT timeout o [sec] =30
+ )
- o socket (STR proto o [udp|tcp] =tcp
- STR host m [hostname|address]
- STR port m [udpport|tcpport]
- INT timeout o [sec] =30
- );
+=head2 Raw Socket Output Channel (socket)
-The "syslog" channel forwards messages poured in from upper channels
-either to the local syslog or passes it to a remote syslogd. It is
-possible to specify the local address to bind to which is useful for
-multihomed hosts.
+The B<socket> channel forwards messages poured in from upper channels to
+daemons on remote hosts using raw UDP communication or TCP connections.
+
+ o socket (STR proto o [udp|tcp] =tcp
+ STR host m [hostname|address]
+ STR port m [udpport|tcpport]
+ INT timeout o [sec] =30
+ )
+
+=head2 Syslog Remote Output Channel (syslog)
+
+The B<syslog> channel forwards messages poured in from upper channels
+either to the local syslog(3) library or passes it directly via UDP
+communication to a remote (or even local) syslogd(8). It is possible
+to specify the local address to bind to which is useful for multi-homed
+hosts.
o syslog (STR target o [local|remote] =local
STR remotehost o [hostname|address]
@@ -314,99 +353,133 @@
INT logpid o [0=no,1=yes] =1
);
- EXAMPLE
- - for a very simple l2spec writing everything to STDERR (FD#2)
-
- fd(filedescriptor=2)
-
- EXAMPLE
- - for a simple l2spec writing notices and more important
- messages to a file
-
- notice: file(path="/var/log/file")
-
- EXAMPLE for a very complex l2spec
-
- noop
- -> {
- (info): filter(
- regex="foo"
- )
- -> syslog(
- remotehost="localhost"
- );
- info: prefix(
- )
- -> {
- debug/error: buffer(
- size=1024
- )
- -> file(
- path="a"
- );
- (trace|debug)/(trace): buffer(
- size=65536
- ) ->
- file(
- path="b"
- )
- };
- prefix() -> {
- warning: filter(
- negate=1,
- regex="foo"
- )
- -> irc(
- host=irc.dev.de.cw.net
- );
- error: filter(
- nocase=1,
- regex="foo"
- )
- -> smtp(
- host=sv1.dev.de.cw.net
- );
- panic: smtp(
- host=sv1.dev.de.cw.net
- )
- }
- };
-
-=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)
+NOTICE: Because B<OSSP fsl> implements the syslog(3) library API itself,
+use cannot use the I<target>=C<local> feature of B<OSSP l2>, because it
+would lead to a endless run-time loop! Be careful here, please.
+
+=head1 EXAMPLES
+
+=head2 Example 1: simple stderr logging
+
+A very simple I<l2-spec> just writing everything to F<stderr>
+(filedescriptor 2):
+
+ ident .*
+ fd(filedescriptor=2)
+
+=head2 Example 2: simple logfile writing
+
+A very simple I<l2-spec> just writing notices and more important
+messages to a logfile with each message prepended with a classical
+timestamp prefix:
+
+ notice: prefix(prefix="[%b %d %H:%M:%S]")
+ -> file(path="/var/log/foo")
+
+=head2 Example 3: complex logging
+
+A very complex I<l2-spec> logging example where... FIXME...
+
+ noop
+ -> {
+ (info): filter(
+ regex="foo"
+ )
+ -> syslog(
+ remotehost="localhost"
+ );
+ info: prefix(
+ prefix="[%b %d %H:%M:%S] <%L> [%P]"
+ )
+ -> {
+ debug/error: buffer(
+ size=1024
+ )
+ -> file(
+ path="a"
+ );
+ (trace|debug)/(trace): buffer(
+ size=65536
+ ) ->
+ file(
+ path="b"
+ )
+ };
+ prefix() -> {
+ warning: filter(
+ negate=1,
+ regex="foo"
+ )
+ -> irc(
+ host=irc.dev.de.cw.net
+ );
+ error: filter(
+ nocase=1,
+ regex="foo"
+ )
+ -> smtp(
+ host=sv1.dev.de.cw.net
+ );
+ panic: smtp(
+ host=sv1.dev.de.cw.net
+ )
+ }
};
=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>.
+=over 4
-F<@sysconfdir@/fsl.*>
+=item F<FSL_CFGDIR/fsl.*>
-=head1 OPENPKG
+B<OSSP fsl> reads configuration sections located in these files. The
+path FSL_CFGDIR of the directory containing these file(s) has to be
+specified at build-time of B<OSSP fsl> via the F<configure> option
+C<--with-cfgdir=>I<cfgdir>.
-OpenPKG RPM packages must require the package "fsl" in both C<BuildPreReq> and
-C<PreReq> and force the packaged application to link against F<libfsl.a>.
+=back
=head1 SEE ALSO
-syslog(3),
-B<OSSP l2> http://www.ossp.org/pkg/lib/l2/,
-B<OSSP cfg> http://www.ossp.org/pkg/lib/cfg/,
-B<OpenPKG> http://www.openpkg.org/.
+=over 4
+
+=item syslog(2)
+
+The B<POSIX> API which B<OSSP fsl> replaces under link-time.
+
+=item B<OSSP l2>, l2(3), http://www.ossp.org/pkg/lib/l2/
+
+The underlying library providing the flexible logging
+functionality (see I<l2-spec> above).
+
+=item B<OSSP cfg>, cfg(3), http://www.ossp.org/pkg/lib/cfg/
+
+The underlying library providing the parsing
+of the B<OSSP fsl> configuration files (see F<FSL_CFGDIR/fsl.*> above).
+
+=item B<OSSP pcre>, pcre(3), http://www.ossp.org/pkg/lib/pcre/
+
+The underlying library providing the matching of program identifiers on
+B<OSSP fsl> C<indent> configuration directives (see I<match> above).
+
+=item B<OpenPKG>, openpkg(7), http://www.openpkg.org/
+
+The project which prompted the development of B<OSSP fsl>
+and which is also the primary application domain of it.
+
+=back
=head1 ONLINE RESOURCES
- Project Homepage: http://www.ossp.org/pkg/lib/fsl/
- Source Repository: http://cvs.ossp.org/pkg/lib/fsl/
- Distribution Files: ftp://ftp.ossp.org/pkg/lib/fsl/
+=over 4
+
+=item http://www.ossp.org/pkg/lib/fsl/
+
+=item http://cvs.ossp.org/pkg/lib/fsl/
+
+=item ftp://ftp.ossp.org/pkg/lib/fsl/
+
+=back
=head1 HISTORY
@@ -417,9 +490,15 @@
messages of particular log levels to different files in the B<OpenPKG>
F<postfix> package.
-=head1 AUTHOR
+=head1 AUTHORS
+
+=over 4
+
+=item Thomas Lotterer <thomas@lotterer.net>
+
+=item Ralf S. Engelschall <rse@engelschall.com>
-Thomas Lotterer <thomas@lotterer.net>
+=back
=cut
|
