OSSP CVS Repository

ossp - Check-in [2389]
Not logged in
[Honeypot]  [Browse]  [Home]  [Login]  [Reports
[Search]  [Ticket]  [Timeline
  [Patchset]  [Tagging/Branching

Check-in Number: 2389
Date: 2002-Jul-27 20:13:32 (local)
2002-Jul-27 18:13:32 (UTC)
User:rse
Branch:
Comment: overhauling, cleanups and enhancements to the manual page
Tickets:
Inspections:
Files:
ossp-pkg/fsl/fsl.pod      1.12 -> 1.13     328 inserted, 249 deleted

ossp-pkg/fsl/fsl.pod 1.12 -> 1.13

--- 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
 

CVSTrac 2.0.1