.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "rolllog 3"
.TH rolllog 3 2023-07-29 "perl v5.38.0" "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
Net::DNS::SEC::Tools::rolllog \- DNSSEC\-Tools rollover logging interfaces.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::DNS::SEC::Tools::rolllog;
\&
\&  @levels = rolllog_levels();
\&
\&  $curlevel = rolllog_level();
\&  $oldlevel = rolllog_level("info");
\&  $oldlevel = rolllog_level(LOG_ERR,1);
\&
\&  $curlogfile = rolllog_file();
\&  $oldlogfile = rolllog_file("\-");
\&  $oldlogfile = rolllog_file("/var/log/roll.log",1);
\&
\&  $loglevelstr = rolllog_str(8)
\&  $loglevelstr = rolllog_str("info")
\&
\&  $ret = rolllog_num("info");
\&
\&  $bool = rolllog_validlevel($newlevel);
\&  $bool = rolllog_validlevel(8);
\&
\&  $curtz = rolllog_gettz();
\&  $oldtz = rolllog_settz(\*(Aqlocal\*(Aq);
\&
\&  rolllog_log(LOG_INFO,"example.com","zone is valid");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBNet::DNS::SEC::Tools::rolllog\fR module provides logging interfaces for
the rollover programs.  The logging interfaces allow log messages to be
recorded.  \fBrollerd\fR must be running, as it is responsible for updating  
the log file.
.PP
Each log message is assigned a particular logging level.  The valid logging
levels are:
.PP
.Vb 11
\&    text       numeric  meaning
\&    \-\-\-\-       \-\-\-\-\-\-\-  \-\-\-\-\-\-\-
\&    tmi           1     The highest level \-\- all log messages
\&                        are saved.
\&    expire        3     A verbose countdown of zone expiration
\&                        is given.
\&    info          4     Many informational messages are recorded.
\&    phase         6     Each zone\*(Aqs current rollover phase
\&                        is given.
\&    err           8     Errors are recorded.
\&    fatal         9     Fatal errors are saved.
.Ve
.PP
The levels include all numerically higher levels.  For example, if the log
level is set to \fBphase\fR, then \fBerr\fR and \fBfatal\fR messages will also be
recorded.
.SH "LOGGING INTERFACES"
.IX Header "LOGGING INTERFACES"
.IP \fIrolllog_file(newfile,useflag)\fR 4
.IX Item "rolllog_file(newfile,useflag)"
This routine sets and retrieves the log file for \fBrollerd\fR.
The \fInewfile\fR argument specifies the new log file to be set.  If \fInewfile\fR
exists, it must be a regular file.
.Sp
The \fIuseflag\fR argument is a boolean that indicates whether or not to give a
descriptive message if an invalid log file is given.  If \fIuseflag\fR is
true, the message is given and the process exits; if false, no message is
given.  For any error condition, an empty string is returned.
.IP \fR\f(BIrolllog_gettz()\fR\fI\fR 4
.IX Item "rolllog_gettz()"
This routine returns the timezone selector currently in use.  This value may
be either 'gmt' (for Greenwich Mean Time) or 'local' (for the host's local
time.)
.IP \fIrolllog_level(newlevel,useflag)\fR 4
.IX Item "rolllog_level(newlevel,useflag)"
This routine sets and retrieves the logging level for \fBrollerd\fR.
The \fInewlevel\fR argument specifies the new logging level to be set.
\&\fInewlevel\fR may be given in either text or numeric form.
.Sp
The \fIuseflag\fR argument is a boolean that indicates whether or not to give a
descriptive message and exit if an invalid logging level is given.  If
\&\fIuseflag\fR is true, the message is given and the process exits; if false, \-1
is returned.
.Sp
If given with no arguments, the current logging level is returned.  In fact,
the current level is always returned unless an error is found.  \-1 is returned
on error.
.IP \fR\f(BIrolllog_levels()\fR\fI\fR 4
.IX Item "rolllog_levels()"
This routine returns an array holding the text forms of the user-settable
logging levels.  The levels are returned in order, from most verbose to least.
.IP \fIrolllog_log(level,group,message)\fR 4
.IX Item "rolllog_log(level,group,message)"
The \fR\f(BIrolllog_log()\fR\fI\fR interface writes a message to the log file.  Log
messages have this format:
.Sp
.Vb 1
\&        timestamp: group: message
.Ve
.Sp
The \fIlevel\fR argument is the message's logging level.  It will only be written
to the log file if the current log level is numerically equal to or less than
\&\fIlevel\fR.
.Sp
\&\fIgroup\fR allows messages to be associated together.  It is currently used by
\&\fBrollerd\fR to group messages by the zone to which the message applies.
.Sp
The \fImessage\fR argument is the log message itself.  Trailing newlines are
removed.
.IP \fIrolllog_num(loglevel)\fR 4
.IX Item "rolllog_num(loglevel)"
This routine translates a text log level (given in \fIloglevel\fR) into the
associated numeric log level.  The numeric log level is returned to the caller.
.Sp
If \fIloglevel\fR is an invalid log level, \-1 is returned.
.IP \fIrolllog_settz(tzsel)\fR 4
.IX Item "rolllog_settz(tzsel)"
This routine sets the timezone to be used for timestamps in messages written
to the log.  This \fItzsel\fR value may be either 'gmt' (Greenwich Mean Time)
or 'local' (for the host's local time.)  \fItzsel\fR may be uppercase or
lowercase; the value will be converted to lowercase.  If no value is passed,
then the default will be used.
.Sp
The current timezone selector is returned.  If an invalid selector is given,
then an undefined value is returned.
.IP \fIrolllog_str(loglevel)\fR 4
.IX Item "rolllog_str(loglevel)"
This routine translates a log level (given in \fIloglevel\fR) into the associated
text log level.  The text log level is returned to the caller.
.Sp
If \fIloglevel\fR is a text string, it is checked to ensure it is a valid log
level.  Case is irrelevant when checking \fIloglevel\fR.
.Sp
If \fIloglevel\fR is numeric, it is must be in the valid range of log levels.
\&\fIundef\fR is returned if \fIloglevel\fR is invalid.
.IP \fIrolllog_validlevel(level)\fR 4
.IX Item "rolllog_validlevel(level)"
This interface returns a boolean value indicating if the given logging level
is valid.
.Sp
The \fIlevel\fR argument is the logging level to be validated.  It may be a
numeric or textual value.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2005\-2014 SPARTA, Inc.  All rights reserved.
See the COPYING file included with the DNSSEC-Tools package for details.
.SH AUTHOR
.IX Header "AUTHOR"
Wayne Morrison, tewok@tislabs.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBrollctl\|(1)\fR
.PP
\&\fBrollerd\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::rollmgr.pm\|(3)\fR