Logfile::Rotate (3pm)

   use Logfile::Rotate;
   my $log = new Logfile::Rotate( File   => '/var/adm/syslog/syslog.log',
                                  Count  => 7,
                                  Gzip  => 'lib',
                                  Post   => sub{
                                    open(IN, "/var/run/syslog.pid");
                                    kill("HUP", chomp(<IN>)); }
                                  Dir    => '/var/log/old',
                                  Flock  => 'yes',
                                  Persist => 'yes',
                                );

# process log file

$log->rotate();

or

my $log = new Logfile::Rotate( File => '/var/adm/syslog', Gzip => '/usr/local/bin/gzip');

# process log file

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

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

\*(C`new\*(C' accepts the following arguments, \*(C`File\*(C', \*(C`Count\*(C', \*(C`Gzip\*(C', \*(C`Pre\*(C', \*(C`Post\*(C', \*(C`Flock\*(C' and \*(C`Dir\*(C' with only \*(C`File\*(C' being mandatory. \*(C`new\*(C' 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 \*(C`undef\*(C''ing the object. The \*(C`Pre\*(C'/\*(C`Post\*(C' arguments allow you to pass function references to this method, which you may use as a callback for any processing you want before or after the rotation. For example, you may notify the process writing to the file that it has been rotated. The \*(C`Pre\*(C' function is passed the current filename to be rotated as an argument and the \*(C`Post\*(C' function is passed the current filename that was rotated and that file's new filename including any extension added by compression previously. Both the \*(C`Pre\*(C' and \*(C`Post\*(C' function references you provide are executed within an \*(C`eval\*(C' statement inside the \*(C`rotate\*(C' method. If the \*(C`eval\*(C' returns an error then the \*(C`rotate\*(C' method will croak at that point. The \*(C`Signal\*(C' argument is deprecated by the \*(C`Post\*(C' argument. The \*(C`Flock\*(C' argument allows you to specify whether the perl function \*(C`flock\*(C' is used to lock the file during the rotation operation. Apparently flock causes problems on some platforms and this option has been added to allow you to control the programs behaviour. By default the file will be locked using \*(C`flock\*(C'. The \*(C`Persist\*(C' argument allows you to control whether the program will try and set the current log file ownership and permissions on any new files that may be created by the rotation. In some circumstances the program doing the file rotation may not have sufficient permission to \*(C`chown\*(C' on the file. By default the program will try and preserve ownership and permissions.

rotate()

This method will copy the file passed in \*(C`new\*(C' 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 \s-1FIFO\s0 (first in, first out) fashion. If the argument \*(C`Dir\*(C' was given, all old files will be placed in the specified directory. The \*(C`Post\*(C' 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.

\$1

If available \*(C`rotate\*(C' will also compress the file with the gzip program or the program passed as the \*(C`Gzip\*(C' argument.

You may now also use \*(C`lib\*(C' as a value for the \*(C`Gzip\*(C' argument. This directs the program to load the \*(C`Compress::Zlib\*(C' module, if available and use it do the compression within perl. This avoids the security issues associated with spawning external programs and is the recommended value for this option.

If no argument is defined it will first check to see if the \*(C`Compress::Zlib\*(C' module can be loaded then 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\*(C' option.

See the \*(L"\s-1WARNING\s0\*(R" section below. If you specify an argument for \*(C`Dir\*(C' 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 \*(L"\s-1WARNING\s0\*(R" section below.

If 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 \s-1STRONGLY\s0 \s-1RECOMMEND\s0 you \s-1DO\s0 \s-1NOT\s0 use this module while you are \s-1ROOT\s0.

For a more secure alternative install the \*(C`Compress::Zlib\*(C' module and use the lib value for the \*(C`Gzip\*(C' argument.

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

See File::Copy.

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

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.

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

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

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

All functions return 1 on success, 0 on failure.

Paul Gampe <[email protected]>