##
##  L2 - OSSP Logging Library
##  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2001 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.pod: Unix manual page for C API
##

=pod

=head1 NAME

B<L2> - Logging Library

=head1 VERSION

L2 L2_VERSION_STR

=head1 SYNOPSIS

...

=head1 DESCRIPTION

The B<L2> library is...

=head1 FUNCTIONS

The following functions are provided by the B<L2> API:

=head1 AVAILABLE CHANNEL HANDLERS

=head2 Syslog Output Channel Handler (l2_handler_syslog)

The Syslog output channel handler C<l2_handler_syslog> sends the
incoming message either via syslog(3) to a local syslogd(8) or via BSD
Syslog protocol to a remote Syslog service. It conforms to RFC 3164 (The
BSD syslog Protocol; C. Lonvick; August 2001).

It provides the following channel parameters:

=over 4

=item B<target> (optional, C<char *>)

Sets the location of the target Syslog service. Possible values
are C<local> (the default) or C<remote>. If C<remote> is used, the
parameters C<remotehost> has to be set, too.

=item B<remotehost> (optional, C<char *>)

Host name or IP address of the remote Syslog service.
No default exists, user has to provide value.

=item B<remoteport> (optional, C<int>)     

Port number of the remote SMTP service.
Default is C<514>.

=item B<localhost> (optional, C<char *>)     

The name of the local host, I<without> any domain appended.

=item B<facility> (optional, C<char *>)     

The Syslog facility used for all messages. It has to be one of the
following: C<kern>, C<user>, C<mail>, C<daemon>, C<auth>, C<syslog>,
C<lpr>, C<news>, C<uucp>, C<cron>, C<authpriv>, C<ftp>, C<ntp>,
C<security>, C<console>, C<clock>, C<local0>, C<local1>, C<local2>,
C<local3>, C<local4>, C<local5>, C<local6>, C<local7>.

=item B<ident> (I<mandatory>, C<char *>)     

Arbitrary string identifying the program.
There is no default, user has to provide value.

=item B<logpid> (optional, C<int>)     

Boolean flag whether to add the Process ID (pid)
to the B<ident> tag in messages. Default is C<0>.

=back

=head2 SMTP Output Channel Handler (l2_handler_smtp)

The SMTP output channel handler C<l2_handler_smtp> sends the incoming
message via Simple Mail Transfer Protocol (SMTP) as an Email to a remote
mail service. It conforms to RFC 2821 (Simple Mail Transfer Protocol; J.
Klensin; April 2001) and RFC 2822 (Internet Message Format; P. Resnick;
April 2001).

It provides the following channel parameters:

=over 4

=item B<progname> (optional, C<char *>)

Arbitrary string identifying the program using B<OSSP L2>.
Default is C<NULL> which means no program identification.

=item B<localhost> (optional, C<char *>)

Hostname of the underlying machine.
Default is set through uname(3) or C<localhost>.

=item B<localuser> (optional, C<char *>)

Username corresponding to the UID of the underlying process.
Default is set through resolving getuid(2) or C<uid#N>.

=item B<from> (optional, C<char *>)

Sender Email address for outgoing mails.
Default is set through B<localuser> and B<localhost>.

=item B<rcpt> (I<mandatory>, C<char *>)

Recipient Email address for outgoing mails.
No default exists, user has to provide value.

=item B<subject> (optional, C<char *>)

Arbitrary string identifying the generated Email message.
Default is C<[L2] log channel output on {localhost}>.

=item B<host> (I<mandatory>, C<char *>)

Host name or IP address of the remote SMTP service.
No default exists, user has to provide value.

=item B<port> (optional, C<char *>)     

Port name or number of the remote SMTP service.
Default is C<smtp> (25).

=item B<timeout> (optional, C<int>)

Timeout in seconds for all I/O operations.
Default is C<30>.

=back

=cut