view release on metacpan or  search on metacpan

Rotate.pm  view on Meta::CPAN

within an C<eval> statement inside the C<rotate> method.  If the C<eval>
returns an error then the C<rotate> method will croak at that point.

The C<Signal> argument is deprecated by the C<Post> argument.

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

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

=item rotate()

This method will copy the file passed in C<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 C<Dir> was given, 
all old files will be placed in the specified directory.

The C<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 L<File::Copy> package, but
I have had a few people suggest that they would prefer L<File::Move>.
I'm still not decided on this as you would loose data if the move should
fail.  

=back 

=head2 Optional Compression

If available C<rotate> will also compress the file with the 
L<gzip> program or the program passed as the C<Gzip> argument.  

You may now also use C<lib> as a value for the C<Gzip> argument.  This
directs the program to load the C<Compress::Zlib> module, if available
and use it do the compression within perl.  B<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> module can be loaded then check the perl L<Config> to
determine if gzip is available on your system. In this case the L<gzip>
must be in your current path to succeed, and accept the C<-f> option.  

See the L<"WARNING"> section below.

=head2 Optional Relocation Directory

If you specify an argument for C<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 C<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<"WARNING"> section below.

=head1 WARNING

If a system call is made to F<gzip> this makes this module vulnerable to
security problems if a rogue gzip is in your path or F<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 C<Compress::Zlib> module and
use the B<lib> value for the C<Gzip> argument.

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

=head1 DEPENDANCIES

See L<File::Copy>.

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

=head1 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. 

=head1 SEE ALSO

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

=head1 RETURN

All functions return 1 on success, 0 on failure.

=head1 AUTHOR

Paul Gampe <paulg@apnic.net>