NAME

       Log::Agent::Driver::File - file logging driver for Log::Agent

SYNOPSIS

        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   => '/tmp/output.err',
               output  => 'log.out',
               debug   => '../appli.debug',
            },
            -chanperm   => {
               error   => 0777,
               output  => 0666,
               debug   => 0644
            }
        );
        logconfig(-driver => $driver);

DESCRIPTION

       The file logging driver redirects logxxx() operations to specified files, one per channel
       usually (but channels may go to the same file).

       The creation routine make() takes the following arguments:

       "-channels" => hash ref
           Specifies where channels go. The supplied hash maps channel names ("error", "output"
           and "debug") to filenames. When "-magic_open" is set to true, filenames are allowed
           magic processing via perl's open(), so this allows things like:

               -channels => {
                   'error'   => '>&FILE',
                   'output'  => '>newlog',   # recreate each time, don't append
                   'debug'  => '|mailx -s whatever user',
               }

           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 STDERR instead.

           If you have installed the additional "Log::Agent::Rotate" module, it is also possible
           to override any default rotating policy setup via the "-rotate" 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 "Log::Agent::Rotate" configuration:

               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 => {
                       'error'  => ['errors', $rotate],
                       'output' => ['output, $rotate],
                       'debug'  => ['>&FILE, $rotate],    # WRONG
                   },
                   -magic_open => 1,
                   ...
               );

           In the above example, the rotation policy for the "debug" channel will not be
           activated, since the channel is opened via a magic method.  See Log::Agent::Rotate for
           more details.

       "-chanperm" => hash ref
           Specifies the file permissions for the channels specified by "-channels".  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
           "umask" in perlfunc(3) for more details..

       "-duperr" => flag
           When true, all messages normally sent to the "error" channel are also copied to the
           "output" channel with a prefixing made to clearly mark them as such: "FATAL: " for
           logdie(), logcroak() and logconfess(), "ERROR: " for logerr() and "WARNING: " for
           logwarn().

           Note that the "duplicate" is the original error string for logconfess() and
           logcroak(), and is not strictly identical to the message that will be logged to the
           "error" channel.  This is a an accidental feature.

           Default is false.

       "-file" => file
           This switch supersedes both "-duperr" and "-channels" by defining a single file for
           all the channels.

       "-perm" => perm
           This switch supersedes "-chanperm" by defining consistent for all the channels.

       "-magic_open" => flag
           When true, channel filenames beginning with '>' or '|' are opened using Perl's open().
           Otherwise, sysopen() is used, in append mode.

           Default is false.

       "-prefix" => prefix
           The application prefix string to prepend to messages.

       "-rotate" => object
           This sets a default logfile rotation policy.  You need to install the additional
           "Log::Agent::Rotate" module to use this switch.

           object is the "Log::Agent::Rotate" instance describing the default policy for all the
           channels.  Only files which are not opened via a so-called magic open can be rotated.

       "-showpid" => flag
           If set to true, the PID of the process will be appended within square brackets after
           the prefix, to all messages.

           Default is false.

       "-stampfmt" => (name | CODE)
           Specifies the time stamp format to use. By default, my "own" format is used.  The
           following formats are available:

               date      "[Fri Oct 22 16:23:10 1999]"
               none
               own       "99/10/22 16:23:10"
               syslog    "Oct 22 16:23:10".

           You may also specify a CODE 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.

CHANNELS

       All the channels go to the specified files. If a channel is not configured, it is
       redirected to 'error', or STDERR if no 'error' channel was configured either.

       Two channels not opened via a magic open and whose logfile name is the same are
       effectively shared, 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.

CAVEAT

       Beware of chdir().  If your program uses chdir(), 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 chdir()ed to.

       Logging channels with the same pathname are shared, i.e. they are only opened once by
       "Log::Agent::Driver::File".  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:

        Rotation for 'logfile' may be wrong (shared with distinct policies)

       emitted in the logs upon subsequent sharing.

AUTHORS

       Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>, currently maintained
       by Mark Rogaski <mrogaski@cpan.org>.

       Thanks to Joseph Pepin for suggesting the file permissions arguments to make().

LICENSE

       Copyright (C) 1999 Raphael Manfredi.  Copyright (C) 2002 Mark Rogaski; all rights
       reserved.

       See Log::Agent(3) or the README file included with the distribution for license
       information.

SEE ALSO

       Log::Agent::Driver(3), Log::Agent(3), Log::Agent::Rotate(3).