.\" 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::Channel 3pm"
.TH Agent::Channel 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::Channel \- ancestor class for all Log::Agent channels
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& @Log::Agent::Channel::XXX::ISA = qw(Log::Agent::Channel);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Log::Agent::Channel\*(C'\fR class is the root class from which all
\&\f(CW\*(C`Log::Agent\*(C'\fR channels 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
Internally, the various \f(CW\*(C`Log::Agent::Driver\*(C'\fR objects create
\&\f(CW\*(C`Log::Agent::Channel\*(C'\fR instances for each logging channel defined at
driver creation time.  The channels are therefore architecturally hidden
within \f(CW\*(C`Log::Agent\*(C'\fR, since this module only provides redefined mappings
for the various \fIlogxxx()\fR routines (\fIlogerr()\fR, \fIlogwarn()\fR, \fIlogdie()\fR, etc...).
.PP
However, this does not mean that channel classes cannot be used externally:
the \f(CW\*(C`Log::Agent::Logger\*(C'\fR extension makes \f(CW\*(C`Log::Agent::Channel\*(C'\fR objects
architecturally visible, thereby offering an application-level logging \s-1API\s0
that can be redirected to various places transparently for the application.
.SH "CHANNEL LIST"
.IX Header "CHANNEL LIST"
The following channels are currently made available by \f(CW\*(C`Log::Agent\*(C'\fR.  More
channels can be defined by the \f(CW\*(C`Log::Agent::Logger\*(C'\fR extension:
.IP "Log::Agent::Channel::File" 4
.IX Item "Log::Agent::Channel::File"
This channel writes logs to files, defined by their path or via a magical
opening sequence such as \*(L"|cmd\*(R".  See Log::Agent::Channel::File.
.IP "Log::Agent::Channel::Handle" 4
.IX Item "Log::Agent::Channel::Handle"
This channel writes logs to an already opened descriptor, as specified by its
file handle: an IO::Handle object, or a \s-1GLOB\s0 reference such as \e*FILE.
See Log::Agent::Channel::Handle.
.IP "Log::Agent::Channel::Syslog" 4
.IX Item "Log::Agent::Channel::Syslog"
This channel redirects logs to the \fIsyslogd\fR\|(8) daemon, which will then handle
the dispatching to various logfiles, based on its own configuration.
See Log::Agent::Channel::Syslog.
.SH "INTERFACE"
.IX Header "INTERFACE"
You need not read this section if you're only \fBusing\fR \f(CW\*(C`Log::Agent\*(C'\fR.
However, if you wish to \fBimplement\fR another channel, then this section
might be of interest.
.PP
The following routines are \fBdeferred\fR and therefore need to be defined
by the heir:
.ie n .IP "write($priority, $logstring)" 4
.el .IP "write($priority, \f(CW$logstring\fR)" 4
.IX Item "write($priority, $logstring)"
Emit the log entry held in \f(CW$logstring\fR, at priority \f(CW$priority\fR.
A trailing \*(L"\en\*(R" is added to the \f(CW$logstring\fR, if needed (i.e. if the physical
entity does not do it already, like syslog does).
.Sp
The \f(CW$priority\fR argument must be a valid syslog priority, i.e. one of the
following strings: \*(L"emerg\*(R", \*(L"alert\*(R", \*(L"crit\*(R", \*(L"err\*(R", \*(L"warning\*(R", \*(L"notice\*(R",
\&\*(L"info\*(R", \*(L"debug\*(R".
.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 "close" 4
.IX Item "close"
Close the channel.
.IP "make" 4
.IX Item "make"
This is the creation routine. Its signature varies for each channel, naturally.
.SH "AUTHOR"
.IX Header "AUTHOR"
Raphael Manfredi \fI<Raphael_Manfredi@pobox.com>\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILog::Agent::Channel::File\fR\|(3), \fILog::Agent::Channel::Handle\fR\|(3),
\&\fILog::Agent::Channel::Syslog\fR\|(3), \fILog::Agent::Logger\fR\|(3).