NAME

       Log::Agent::File::Rotate - a rotating logfile set

SYNOPSIS

        #
        # This class is not user-visible.
        #
        # It is documented only for programmers wishing to inherit
        # from it to further extend its behaviour.
        #

        require Log::Agent::Driver::File;
        require Log::Agent::Rotate;
        require Log::Agent::File::Rotate;

        my $config = Log::Agent::Rotate->make(...);
        my $driver = Log::Agent::Driver::File->make(...);
        my $fh = Log::Agent::File::Rotate->make("file", $config, $driver);

DESCRIPTION

       This class represents a rotating logfile and is used drivers wishing to rotate their
       logfiles periodically.  From the outside, it exports a single "print" routine, just like
       "Log::Agent::File::Native".

       Internally, it uses the parameters given by a "Log::Agent::Rotate" object to transparently
       close the current logfile and cycle the older logs.

       Before rotating the current logfile, the string:

           *** LOGFILE ROTATED ON <local date>

       is emitted, so that people monitoring the file via "tail -f" know about it and are not
       surprised by the sudden stop of messages.

       Its exported interface is:

       make file, config
           This is the creation routine.  The config object is an instance of
           "Log::Agent::Rotate".

       print args
           Prints args to the file.  After having printed the data, monitor the file against the
           thresholds defined in the configuration, and possibly rotate the logfiles according to
           the parameters held in the same configuration object.

           When the "is_alone" flag is not set in the configuration, the logfile is checked
           everytime a "print" is issued to see if its inode changed.  Indeed, when several
           instances of the same program using rotating logfiles are running, each of them may
           decide to cycle the logs at some point in time, and therefore our opened handle could
           point to an already renamed or unlinked file.

AUTHORS

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

SEE ALSO

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