.\" -*- 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 "rollrec 3"
.TH rollrec 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::rollrec \- Manipulate a DNSSEC\-Tools rollrec file.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::DNS::SEC::Tools::rollrec;
\&
\&  rollrec_lock();
\&  rollrec_read("localhost.rollrec");
\&
\&  $valid = rollrec_current();
\&  $rrinfo = rollrec_info();
\&
\&  @rrnames = rollrec_names();
\&
\&  $flag = rollrec_exists("example.com");
\&
\&  $rrec = rollrec_fullrec("example.com");
\&  %rrhash = %$rrec;
\&  $zname = $rrhash{"maxttl"};
\&
\&  $val = rollrec_recval("example.com","zonefile");
\&
\&  rollrec_add("roll","example.com",\e%rollfields);
\&  rollrec_add("skip","example.com",\e%rollfields);
\&
\&  rollrec_del("example.com");
\&
\&  rollrec_rename("example.com","subdom.example.com");
\&
\&  rollrec_type("example.com","roll");
\&  rollrec_type("example.com","skip");
\&
\&  rollrec_setval("example.com","zonefile","db.example.com");
\&
\&  rollrec_delfield("example.com","directory");
\&
\&  rollrec_settime("example.com");
\&  rollrec_settime("example.com",0);
\&
\&  @rollrecfields = rollrec_fields();
\&
\&  $default_file = rollrec_default();
\&
\&  $count = rollrec_merge("primary.rrf", "new0.rrf", "new1.rrf");
\&  @retvals = rollrec_split("new\-rollrec.rrf", @rollrec_list);
\&
\&  %zgroups = rollrec_zonegroups();
\&  @zgroup = rollrec_zonegroup($zonegroupname);
\&  @zgcmds = rollrec_zonegroup_cmds();
\&
\&  rollrec_write();
\&  rollrec_close();
\&  rollrec_discard();
\&
\&  rollrec_unlock();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBNet::DNS::SEC::Tools::rollrec\fR module manipulates the contents of a
DNSSEC-Tools \fIrollrec\fR file.  \fIrollrec\fR files describe the status of a
zone rollover process, as performed by the DNSSEC-Tools programs.  Module
interfaces exist for looking up \fIrollrec\fR records, creating new records,
and modifying existing records.
.PP
A \fIrollrec\fR file is organized in sets of \fIrollrec\fR records.  \fIrollrec\fRs
describe the state of a rollover operation.  A \fIrollrec\fR consists of a set
of keyword/value entries.  The following is an example of a \fIrollrec\fR:
.PP
.Vb 10
\&    roll "example"
\&        zonename                "example.com"
\&        zonefile                "/etc/dnssec\-tools/zones/db.example.com"
\&        keyrec                  "/etc/dnssec\-tools/keyrec/example.keyrec"
\&        zonegroup               "example zones"
\&        directory               "/etc/dnssec\-tools/dir\-example.com"
\&        kskphase                "0"
\&        zskphase                "2"
\&        maxttl                  "86400"
\&        administrator           "bob@bobhost.example.com"
\&        phasestart              "Wed Mar 09 21:49:22 2005"
\&        display                 "0"
\&        loglevel                "info"
\&        rollrec_rollsecs        "1115923362"
\&        rollrec_rolldate        "Tue Mar 09 19:12:54 2005"
\&        curerrors               0
\&        maxerrors               5
\&        # optional records:
\&        istrustanchor           "yes"
\&        holddowntime            "8W"
.Ve
.PP
Additionally, commands to be acted upon at start-up can be defined using the
"cmd" token as shown in the following example.
.PP
.Vb 1
\&    cmd "rollzsk example.com"
.Ve
.PP
Use this feature with caution and only if you understand the internals of
\&\fBrollerd\fR and \fIexactly\fR what will be done by the specified command.
.PP
The first step in using this module must be to read the \fIrollrec\fR file.  The
\&\fR\f(BIrollrec_read()\fR\fI\fR interface reads the file and parses it into an internal
format.  The file's records are copied into a hash table (for easy reference
by the \fBrollrec.pm\fR routines) and in an array (for
preserving formatting and comments.)
.PP
After the file has been read, the contents are referenced using
\&\fR\f(BIrollrec_fullrec()\fR\fI\fR and \fI\fR\f(BIrollrec_recval()\fR\fI\fR.  The \fI\fR\f(BIrollrec_add()\fR\fI\fR,
\&\fI\fR\f(BIrollrec_setval()\fR\fI\fR, and \fI\fR\f(BIrollrec_settime()\fR\fI\fR interfaces are used
to modify the contents of a \fIrollrec\fR record.
.PP
If the \fIrollrec\fR file has been modified, it must be explicitly written or
the changes will not saved.  \fR\f(BIrollrec_write()\fR\fI\fR saves the new contents to disk.
\&\fI\fR\f(BIrollrec_close()\fR\fI\fR saves the file and close the Perl file handle to the
\&\fIrollrec\fR file.  If a \fIrollrec\fR file is no longer wanted to be open, yet
the contents should not be saved, \fI\fR\f(BIrollrec_discard()\fR\fI\fR gets rid of the data
closes and the file handle \fBwithout\fR saving any modified data.
.PP
On reading a \fIrollrec\fR file, consecutive blank lines are collapsed into a
single blank line.  As \fIrollrec\fR entries are added and deleted, files merged
and files split, it is possible for blocks of consecutive blanks lines to
grow.  This blank-line collapsing will prevent these blocks from growing
excessively.
.PP
There is a special \fIrollrec\fR called the \fIinfo rollrec\fR.  It contains
information about the \fIrollrec\fR file, such as the version of \fIrollrec\fRs
stored within the file.  It is only accessible through the \fR\f(BIrollrec_info()\fR\fI\fR
interface, and the \fI\fR\f(BIrollrec_current()\fR\fI\fR interface will indicate if the file's
version number is current.
.SH "ROLLREC LOCKING"
.IX Header "ROLLREC LOCKING"
This module includes interfaces for synchronizing access to the \fIrollrec\fR
files.  This synchronization is very simple and relies upon locking and
unlocking a single lock file for all \fIrollrec\fR files.
.PP
\&\fIrollrec\fR locking is not required before using this module, but it is
recommended.  The expected use of these facilities follows:
.PP
.Vb 5
\&    rollrec_lock() || die "unable to lock rollrec file\en";
\&    rollrec_read();
\&    ... perform other rollrec operations ...
\&    rollrec_close();
\&    rollrec_unlock();
.Ve
.PP
Synchronization is performed in this manner due to the way the module's
functionality is implemented, as well as providing flexibility to users
of the module.  It also provides a clear delineation in callers' code as
to where and when \fIrollrec\fR locking is performed.
.PP
This synchronization method has the disadvantage of having a single lockfile
as a bottleneck to all \fIrollrec\fR file access.  However, it reduces complexity
in the locking interfaces and cuts back on the potential number of required
lockfiles.
.PP
Using a single synchronization file may not be practical in large
installations.  If that is found to be the case, then this will be reworked.
.SH "ROLLREC INTERFACES"
.IX Header "ROLLREC INTERFACES"
The interfaces to the \fBrollrec.pm\fR module are given below.
.IP \fIrollrec_add(rollrec_type,rollrec_name,fields)\fR 4
.IX Item "rollrec_add(rollrec_type,rollrec_name,fields)"
This routine adds a new \fIrollrec\fR to the \fIrollrec\fR file and the internal
representation of the file contents.  The \fIrollrec\fR is added to both the
\&\fR\f(CI%rollrecs\fR\fI\fR hash table and the \fI\fR\f(CI@rollreclines\fR\fI\fR array.  Entries are only
added if they are defined for \fIrollrec\fRs.
.Sp
\&\fIrollrec_type\fR is the type of the \fIrollrec\fR.  This must be either "roll"
or "skip".  \fIrollrec_name\fR is the name of the \fIrollrec\fR.  \fIfields\fR is a
reference to a hash table that contains the name/value \fIrollrec\fR fields.  The
keys of the hash table are always converted to lowercase, but the entry values
are left as given.
.Sp
Timestamp fields are added at the end of the \fIrollrec\fR.  These fields have
the key values \fIrollrec_gensecs\fR and \fIrollrec_gendate\fR.
.Sp
A blank line is added after the final line of the new \fIrollrec\fR.
The \fIrollrec\fR file is not written after \fR\f(BIrollrec_add()\fR\fI\fR, though
it is internally marked as having been modified.
.IP \fR\f(BIrollrec_close()\fR\fI\fR 4
.IX Item "rollrec_close()"
This interface saves the internal version of the \fIrollrec\fR file (opened with
\&\fR\f(BIrollrec_read()\fR\fI\fR) and closes the file handle.
.IP \fR\f(BIrollrec_current()\fR\fI\fR 4
.IX Item "rollrec_current()"
This routine returns a boolean indicating if this open rollrec is current,
as defined by the version number in the \fIinfo rollrec\fR.
Versions 0, 1, and 2 are considered to be equivalent.
.Sp
Return values are:
.Sp
.Vb 3
\&    1 rollrec is current
\&    0 rollrec is obsolete
\&    0 rollrec has an invalid version
.Ve
.Sp
The last condition shouldn't ever happen and it could be argued that a
failure value should be returned.  However, an easy two-value boolean
function was wanted, not a three-value function.
.IP \fIrollrec_del(rollrec_name)\fR 4
.IX Item "rollrec_del(rollrec_name)"
This routine deletes a \fIrollrec\fR from the set of \fIrollrec\fRs loaded into
memory by the \fBrollrec.pm\fR module.  The \fIrollrec\fR is deleted from both
the \fR\f(CI%rollrecs\fR\fI\fR hash table and the \fI\fR\f(CI@rollreclines\fR\fI\fR array.
.Sp
The \fIrollrec\fR file is not written after \fR\f(BIrollrec_del()\fR\fI\fR, though the
collection of \fIrollrec\fRs is internally marked as having been modified.
.Sp
Only the \fIrollrec\fR itself is deleted.  Any associated comments and blank
lines surrounding it are left intact.
.Sp
Return values are:
.Sp
.Vb 2
\&     0 successful rollrec deletion
\&    \-1 unknown name
.Ve
.IP \fIrollrec_delfield(rollrec_name,field)\fR 4
.IX Item "rollrec_delfield(rollrec_name,field)"
Deletes the given field from the specified \fIrollrec\fR.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%rollrecs\fR\fI\fR and in \fI\fR\f(CI@rollreclines\fR\fI\fR.
.Sp
Return values:
.Sp
.Vb 3
\&    0 \- failure (rollrec not found or rollrec does not
\&        contain the field)
\&    1 \- success
.Ve
.IP \fR\f(BIrollrec_discard()\fR\fI\fR 4
.IX Item "rollrec_discard()"
This routine removes a \fIrollrec\fR file from use by a program.  The internally
stored data are deleted and the \fIrollrec\fR file handle is closed.  However,
modified data are not saved prior to closing the file handle.  Thus, modified
and new data will be lost.
.IP \fIrollrec_exists(rollrec_name)\fR 4
.IX Item "rollrec_exists(rollrec_name)"
This routine returns a boolean flag indicating if the \fIrollrec\fR named in
\&\fIrollrec_name\fR exists.
.IP \fIrollrec_fullrec(rollrec_name)\fR 4
.IX Item "rollrec_fullrec(rollrec_name)"
\&\fR\f(BIrollrec_fullrec()\fR\fI\fR returns a reference to the \fIrollrec\fR specified in
\&\fIrollrec_name\fR.
.IP \fR\f(BIrollrec_info()\fR\fI\fR 4
.IX Item "rollrec_info()"
\&\fR\f(BIrollrec_info()\fR\fI\fR returns a reference to the \fIinfo rollrec\fR given in the
current file.  This interface is the only way for a calling program to
retrieve this information.
.IP \fR\f(BIrollrec_lock()\fR\fI\fR 4
.IX Item "rollrec_lock()"
\&\fR\f(BIrollrec_lock()\fR\fI\fR locks the \fIrollrec\fR lockfile.  An exclusive lock is
requested, so the execution will suspend until the lock is available.  If the
\&\fIrollrec\fR synchronization file does not exist, it will be created.  If the
process can't create the synchronization file, an error will be returned.
Success or failure is returned.
.IP "\fIrollrec_merge(target_rollrec_file, rollrec_file1, ... rollrec_fileN)\fR" 4
.IX Item "rollrec_merge(target_rollrec_file, rollrec_file1, ... rollrec_fileN)"
This interface merges the specified \fIrollrec\fR files.  It reads each file
and parses them into a \fIrollrec\fR hash table and a file-contents array.  The
resulting merge is written to the file named by \fItarget_rollrec_file\fR.
If another \fIrollrec\fR is already open, it is saved and closed prior to
opening the new \fIrollrec\fR.
.Sp
If \fItarget_rollrec_file\fR is an existing \fIrollrec\fR file, its contents will
be merged with the other files passed to \fR\f(BIrollrec_merge()\fR\fI\fR.  If the file
does not exist, \fI\fR\f(BIrollrec_merge()\fR\fI\fR will create it and merge the remaining
files into it.
.Sp
The \fIinfo rollrec\fR can affect how the merging will work.  If the
\&\fItarget_rollrec_file\fR is doesn't exist or is empty, then a simple \fIinfo
rollrec\fR will be added to the file.  No part of the \fIinfo rollrec\fRs will be
merged into that of the \fItarget_rollrec_file\fR.
.Sp
If the file does exist but doesn't have an \fIinfo rollrec\fR \fBrollrec\fR, then
then the source's \fIinfo rollrec\fR is copied to the target.  The
files' \fIinfo rollrec\fRs must either have the same version or the versions
must all be less than the version of the \fItarget_rollrec_file\fR.
.Sp
Upon success, \fR\f(BIrollrec_merge()\fR\fI\fR returns the number of \fIrollrec\fRs read from
the file.
.Sp
Failure return values:
.Sp
.Vb 5
\&    \-1 no rollrec files were given to rollrec_merge
\&    \-2 unable to create target rollrec file
\&    \-3 unable to read first rollrec file
\&    \-4 an error occurred while reading the rollrec names
\&    \-5 rollrec files were duplicated in the list of rollrec files
.Ve
.IP \fR\f(BIrollrec_names()\fR\fI\fR 4
.IX Item "rollrec_names()"
This routine returns a list of the \fIrollrec\fR names from the file.
The name of the \fIinfo rollrec\fR is not included in this list.
.IP \fIrollrec_read(rollrec_file)\fR 4
.IX Item "rollrec_read(rollrec_file)"
This interface reads the specified \fIrollrec\fR file and parses it into a
\&\fIrollrec\fR hash table and a file-contents array.  \fR\f(BIrollrec_read()\fR\fI\fR \fBmust\fR be
called prior to any of the other \fBrollrec.pm\fR calls.  If another \fIrollrec\fR
is already open, it is saved and closed prior to opening the new \fIrollrec\fR.
.Sp
\&\fR\f(BIrollrec_read()\fR\fI\fR attempts to open the \fIrollrec\fR file for reading and
writing.  If this fails, then it attempts to open the file for reading only.
.Sp
\&\fR\f(BIrollrec_read()\fR\fI\fR is a front-end for \fI\fR\f(BIrollrec_readfile()\fR\fI\fR.  It sets up the
module's saved data in preparation for reading a new \fIrollrec\fR file.  These
house-keeping actions are not performed by \fI\fR\f(BIrollrec_readfile()\fR\fI\fR.
.Sp
Upon success, \fR\f(BIrollrec_read()\fR\fI\fR returns the number of \fIrollrec\fRs read from
the file.
.Sp
Failure return values:
.Sp
.Vb 3
\&    \-1 specified rollrec file doesn\*(Aqt exit
\&    \-2 unable to open rollrec file
\&    \-3 duplicate rollrec names in file
.Ve
.IP \fIrollrec_readfile(rollrec_file_handle,mergeflag)\fR 4
.IX Item "rollrec_readfile(rollrec_file_handle,mergeflag)"
This interface reads the specified file handle to a \fIrollrec\fR file and
parses the file contents into a \fIrollrec\fR hash table and a file-contents
array.  The hash table and file-contents array are \fBnot\fR cleared prior
to adding data to them.
.Sp
The \fImergeflag\fR argument indicates whether the call will be merging a
\&\fIrollrec\fR file with a previously read \fIrollrec\fR or if it will be reading
a fresh \fIrollrec\fR file.
.Sp
Upon success, \fR\f(BIrollrec_read()\fR\fI\fR returns zero.
.Sp
Failure return values:
.Sp
.Vb 1
\&    \-1 duplicate rollrec names in file
.Ve
.IP \fIrollrec_rectype(rollrec_name,rectype)\fR 4
.IX Item "rollrec_rectype(rollrec_name,rectype)"
Set the type of the specified \fIrollrec\fR record.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%rollrecs\fR\fI\fR and in \fI\fR\f(CI@rollreclines\fR\fI\fR.
.Sp
\&\fIrollrec_name\fR is the name of the \fIrollrec\fR that will be modified.
\&\fIrectype\fR is the new type of the \fIrollrec\fR, which must be either "roll"
or "skip".
.Sp
Return values:
.Sp
.Vb 2
\&    0 \- failure (invalid record type or rollrec not found)
\&    1 \- success
.Ve
.IP \fIrollrec_recval(rollrec_name,rollrec_field)\fR 4
.IX Item "rollrec_recval(rollrec_name,rollrec_field)"
This routine returns the value of a specified field in a given \fIrollrec\fR.
\&\fIrollrec_name\fR is the name of the particular \fIrollrec\fR to consult.
\&\fIrollrec_field\fR is the field name within that \fIrollrec\fR.
.Sp
For example, the current \fIrollrec\fR file contains the following \fIrollrec\fR.
.Sp
.Vb 2
\&    roll        "example.com"
\&                zonefile        "db.example.com"
.Ve
.Sp
The call:
.Sp
.Vb 1
\&    rollrec_recval("example.com","zonefile")
.Ve
.Sp
will return the value "db.example.com".
.IP \fIrollrec_rename(old_rollrec_name,new_rollrec_name)\fR 4
.IX Item "rollrec_rename(old_rollrec_name,new_rollrec_name)"
This routine renames the \fIrollrec\fR named by \fIold_rollrec_name\fR to
\&\fInew_rollrec_name\fR.  The actual effect is to change the name in the \fIroll\fR
or \fIskip\fR line to \fInew_rollrec_name\fR.  The name is changed in the internal
version of the the \fIrollrec\fR file only.  The file itself is not changed, but
must be saved by calling either \fR\f(BIrollrec_write()\fR\fI\fR, \fI\fR\f(BIrollrec_save()\fR\fI\fR, or
\&\fI\fR\f(BIrollrec_saveas()\fR\fI\fR.
.Sp
\&\fIold_rollrec_name\fR must be the name of an existing \fIrollrec\fR.  Conversely,
\&\fInew_rollrec_name\fR must not name an existing \fIrollrec\fR.
.Sp
Return values:
.Sp
.Vb 6
\&     0 \- success
\&    \-1 \- old_rollrec_name was null or empty
\&    \-2 \- new_rollrec_name was null or empty
\&    \-3 \- old_rollrec_name is not an existing rollrec
\&    \-4 \- new_rollrec_name is already a rollrec
\&    \-5 \- internal error that should never happen
.Ve
.IP \fIrollrec_settime(rollrec_name,val)\fR 4
.IX Item "rollrec_settime(rollrec_name,val)"
Set the phase-start timestamp in the \fIrollrec\fR specified by \fIrollrec_name\fR
to the current time.  If the optional \fIval\fR parameter is given and it is
zero, then the phase-start timestamp is set to a null value.
.Sp
The file is \fBnot\fR written after updating the value.
.IP \fIrollrec_setval(rollrec_name,field,value)\fR 4
.IX Item "rollrec_setval(rollrec_name,field,value)"
Set the value of a name/field pair in a specified \fIrollrec\fR.  The file is
\&\fBnot\fR written after updating the value, but the internal file-modified flag
is set.  The value is saved in both \fR\f(CI%rollrecs\fR\fI\fR and in \fI\fR\f(CI@rollreclines\fR\fI\fR.
.Sp
\&\fIrollrec_name\fR is the name of the \fIrollrec\fR that will be modified.  If the
named \fIrollrec\fR does not exist, it will be created as a "roll"\-type
\&\fIrollrec\fR.
\&\fIfield\fR is the \fIrollrec\fR field which will be modified.
\&\fIvalue\fR is the new value for the field.
.IP \fIrollrec_split(new_rollrec_file,rollrec_names)\fR 4
.IX Item "rollrec_split(new_rollrec_file,rollrec_names)"
Move a set of \fIrollrec\fR entries from the current \fIrollrec\fR file to a new
file.  The moved \fIrollrec\fR entries are removed both from the current file
and from the internal module data representing that file.
.Sp
The \fInew_rollrec_file\fR parameter holds the name of the new \fIrollrec\fR file.
If this file doesn't exist, it will be created.  If it does exist, the
\&\fIrollrec\fR entries will be appended to that file.
.Sp
\&\fIrollrec_names\fR is a list of \fIrollrec\fR entries that will be moved from the
current file to the file named in \fInew_rollrec_file\fR.  If some of the given
\&\fIrollrec\fR names are invalid, the valid names will be moved to the new file
and the invalid names will be returned in a list to the caller.
.Sp
Only the \fIrollrec\fR entries themselves will be moved to the new \fIrollrec\fR
file.  Any associated comments will be left in the current \fIrollrec\fR file.
.Sp
\&\fIrollrec\fR\-splitting gets interesting with the addition of the \fIinfo
rollrec\fR.  If the \fInew_rollrec_file\fR file doesn't exist, the source
\&\fBrollrec\fR file's \fIinfo rollrec\fR is copied to the target file.  If the file
does exist but doesn't have an \fIinfo rollrec\fR, then then the source's \fIinfo
rollrec\fR is copied to the target.  If the target file exists and has an \fIinfo
rollrec\fR, then the two files must have matching version numbers.
.Sp
On success, the count of moved \fIrollrec\fR entries is returned.  Error returns
are given below.
.Sp
Failure return values:
    \-1 \- no target rollrec file given in new_rollrec_file
    \-2 \- no rollrec names given in rollrec_names
    \-3 \- none of the rollrec names given are existing rollrecs
    \-4 \- unable to open new_rollrec_file
    \-5 \- invalid rollrec names were specified in rollrec_names,
         followed by the list of bad names
    \-6 \- target's info rollrec has previous version than current
    \-7 \- target's info rollrec has (undefined) later version
         than current
    \-8 \- target's info rollrec exists without version number
.IP \fR\f(BIrollrec_unlock()\fR\fI\fR 4
.IX Item "rollrec_unlock()"
\&\fR\f(BIrollrec_unlock()\fR\fI\fR unlocks the \fIrollrec\fR synchronization file.
.IP \fR\f(BIrollrec_write()\fR\fI\fR 4
.IX Item "rollrec_write()"
This interface saves the internal version of the \fIrollrec\fR file (opened with
\&\fR\f(BIrollrec_read()\fR\fI\fR).  It does not close the file handle.  As an efficiency
measure, an internal modification flag is checked prior to writing the file.
If the program has not modified the contents of the \fIrollrec\fR file, it is not
rewritten.
.Sp
\&\fR\f(BIrollrec_write()\fR\fI\fR gets an exclusive lock on the \fIrollrec\fR file while writing.
.IP \fIrollrec_zonegroup($zonegroupname)\fR 4
.IX Item "rollrec_zonegroup($zonegroupname)"
This interface returns a list of the zones in the zonegroup (named by
\&\fR\f(CI$zonegroupname\fR\fI\fR) defined in the current \fIrollrec\fR file.  Null is returned
if there are no zones in the zonegroup.
.Sp
While this is using the term "zone", it is actually referring to the name of
the rollrec entries.  For a particular rollrec entry, the rollrec name is
usually the same as the zone name, but this is not a requirement.
.IP \fR\f(BIrollrec_zonegroup_cmds()\fR\fI\fR 4
.IX Item "rollrec_zonegroup_cmds()"
This interface returns a list of the rollctl commands whose behavior changes
when they are used with the \fI\-group\fR option.
.IP \fR\f(BIrollrec_zonegroups()\fR\fI\fR 4
.IX Item "rollrec_zonegroups()"
This interface returns a hash table of the zonegroups defined in the current
\&\fIrollrec\fR file.  The hash key is the name of the zonegroup; the hash value
is the number of zones in the zonegroup.  Null is returned if there are no
zonegroups in the \fIrollrec\fR file.
.Sp
While this is using the term "zone", it is actually referring to the name of
the rollrec entries.  For a particular rollrec entry, the rollrec name is
usually the same as the zone name, but this is not a requirement.
.SH "ROLLREC INTERNAL INTERFACES"
.IX Header "ROLLREC INTERNAL INTERFACES"
The interfaces described in this section are intended for internal use by the
\&\fBrollrec.pm\fR module.  However, there are situations where external entities
may have need of them.  Use with caution, as misuse may result in damaged or
lost \fIrollrec\fR files.
.IP \fR\f(BIrollrec_init()\fR\fI\fR 4
.IX Item "rollrec_init()"
This routine initializes the internal \fIrollrec\fR data.  Pending changes will
be lost.  An open \fIrollrec\fR file handle will remain open, though the data are
no longer held internally.  A new \fIrollrec\fR file must be read in order to use
the \fBrollrec.pm\fR interfaces again.
.IP \fR\f(BIrollrec_default()\fR\fI\fR 4
.IX Item "rollrec_default()"
This routine returns the name of the default \fIrollrec\fR file.
.SH "ROLLREC DEBUGGING INTERFACES"
.IX Header "ROLLREC DEBUGGING INTERFACES"
The following interfaces display information about the currently parsed
\&\fIrollrec\fR file.  They are intended to be used for debugging and testing, but
may be useful at other times.
.IP \fR\f(BIrollrec_dump_hash()\fR\fI\fR 4
.IX Item "rollrec_dump_hash()"
This routine prints the \fIrollrec\fR file as it is stored internally in a hash
table.  The \fIrollrec\fRs are printed in alphabetical order, with the fields
alphabetized for each \fIrollrec\fR.  New \fIrollrec\fRs and \fIrollrec\fR fields are
alphabetized along with current \fIrollrec\fRs and fields.  Comments from the
\&\fIrollrec\fR file are not included with the hash table.
.IP \fR\f(BIrollrec_dump_array()\fR\fI\fR 4
.IX Item "rollrec_dump_array()"
This routine prints the \fIrollrec\fR file as it is stored internally in an
array.  The \fIrollrec\fRs are printed in the order given in the file, with the
fields ordered in the same manner.  New \fIrollrec\fRs are appended to the end
of the array.  \fIrollrec\fR fields added to existing \fIrollrec\fRs are added at
the beginning of the \fIrollrec\fR entry.  Comments and vertical whitespace are
preserved as given in the \fIrollrec\fR file.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2006\-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"
\&\fBlsroll\|(1)\fR,
\&\fBrollchk\|(8)\fR,
\&\fBrollinit\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::keyrec\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::keyrec\|(5)\fR