.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Agent::Driver 3pm"
.TH Agent::Driver 3pm "2016-09-17" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Agent::Driver \- ancestor class for all Log::Agent drivers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& @Log::Agent::Driver::XXX::ISA = qw(Log::Agent::Driver);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Log::Agent::Driver class is the root class from which all Log::Agent
drivers inherit. It is a \fIdeferred\fR class, meaning that it cannot
be instantiated directly. All the deferred routines need to be implemented
by its heirs to form a valid driver.
.PP
A \fIdeferred\fR routine is a routine whose signature and semantics (pre and
post conditions, formally) are specified, but not implemented. It allows
specification of high-level processings in terms of them, thereby factorizing
common code in the ancestors without loosing specialization benefits.
.SH "DRIVER LIST"
.IX Header "DRIVER LIST"
The following drivers are currently fully implemented:
.IP "Log::Agent::Driver::Default" 4
.IX Item "Log::Agent::Driver::Default"
This is the default driver which remaps to simple \fIprint()\fR, \fIwarn()\fR and \fIdie()\fR
Perl calls.
.IP "Log::Agent::Driver::File" 4
.IX Item "Log::Agent::Driver::File"
This driver redirects logs to files. Each logging channel may go to a dedicated
file.
.IP "Log::Agent::Driver::Silent" 4
.IX Item "Log::Agent::Driver::Silent"
Silence all the \fIlogxxx()\fR routines.
.IP "Log::Agent::Driver::Syslog" 4
.IX Item "Log::Agent::Driver::Syslog"
This driver redirects logs to the \fIsyslogd\fR\|(8) daemon, which will then handle
the dispatching to various logfiles, based on its own configuration.
.SH "INTERFACE"
.IX Header "INTERFACE"
You need not read this section if you're only \fBusing\fR Log::Agent.  However,
if you wish to \fBimplement\fR another driver, then you should probably read it
a few times.
.PP
The following routines are \fBdeferred\fR and therefore need to be defined
by the heir:
.ie n .IP "channel_eq($chan1, $chan2)" 4
.el .IP "channel_eq($chan1, \f(CW$chan2\fR)" 4
.IX Item "channel_eq($chan1, $chan2)"
Returns true when both channels \f(CW$chan1\fR and \f(CW$chan2\fR send their output to
the same place.  The purpose is not to have a 100% accurate comparison,
which is almost impossible for the Log::Agent::Driver::File driver,
but to reasonably detect similarities to avoid duplicating messages to
the same output when Carp::Datum is installed and activated.
.ie n .IP "write($channel, $priority, $logstring)" 4
.el .IP "write($channel, \f(CW$priority\fR, \f(CW$logstring\fR)" 4
.IX Item "write($channel, $priority, $logstring)"
Emit the log entry held in \f(CW$logstring\fR, at priority \f(CW$priority\fR and through
the specfied \f(CW$channel\fR name. A trailing \*(L"\en\*(R" is to be added if needed, but the
\&\f(CW$logstring\fR should not already have one.
.Sp
The \f(CW$channel\fR name is just a string, and it is up to the driver to map that
name to an output device using its own configuration information. The generic
\&\fIlogxxx()\fR routines use only \f(CW\*(C`error\*(C'\fR, \f(CW\*(C`output\*(C'\fR or \f(CW\*(C`debug\*(C'\fR for channel names.
.Sp
The \f(CW$priority\fR entry is assumed to have passed through the \fImap_pri()\fR routine,
which by default returns an empty string (only the Log::Agent::Driver::Syslog
driver needs a priority, for now). Ignore if you don't need that, or redefine
\&\fImap_pri()\fR.
.Sp
The \f(CW$logstring\fR may not really be a plain string. It can actually be a
Log::Agent::Message object with an overloaded stringification routine, so
the illusion should be complete.
.IP "make" 4
.IX Item "make"
This is the creation routine. Its signature varies for each driver, naturally.
.IP "prefix_msg($str)" 4
.IX Item "prefix_msg($str)"
Prefix the log message string (a Log::Agent::Message object) with
driver-specific information (like the configured prefix, the \s-1PID\s0 of the
process, etc...).
.Sp
Must return the prefixed string, either as a Log::Agent::Message object
or as a plain string. This means you may use normal string operations on the
\&\f(CW$str\fR variable and let the overloaded stringification perform its magic. Or
you may return the \f(CW$str\fR parameter without modification.
.Sp
There is no default implementation here because this is too driver-specific
to choose one good default. And I like making things explicit sometimes.
.PP
The following routines are implemented in terms of \fIwrite()\fR, \fImap_pri()\fR
and \fIprefix_msg()\fR. The default implementation may need to be redefined for
performance or tuning reasons, but simply defining the deferred routines
above should bring a reasonable behaviour.
.PP
As an example, here is the default \fIlogsay()\fR implementation, which uses
the \fIemit()\fR wrapper (see below):
.PP
.Vb 5
\&    sub logsay {
\&        my $self = shift;
\&        my ($str) = @_;
\&        $self\->emit(\*(Aqoutput\*(Aq, \*(Aqnotice\*(Aq, $str);
\&    }
.Ve
.PP
Yes, we do show the gory details in a manpage, but inheriting from a class
is not for the faint of heart, and requires getting acquainted with the
implementation, most of the time.
.PP
The order is not alphabetical here but by increased level of severity
(as expected, anyway):
.ie n .IP "logwrite($channel, $priority, $level, $str)" 4
.el .IP "logwrite($channel, \f(CW$priority\fR, \f(CW$level\fR, \f(CW$str\fR)" 4
.IX Item "logwrite($channel, $priority, $level, $str)"
Log message to the given channel, at the specified priority/level,
obtained through a call to \fImap_pri()\fR.
.IP "logsay($str)" 4
.IX Item "logsay($str)"
Log message to the \f(CW\*(C`output\*(C'\fR channel, at the \f(CW\*(C`notice\*(C'\fR priority.
.IP "logwarn($str)" 4
.IX Item "logwarn($str)"
Log warning to the \f(CW\*(C`error\*(C'\fR channel at the \f(CW\*(C`warning\*(C'\fR priority.
.ie n .IP "logxcarp($offset, $str)" 4
.el .IP "logxcarp($offset, \f(CW$str\fR)" 4
.IX Item "logxcarp($offset, $str)"
Log warning to the \f(CW\*(C`error\*(C'\fR channel at the \f(CW\*(C`warning\*(C'\fR priority, from
the perspective of the caller.  An additional \f(CW$offset\fR stack frames
are skipped to find the caller (added to the hardwired fixed offset imposed
by the overall Log::Agent architecture).
.IP "logerr($str)" 4
.IX Item "logerr($str)"
Log error to the \f(CW\*(C`error\*(C'\fR channel at the \f(CW\*(C`error\*(C'\fR priority.
.IP "logdie($str)" 4
.IX Item "logdie($str)"
Log fatal error to the \f(CW\*(C`error\*(C'\fR channel at the \f(CW\*(C`critical\*(C'\fR priority
and then call \fIdie()\fR with \*(L"$str\en\*(R" as argument.
.ie n .IP "logxcroak($offset, $str)" 4
.el .IP "logxcroak($offset, \f(CW$str\fR)" 4
.IX Item "logxcroak($offset, $str)"
Log a fatal error, from the perspective of the caller. The error is logged
to the \f(CW\*(C`error\*(C'\fR channel at the \f(CW\*(C`critical\*(C'\fR priority and then \fICarp::croak()\fR
is called with \*(L"$str\en\*(R" as argument.  An additional \f(CW$offset\fR stack frames
are skipped to find the caller (added to the hardwired fixed offset imposed
by the overall Log::Agent architecture).
.IP "logconfess($str)" 4
.IX Item "logconfess($str)"
Confess a fatal error. The error is logged to the \f(CW\*(C`error\*(C'\fR channel at
the \f(CW\*(C`critical\*(C'\fR priority and then \fICarp::confess()\fR is called with \*(L"$str\en\*(R"
as argument.
.PP
The following routines have a default implementation but may be redefined
for specific drivers:
.ie n .IP "emit($channel, $prio, $str)" 4
.el .IP "emit($channel, \f(CW$prio\fR, \f(CW$str\fR)" 4
.IX Item "emit($channel, $prio, $str)"
This is a convenient wrapper that calls:
.Sp
.Vb 1
\& write($channel, $self\->priority($prio), $self\->prefix_msg($str))
.Ve
.Sp
using dynamic binding.
.ie n .IP "map_pri($priority, $level)" 4
.el .IP "map_pri($priority, \f(CW$level\fR)" 4
.IX Item "map_pri($priority, $level)"
Converts a (\*(L"priority\*(R", level) tupple to a single priority token suitable
for \fIemit()\fR. By default, returns an empty string, which is \s-1OK\s0 only when
\&\fIemit()\fR does not care!
.PP
The following routine is \fBfrozen\fR. There is no way in Perl to freeze a routine,
i.e. to explicitly forbid any redefinition, so this is an informal
notification:
.IP "priority($priority)" 4
.IX Item "priority($priority)"
This routine returns the proper priority for \fIemit()\fR for each of the
following strings: \*(L"critical\*(R", \*(L"error\*(R", \*(L"warning\*(R" and \*(L"notice\*(R", which are
the hardwired priority strings, as documented above.
.Sp
It derives a logging level from the \f(CW$priority\fR given and then returns the
result of:
.Sp
.Vb 1
\&    map_pri($priority, $level);
.Ve
.Sp
Therefore, only \fImap_pri()\fR should be redefined.
.PP
Finally, the following initialization routine is provided: to record the
.ie n .IP "_init($prefix, $penalty)" 4
.el .IP "_init($prefix, \f(CW$penalty\fR)" 4
.IX Item "_init($prefix, $penalty)"
Records the \f(CW\*(C`prefix\*(C'\fR attribute, as well as the Carp \f(CW\*(C`penalty\*(C'\fR (amount
of extra stack frames to skip). Should be called in the constructor of
all the drivers.
.SH "AUTHORS"
.IX Header "AUTHORS"
Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
currently maintained by Mark Rogaski <mrogaski@cpan.org>.
.SH "LICENSE"
.IX Header "LICENSE"
.Vb 2
\&  Copyright (C) 1999 Raphael Manfredi.
\&  Copyright (C) 2002 Mark Rogaski; all rights reserved.
.Ve
.PP
See \fILog::Agent\fR\|(3) or the \s-1README\s0 file included with the distribution for
license information.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILog::Agent\fR\|(3), \fILog::Agent::Driver::Default\fR\|(3), \fILog::Agent::Driver::File\fR\|(3),
\&\fILog::Agent::Driver::Fork\fR\|(3), \fILog::Agent::Driver::Silent\fR\|(3),
\&\fILog::Agent::Driver::Syslog\fR\|(3), \fICarp::Datum\fR\|(3).