.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Log::Agent::Rotate 3pm"
.TH Log::Agent::Rotate 3pm "2015-12-08" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Agent::Rotate \- parameters for logfile rotation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Log::Agent::Rotate\*(C'\fR class holds the parameters describing the logfile
rotation policy, and is meant to be supplied to instances of
\&\f(CW\*(C`Log::Agent::Driver::File\*(C'\fR via arguments in the creation routine,
such as \f(CW\*(C`\-rotate\*(C'\fR, or by using array references as values in the
\&\f(CW\*(C`\-channels\*(C'\fR hashref: See complementary information in
Log::Agent::Driver::File.
.PP
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:
.PP
.Vb 6
\&    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
.Ve
.PP
The following \fIswitches\fR are available to the creation routine \fImake()\fR,
listed in alphabetical order, all taking a single integer value as argument:
.IP "\fIbacklog\fR" 4
.IX Item "backlog"
The total amount of old logfiles to keep, besides the current logfile.
.Sp
Defaults to 7.
.IP "\fIfile_perm\fR" 4
.IX Item "file_perm"
The file permissions, given as an octal integer value, to supply to
\&\fIsysopen()\fR 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.
.Sp
This option has no effect on Win32 systems.
.Sp
Defaults to 0666.
.IP "\fIis_alone\fR" 4
.IX Item "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 \fBguarantee\fR that noone else will be able to
write to or unlink the current logfile when set to \fItrue\fR.
.Sp
Defaults to \fIfalse\fR.
.IP "\fImax_size\fR" 4
.IX Item "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 \f(CW0\fR, this threshold is not checked.
.Sp
Defaults to 1 megabyte.
.IP "\fImax_time\fR" 4
.IX Item "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.
.Sp
The value can also be given as a string, postfixed by one of the
following letters to specify the period unit (e.g. \*(L"3w\*(R"):
.Sp
.Vb 9
\&    Letter   Unit
\&    \-\-\-\-\-\-   \-\-\-\-\-\-\-
\&       m     minutes
\&       h     hours
\&       d     days
\&       d     days
\&       w     weeks
\&       M     months (30 days of 24 hours)
\&       y     years
.Ve
.Sp
Defaults to \f(CW0\fR, meaning it is not checked.
.IP "\fImax_write\fR" 4
.IX Item "max_write"
The maximum amount of data we can write to the logfile.  Like \f(CW\*(C`max_size\*(C'\fR,
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 \f(CW\*(C`max_size\*(C'\fR is not used, then the logfiles may never be rotated
at all if none of the programs write at least \f(CW\*(C`max_write\*(C'\fR bytes to the
logfile before exiting.
.Sp
Defaults to \f(CW0\fR, meaning it is not checked.
.IP "\fIsingle_host\fR" 4
.IX Item "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 \fBguarantee\fR that it is
accurately set.
.Sp
Defaults to \fIfalse\fR, which is always a safe value.
.IP "\fIunzipped\fR" 4
.IX Item "unzipped"
The amount of old logfiles, amongst the most recent ones, that should
not be compressed but be kept as plain files.
.Sp
Defaults to 1.
.PP
To test whether two configurations are strictly identical, use \fIis_same()\fR,
as in:
.PP
.Vb 1
\&    print "identical\en" if $x\->is_same($y);
.Ve
.PP
where both \f(CW$x\fR and \f(CW$y\fR are \f(CW\*(C`Log::Agent::Rotate\*(C'\fR objects.
.PP
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.
.PP
For instance:
.PP
.Vb 2
\&    my $x = Log::Agent::Rotate\->make(...);
\&    my $mwrite = $x\->max_write();
.Ve
.PP
would get the configured \fImax_write\fR threshold.
.SH "AUTHORS"
.IX Header "AUTHORS"
Originally written by Raphael Manfredi (Raphael_Manfredi@pobox.com),
currently maintained by Mark Rogaski (mrogaski@cpan.org).
.PP
Thanks to Chris Meshkin for his suggestions on file permissions.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000, Raphael Manfredi.
.PP
Copyright (c) 2002\-2015, Mark Rogaski; all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the Artistic License 2.0, a copy of which can
be found with perl.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the
Artistic License 2.0 for more details.
.PP
http://www.perlfoundation.org/artistic_license_2_0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILog::Agent\fR\|(3), \fILog::Agent::Driver::File\fR\|(3),
\&\fILog::Agent::Rotate::File\fR\|(3).