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  => '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;

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 the following arguments, "File", "Count", "Gzip", "Pre", "Post", "Flock" 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 "Pre"/"Post" 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 "Pre" function is passed the current filename to  be  rotated  as  an  argument  and  the  "Post"
           function  is  passed the current filename that was rotated and that file's new filename including any
           extension added by compression previously.

           Both the "Pre" and "Post" function references you provide are executed  within  an  "eval"  statement
           inside  the  "rotate"  method.  If the "eval" returns an error then the "rotate" method will croak at
           that point.

           The "Signal" argument is deprecated by the "Post" argument.

           The "Flock" argument allows you to specify whether the perl function "flock" 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 "flock".

           The "Persist" 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  "chown"  on
           the file.  By default the program will try and preserve ownership and permissions.

       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  "Post" 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.

       You  may  now  also  use  "lib" as a value for the "Gzip" argument.  This directs the program to load the
       "Compress::Zlib" 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 "Compress::Zlib" 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 "-f" option.

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

WARNING

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

       For a more secure alternative install the "Compress::Zlib" module and use the lib value  for  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 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-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

       File::Copy, Logfile::Base, flock 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>

perl v5.36.0                                       2022-10-13                                        Rotate(3pm)