NAME
    Logfile::Rotate - Perl module to rotate logfiles.

SYNOPSIS
       use Logfile::Rotate;
       my $log = new Logfile::Rotate( File   => '/var/adm/syslog/syslog.log', 
                                      Count  => 7,
                                      Gzip   => '/usr/local/bin/gzip',
                                      Signal => sub {
                                            my $pid = `cat /var/run/syslog.pid`;
                                            my @args = ('kill', '-s', 'HUP', $pid );
                                            system(@args);
                                            },
                                      Dir    => '/var/log/old'
                                    );

       # process log file 

       $log->rotate();

       or
       
       my $log = new Logfile::Rotate( File  => '/var/adm/syslog', 
                                      Gzip  => 'no' );
       
       # process log file 

       $log->rotate();
       undef $log;

DESCRIPTION
    I have used the name space of the Logfile::Base manpage package
    by *Ulrich Pfeifer*, as the use of this module closely relates
    to the processing logfiles.

    new `new' accepts five arguments, `File', `Count', `Gzip', `Signal'
        and `Dir' with only `File' being mandatory. `new' will open
        and lock the file, so you may co-ordinate the processing of
        the file with rotating it. The file is closed and unlocked
        when the object is destroyed, so you can do this explicitly
        by `undef''ing the object.

        The `Signal' argument allows you to pass a function
        reference to this method, which you may use as a callback
        for any further processing you want after the rotate is
        completed. For example, you may notify the process writing
        to the file that it has been rotated.

    rotate()
        This method will copy the file passed in `new' to a file of
        the same name, with a numeric extension and truncate the
        original file to zero length. The numeric extension will
        range from 1 up to the value specified by Count, or 7 if
        none is defined, with 1 being the most recent file. When
        Count is reached, the older file is discarded in a FIFO
        (first in, first out) fashion. If the argument `Dir' was
        given, all old files will be placed in the specified
        directory.

        The `Signal' function is the last step executed by the
        rotate method so the return code of rotate will be the
        return code of the function you proved, or 1 by default.

        The copy function is implemented by using the the File::Copy
        manpage package, but I have had a few people suggest that
        they would prefer the File::Move manpage. I'm still not
        decided on this as you would loose data if the move should
        fail.

  Optional Compression

    If available `rotate' will also compress the file with the the
    gzip manpage program or the program passed as the `Gzip'
    argument. If no argument is defined it will also check the perl
    the Config manpage to determine if gzip is available on your
    system. In this case the the gzip manpage must be in your
    current path to succeed, and accept the C-f option.

    See the the section on "WARNING" section below.

  Optional Relocation Directory

    If you specify an argument for `Dir' then the file being rotated
    will be relocated to the directory specified. Along with any
    other files that may have been rotated previously. If the
    directory name specified does not exist then it will be created
    with `0750' permissions. If you wish to have other permissions
    on the directory then I would recommend you create the directory
    before using this module.

    See the the section on "WARNING" section below.

WARNING
    A system call is made to gzip this makes this module vulnerable
    to security problems if a rogue gzip is in your path or gzip has
    been sabotaged. For this reason a STRONGLY RECOMMEND you DO NOT
    use this module while you are ROOT, or specify the `Gzip'
    argument.

    If you specify an argument for `Dir' and the directory name you
    pass does not exist, this module will create the directory with
    permissions `0750'.

DEPENDANCIES
    See the File::Copy manpage.

    If `Gzip' is being used it must create files with an extension
    of `.gz' for the file to be picked by the rotate cycle.

COPYRIGHT
    Copyright (c) 1997-99 Paul Gampe. All rights reserved. This
    program is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself.

    IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY
    PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE,
    ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE
    AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY
    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
    AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN ``AS IS''
    BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
    PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
    MODIFICATIONS.

SEE ALSO
    the File::Copy manpage, the Logfile::Base manpage, Changes file
    for change history and credits for contributions.

RETURN
    All functions return 1 on success, 0 on failure.

AUTHOR
    Paul Gampe <paulg@apnic.net>