Appender::File(User Contributed Perl DocumentatAppender::File(3p)


NAME
       Log::Log4perl::Appender::File - Log to file

SYNOPSIS
           use Log::Log4perl::Appender::File;

           my $app = Log::Log4perl::Appender::File->new(
             filename  => 'file.log',
             mode      => 'append',
             autoflush => 1,
             umask     => 0222,
           );

           $file->log(message => "Log me\n");

DESCRIPTION
       This is a simple appender for writing to a file.

       The "log()" method takes a single scalar. If a newline character should
       terminate the message, it has to be added explicitely.

       Upon destruction of the object, the filehandle to access the file is
       flushed and closed.

       If you want to switch over to a different logfile, use the
       "file_switch($newfile)" method which will first close the old file
       handle and then open a one to the new file specified.

   OPTIONS
       filename
           Name of the log file.

       mode
           Messages will be append to the file if $mode is set to the string
           "append". Will clobber the file if set to "clobber". If it is
           "pipe", the file will be understood as executable to pipe output
           to. Default mode is "append".

       autoflush
           "autoflush", if set to a true value, triggers flushing the data out
           to the file on every call to "log()". "autoflush" is on by default.

       syswrite
           "syswrite", if set to a true value, makes sure that the appender
           uses syswrite() instead of print() to log the message. "syswrite()"
           usually maps to the operating system's "write()" function and makes
           sure that no other process writes to the same log file while
           "write()" is busy.  Might safe you from having to use other
           syncronisation measures like semaphores (see: Synchronized
           appender).

       umask
           Specifies the "umask" to use when creating the file, determining
           the file's permission settings.  If set to 0222 (default), new



perl v5.12.2                2009-05-02                          1





Appender::File(User Contributed Perl DocumentatAppender::File(3p)


           files will be created with "rw-r--r--" permissions.  If set to
           0000, new files will be created with "rw-rw-rw-" permissions.

       owner
           If set, specifies that the owner of the newly created log file
           should be different from the effective user id of the running
           process.  Only makes sense if the process is running as root.  Both
           numerical user ids and user names are acceptable.

       group
           If set, specifies that the group of the newly created log file
           should be different from the effective group id of the running
           process.  Only makes sense if the process is running as root.  Both
           numerical group ids and group names are acceptable.

       utf8
           If you're printing out Unicode strings, the output filehandle needs
           to be set into ":utf8" mode:

               my $app = Log::Log4perl::Appender::File->new(
                 filename  => 'file.log',
                 mode      => 'append',
                 utf8      => 1,
               );

       binmode
           To manipulate the output filehandle via "binmode()", use the
           binmode parameter:

               my $app = Log::Log4perl::Appender::File->new(
                 filename  => 'file.log',
                 mode      => 'append',
                 binmode   => ":utf8",
               );

           A setting of ":utf8" for "binmode" is equivalent to specifying the
           "utf8" option (see above).

       recreate
           Normally, if a file appender logs to a file and the file gets moved
           to a different location (e.g. via "mv"), the appender's open file
           handle will automatically follow the file to the new location.

           This may be undesirable. When using an external logfile rotator,
           for example, the appender should create a new file under the old
           name and start logging into it. If the "recreate" option is set to
           a true value, "Log::Log4perl::Appender::File" will do exactly that.
           It defaults to false. Check the "recreate_check_interval" option
           for performance optimizations with this feature.

       recreate_check_interval
           In "recreate" mode, the appender has to continuously check if the
           file it is logging to is still in the same location. This check is
           fairly expensive, since it has to call "stat" on the file name and



perl v5.12.2                2009-05-02                          2





Appender::File(User Contributed Perl DocumentatAppender::File(3p)


           figure out if its inode has changed. Doing this with every call to
           "log" can be prohibitively expensive. Setting it to a positive
           integer value N will only check the file every N seconds. It
           defaults to 30.

           This obviously means that the appender will continue writing to a
           moved file until the next check occurs, in the worst case this will
           happen "recreate_check_interval" seconds after the file has been
           moved or deleted. If this is undesirable, setting
           "recreate_check_interval" to 0 will have the appender check the
           file with every call to "log()".

       recreate_check_signal
           In "recreate" mode, if this option is set to a signal name (e.g.
           "USR1"), the appender will recreate a missing logfile when it
           receives the signal. It uses less resources than constant polling.
           The usual limitation with perl's signal handling apply.  Check the
           FAQ for using this option with the log rotating utility
           "newsyslog".

       recreate_pid_write
           The popular log rotating utility "newsyslog" expects a pid file in
           order to send the application a signal when its logs have been
           rotated. This option expects a path to a file where the pid of the
           currently running application gets written to.  Check the FAQ for
           using this option with the log rotating utility "newsyslog".

       create_at_logtime
           The file appender typically creates its logfile in its constructor,
           i.e.  at Log4perl "init()" time. This is desirable for most use
           cases, because it makes sure that file permission problems get
           detected right away, and not after days/weeks/months of operation
           when the appender suddenly needs to log something and fails because
           of a problem that was obvious at startup.

           However, there are rare use cases where the file shouldn't be
           created at Log4perl "init()" time, e.g. if the appender can't be
           used by the current user although it is defined in the
           configuration file. If you set "create_at_logtime" to a true value,
           the file appender will try to create the file at log time. Note
           that this setting lets permission problems sit undetected until log
           time, which might be undesirable.

       header_text
           If you want Log4perl to print a header into every newly opened (or
           re-opened) logfile, set "header_text" to either a string or a
           subroutine returning a string. If the message doesn't have a
           newline, a newline at the end of the header will be provided.

       Design and implementation of this module has been greatly inspired by
       Dave Rolsky's "Log::Dispatch" appender framework.

AUTHOR
       Mike Schilli <log4perlATperlmeister.com>, 2003, 2005



perl v5.12.2                2009-05-02                          3