Rotate(3pm)						User Contributed Perl Documentation					       Rotate(3pm)

NAME

       Log::Agent::Rotate - parameters for logfile rotation

SYNOPSIS

	require Log::Agent::Rotate;

	my $policy = Log::Agent::Rotate->make(
	    -backlog	 => 7,
	    -unzipped	 => 2,
	    -is_alone	 => 0,
	    -max_size	 => 100_000,
	    -max_time	 => "1w",
	    -file_perm	 => 0666
	);

DESCRIPTION

       The "Log::Agent::Rotate" class holds the parameters describing the logfile rotation policy, and is meant to be supplied to instances of
       "Log::Agent::Driver::File" via arguments in the creation routine, such as "-rotate", or by using array references as values in the
       "-channels" hashref: See complementary information in Log::Agent::Driver::File.

       As rotation cycles are performed, the current logfile is renamed, and possibly compressed, until the maximum backlog is reached, at which
       time files are deleted.	Assuming a backlog of 5 and that the latest 2 files are not compressed, the following files can be present on the
       filesystem:

	   logfile	     # the current logfile
	   logfile.0	     # most recently renamed logfile
	   logfile.1
	   logfile.2.gz
	   logfile.3.gz
	   logfile.4.gz      # oldest logfile, unlinked next cycle

       The following switches are available to the creation routine make(), listed in alphabetical order, all taking a single integer value as
       argument:

       backlog
	   The total amount of old logfiles to keep, besides the current logfile.

	   Defaults to 7.

       file_perm
	   The file permissions, given as an octal integer value, to supply to sysopen() during file creation.	This value is modified during
	   execution by the umask of the process.  In most cases, it is good practice to leave this set to the default and let the user process
	   controll the file permissions.

	   Defaults to 0666.

       is_alone
	   The argument is a boolean stating whether the program writing to the logfile will be the only one or not.  This is a hint that drives
	   some optimizations, but it is up to the program to guarantee that noone else will be able to write to or unlink the current logfile
	   when set to true.

	   Defaults to false.

       max_size
	   The maximum logfile size.  This is a threshold, which will cause a logfile rotation cycle to be performed, when crossed after a write
	   to the file.  If set to 0, this threshold is not checked.

	   Defaults to 1 megabyte.

       max_time
	   The maximum time in seconds between the moment we opened the file and the next rotation cycle occurs.  This threshold is only checked
	   after a write to the file.

	   The value can also be given as a string, postfixed by one of the following letters to specify the period unit (e.g. "3w"):

	       Letter	Unit
	       ------	-------
		  m	minutes
		  h	hours
		  d	days
		  d	days
		  w	weeks
		  M	months (30 days of 24 hours)
		  y	years

	   Defaults to 0, meaning it is not checked.

       max_write
	   The maximum amount of data we can write to the logfile.  Like "max_size", this is a threshold, which is only checked after a write to
	   the logfile.  This is not the total logfile size: if several programs write to the same logfile and "max_size" is not used, then the
	   logfiles may never be rotated at all if none of the programs write at least "max_write" bytes to the logfile before exiting.

	   Defaults to 0, meaning it is not checked.

       single_host
	   The argument is a boolean stating whether the access to the logfiles will be made from one single host or not.  This is a hint that
	   drives some optimizations, but it is up to the program to guarantee that it is accurately set.

	   Defaults to false, which is always a safe value.

       unzipped
	   The amount of old logfiles, amongst the most recent ones, that should not be compressed but be kept as plain files.

	   Defaults to 1.

       To test whether two configurations are strictly identical, use is_same(), as in:

	   print "identical
" if $x->is_same($y);

       where both $x and $y are "Log::Agent::Rotate" objects.

       All the aforementioned switches also have a corresponding querying routine that can be issued on instances of the class to get their value.
       It is not possible to modify those attributes.

       For instance:

	   my $x = Log::Agent::Rotate->make(...);
	   my $mwrite = $x->max_write();

       would get the configured max_write threshold.

AUTHORS

       Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>, currently maintained by Mark Rogaski <mrogaski@cpan.org>.

       Thanks to Chris Meshkin for his suggestions on file permissions.

SEE ALSO

       Log::Agent(3), Log::Agent::Driver::File(3), Log::Agent::Rotate::File(3).

perl v5.10.0							    2002-05-14							       Rotate(3pm)