.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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::File 3pm"
.TH Agent::Driver::File 3pm "2022-10-15" "perl v5.34.0" "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::File \- file logging driver for Log::Agent
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Log::Agent;
\& require Log::Agent::Driver::File;
\&
\& my $driver = Log::Agent::Driver::File\->make(
\&     \-prefix     => "prefix",
\&     \-duperr     => 1,
\&     \-stampfmt   => "own",
\&     \-showpid    => 1,
\&     \-magic_open => 0,
\&     \-channels   => {
\&        error   => \*(Aq/tmp/output.err\*(Aq,
\&        output  => \*(Aqlog.out\*(Aq,
\&        debug   => \*(Aq../appli.debug\*(Aq,
\&     },
\&     \-chanperm   => {
\&        error   => 0777,
\&        output  => 0666,
\&        debug   => 0644
\&     }
\& );
\& logconfig(\-driver => $driver);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The file logging driver redirects \fBlogxxx()\fR operations to specified files,
one per channel usually (but channels may go to the same file).
.PP
The creation routine \fBmake()\fR takes the following arguments:
.ie n .IP """\-channels"" => \fIhash ref\fR" 4
.el .IP "\f(CW\-channels\fR => \fIhash ref\fR" 4
.IX Item "-channels => hash ref"
Specifies where channels go. The supplied hash maps channel names
(\f(CW\*(C`error\*(C'\fR, \f(CW\*(C`output\*(C'\fR and \f(CW\*(C`debug\*(C'\fR) to filenames. When \f(CW\*(C`\-magic_open\*(C'\fR is
set to true, filenames are allowed magic processing via perl's \fBopen()\fR, so
this allows things like:
.Sp
.Vb 5
\&    \-channels => {
\&        \*(Aqerror\*(Aq   => \*(Aq>&FILE\*(Aq,
\&        \*(Aqoutput\*(Aq  => \*(Aq>newlog\*(Aq,   # recreate each time, don\*(Aqt append
\&        \*(Aqdebug\*(Aq  => \*(Aq|mailx \-s whatever user\*(Aq,
\&    }
.Ve
.Sp
If a channel (e.g. 'output') is not specified, it will go to the 'error'
channel, and if that one is not specified either, it will go to \s-1STDERR\s0 instead.
.Sp
If you have installed the additional \f(CW\*(C`Log::Agent::Rotate\*(C'\fR module, it is
also possible to override any default rotating policy setup via the \f(CW\*(C`\-rotate\*(C'\fR
argument: instead of supplying the channel as a single string, use an array
reference where the first item is the channel file, and the second one is
the \f(CW\*(C`Log::Agent::Rotate\*(C'\fR configuration:
.Sp
.Vb 6
\&    my $rotate = Log::Agent::Rotate\->make(
\&        \-backlog     => 7,
\&        \-unzipped    => 2,
\&        \-max_write   => 100_000,
\&        \-is_alone    => 1,
\&    );
\&
\&    my $driver = Log::Agent::Driver::File\->make(
\&        ...
\&        \-channels => {
\&            \*(Aqerror\*(Aq  => [\*(Aqerrors\*(Aq, $rotate],
\&            \*(Aqoutput\*(Aq => [\*(Aqoutput, $rotate],
\&            \*(Aqdebug\*(Aq  => [\*(Aq>&FILE, $rotate],    # WRONG
\&        },
\&        \-magic_open => 1,
\&        ...
\&    );
.Ve
.Sp
In the above example, the rotation policy for the \f(CW\*(C`debug\*(C'\fR channel will
not be activated, since the channel is opened via a \fImagic\fR method.
See Log::Agent::Rotate for more details.
.ie n .IP """\-chanperm"" => \fIhash ref\fR" 4
.el .IP "\f(CW\-chanperm\fR => \fIhash ref\fR" 4
.IX Item "-chanperm => hash ref"
Specifies the file permissions for the channels specified by \f(CW\*(C`\-channels\*(C'\fR.
The arguemtn is a hash ref, indexed by channel name, with numeric values.
This option is only necessary to override the default permissions used by
Log::Agent::Channel::File.  It is generally better to leave these
permissive and rely on the user's umask.
See \*(L"umask\*(R" in \fBperlfunc\fR\|(3) for more details..
.ie n .IP """\-duperr"" => \fIflag\fR" 4
.el .IP "\f(CW\-duperr\fR => \fIflag\fR" 4
.IX Item "-duperr => flag"
When true, all messages normally sent to the \f(CW\*(C`error\*(C'\fR channel are also
copied to the \f(CW\*(C`output\*(C'\fR channel with a prefixing made to clearly mark
them as such: \*(L"\s-1FATAL: \*(R"\s0 for \fBlogdie()\fR, \fBlogcroak()\fR and \fBlogconfess()\fR,
\&\*(L"\s-1ERROR: \*(R"\s0 for \fBlogerr()\fR and \*(L"\s-1WARNING: \*(R"\s0 for \fBlogwarn()\fR.
.Sp
Note that the \*(L"duplicate\*(R" is the original error string for \fBlogconfess()\fR
and \fBlogcroak()\fR, and is not strictly identical to the message that will be
logged to the \f(CW\*(C`error\*(C'\fR channel.  This is a an accidental feature.
.Sp
Default is false.
.ie n .IP """\-file"" => \fIfile\fR" 4
.el .IP "\f(CW\-file\fR => \fIfile\fR" 4
.IX Item "-file => file"
This switch supersedes both \f(CW\*(C`\-duperr\*(C'\fR and \f(CW\*(C`\-channels\*(C'\fR by defining a
single file for all the channels.
.ie n .IP """\-perm"" => \fIperm\fR" 4
.el .IP "\f(CW\-perm\fR => \fIperm\fR" 4
.IX Item "-perm => perm"
This switch supersedes \f(CW\*(C`\-chanperm\*(C'\fR by defining consistent for all
the channels.
.ie n .IP """\-magic_open"" => \fIflag\fR" 4
.el .IP "\f(CW\-magic_open\fR => \fIflag\fR" 4
.IX Item "-magic_open => flag"
When true, channel filenames beginning with '>' or '|' are opened using
Perl's \fBopen()\fR. Otherwise, \fBsysopen()\fR is used, in append mode.
.Sp
Default is false.
.ie n .IP """\-prefix"" => \fIprefix\fR" 4
.el .IP "\f(CW\-prefix\fR => \fIprefix\fR" 4
.IX Item "-prefix => prefix"
The application prefix string to prepend to messages.
.ie n .IP """\-rotate"" => \fIobject\fR" 4
.el .IP "\f(CW\-rotate\fR => \fIobject\fR" 4
.IX Item "-rotate => object"
This sets a default logfile rotation policy.  You need to install the
additional \f(CW\*(C`Log::Agent::Rotate\*(C'\fR module to use this switch.
.Sp
\&\fIobject\fR is the \f(CW\*(C`Log::Agent::Rotate\*(C'\fR instance describing the default
policy for all the channels.  Only files which are not opened via a
so-called \fImagic open\fR can be rotated.
.ie n .IP """\-showpid"" => \fIflag\fR" 4
.el .IP "\f(CW\-showpid\fR => \fIflag\fR" 4
.IX Item "-showpid => flag"
If set to true, the \s-1PID\s0 of the process will be appended within square
brackets after the prefix, to all messages.
.Sp
Default is false.
.ie n .IP """\-stampfmt"" => (\fIname\fR | \fI\s-1CODE\s0\fR)" 4
.el .IP "\f(CW\-stampfmt\fR => (\fIname\fR | \fI\s-1CODE\s0\fR)" 4
.IX Item "-stampfmt => (name | CODE)"
Specifies the time stamp format to use. By default, my \*(L"own\*(R" format is used.
The following formats are available:
.Sp
.Vb 4
\&    date      "[Fri Oct 22 16:23:10 1999]"
\&    none
\&    own       "99/10/22 16:23:10"
\&    syslog    "Oct 22 16:23:10".
.Ve
.Sp
You may also specify a \s-1CODE\s0 ref: that routine will be called every time
we need to compute a time stamp. It should not expect any parameter, and
should return a string.
.SH "CHANNELS"
.IX Header "CHANNELS"
All the channels go to the specified files. If a channel is not configured,
it is redirected to 'error', or \s-1STDERR\s0 if no 'error' channel was configured
either.
.PP
Two channels not opened via a \fImagic\fR open and whose logfile name is the
same are effectively \fIshared\fR, i.e. the same file descriptor is used for
both of them. If you supply distinct rotation policies (e.g. by having a
default policy, and supplying another policy to one of the channel only),
then the final rotation policy will depend on which one was opened first.
So don't do that.
.SH "CAVEAT"
.IX Header "CAVEAT"
Beware of \fBchdir()\fR.  If your program uses \fBchdir()\fR, you should always specify
logfiles by using absolute paths, otherwise you run the risk of having
your relative paths become invalid: there is no anchoring done at the time
you specify them.  This is especially true when configured for rotation,
since the logfiles are recreated as needed and you might end up with many
logfiles scattered throughout all the directories you \fBchdir()\fRed to.
.PP
Logging channels with the same pathname are shared, i.e. they are only
opened once by \f(CW\*(C`Log::Agent::Driver::File\*(C'\fR.  Therefore, if you specify
different rotation policy to such channels, the channel opening order will
determine which of the policies will be used for all such shared channels.
Such errors are flagged at runtime with the following message:
.PP
.Vb 1
\& Rotation for \*(Aqlogfile\*(Aq may be wrong (shared with distinct policies)
.Ve
.PP
emitted in the logs upon subsequent sharing.
.SH "AUTHORS"
.IX Header "AUTHORS"
Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
currently maintained by Mark Rogaski <mrogaski@cpan.org>.
.PP
Thanks to Joseph Pepin for suggesting the file permissions arguments
to \fBmake()\fR.
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) 1999 Raphael Manfredi.
Copyright (C) 2002 Mark Rogaski; all rights reserved.
.PP
See \fBLog::Agent\fR\|(3) or the \s-1README\s0 file included with the distribution for
license information.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBLog::Agent::Driver\fR\|(3), \fBLog::Agent\fR\|(3), \fBLog::Agent::Rotate\fR\|(3).