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', '-HUP', $pid );
                                         system(@args);
                                         }
                             );

# 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 Logfile::Base package by Ulrich Pfeifer, as the use of this module closely relates to the processing logfiles.

new

new accepts four arguments, File, Count, Gzip, Signal with only File being mandatory. new will open and lock the file, so you may coordindate the processing of the file with rotating it. The file is closed and unlocked when the object is destroyed, so you can do this explicity 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.

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 File::Copy package, but I have had a few people suggest that they would prefer File::Move. 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 gzip program or the program passed as the Gzip argument. If no argument is defined it will also check the perl Config to determine if gzip is available on your system. In this case the gzip must be in your current path to succeed, and accept the C-f option.

See the "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.

DEPENDANCIES

See File::Copy.

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-98 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

File::Copy, Logfile::Base, Changes file for change history and credits for contributions.

RETURN

All functions return 1 on success, 0 on failure.

AUTHOR

Paul Gampe <paulg@twics.com>