.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" 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 >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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Fast 3pm" .TH Fast 3pm "2018-05-18" "perl v5.26.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" Net::DNS::ZoneFile::Fast \-\- parse BIND8/9 zone files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::DNS::ZoneFile::Fast; \& \& my $rr = Net::DNS::ZoneFile::Fast::parse($zone_text); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Net::DNS::ZoneFile::Fast module provides an ability to parse zone files that \s-1BIND8\s0 and \s-1BIND9\s0 use, fast. Currently it provides a single function, \fI\fIparse()\fI\fR, which returns a reference to an array of traditional \fINet::DNS::RR\fR objects, so that no new \s-1API\s0 has to be learned in order to manipulate zone records. .PP Great care was taken to ensure that \fI\fIparse()\fI\fR does its job as fast as possible, so it is interesting to use this module to parse huge zones. As an example datapoint, it takes less than 5 seconds to parse a 2.2 \s-1MB\s0 zone with about 72000 records on an Athlon \s-1XP 2600+\s0 box. .PP On the other hand, it is likely that \fINet::DNS::RR\fR objects that \&\fI\fIparse()\fI\fR returns are going to be further processed. To make it easier to link any record back to the zone file (say, to report a logical error like infamous `\s-1CNAME\s0 and other data' back to the user, or to do a zone file modification), \fI\fIparse()\fI\fR inserts line numbering information into \&\fINet::DNS::RR\fR objects. .PP The module currently understands: .IP "\fB\f(CB$GENERATE\fB\fR directive" 4 .IX Item "$GENERATE directive" .PD 0 .IP "\fB\f(CB$ORIGIN\fB\fR directive" 4 .IX Item "$ORIGIN directive" .IP "\fB\f(CB$TTL\fB\fR directive" 4 .IX Item "$TTL directive" .IP "\fB\f(CB$INCLUDE\fB\fR directive (only while processing files or filehandles)" 4 .IX Item "$INCLUDE directive (only while processing files or filehandles)" .IP "\fBA\fR records" 4 .IX Item "A records" .IP "\fB\s-1AAAA\s0\fR records" 4 .IX Item "AAAA records" .IP "\fB\s-1CNAME\s0\fR records" 4 .IX Item "CNAME records" .IP "\fB\s-1DNAME\s0\fR records" 4 .IX Item "DNAME records" .IP "\fB\s-1HINFO\s0\fR records" 4 .IX Item "HINFO records" .IP "\fB\s-1LOC\s0\fR records" 4 .IX Item "LOC records" .IP "\fB\s-1MX\s0\fR records" 4 .IX Item "MX records" .IP "\fB\s-1NS\s0\fR records" 4 .IX Item "NS records" .IP "\fB\s-1PTR\s0\fR records" 4 .IX Item "PTR records" .IP "\fB\s-1RP\s0\fR records" 4 .IX Item "RP records" .IP "\fB\s-1SOA\s0\fR records" 4 .IX Item "SOA records" .IP "\fB\s-1SRV\s0\fR records" 4 .IX Item "SRV records" .IP "\fB\s-1TXT\s0\fR records" 4 .IX Item "TXT records" .IP "\fB\s-1RRSIG\s0\fR records" 4 .IX Item "RRSIG records" .IP "\fB\s-1DNSKEY\s0\fR records" 4 .IX Item "DNSKEY records" .IP "\fB\s-1DS\s0\fR records" 4 .IX Item "DS records" .IP "\fB\s-1NSEC\s0\fR records" 4 .IX Item "NSEC records" .IP "\fB\s-1RRSIG\s0\fR records" 4 .IX Item "RRSIG records" .PD .SS "Non-standard third-party modules" .IX Subsection "Non-standard third-party modules" \&\fINet::DNS\fR. .SS "Exports" .IX Subsection "Exports" None. .SS "Subroutines" .IX Subsection "Subroutines" .IP "\fIparse\fR" 4 .IX Item "parse" Parses zone data and returns a reference to an array of \fINet::DNS::RR\fR objects if successful. Takes the following named (no pun intended) parameters: .RS 4 .IP "\fBtext\fR" 4 .IX Item "text" A semi-mandatory parameter, textual contents of the zone to be parsed. .IP "\fBfh\fR" 4 .IX Item "fh" A semi-mandatory parameter, a file handle from which zone contents can be read for parsing. .IP "\fBfile\fR" 4 .IX Item "file" A semi-mandatory parameter, a file name with the zone to parse. .IP "\fBorigin\fR" 4 .IX Item "origin" An optional parameter specifying zone origin. The default is \*(L".\*(R". A trailing \*(L".\*(R" is appended if necessary. .IP "\fBon_error\fR" 4 .IX Item "on_error" An optional parameter, user-defined error handler. If specified, it must be a subroutine reference, which will be called on any error. This subroutine will be passed two parameters: a line number in the zone, where the error occurred, and the error description. .IP "\fBsoft_errors\fR" 4 .IX Item "soft_errors" By default, \fIparse\fR throws an exception on any error. Set this optional parameter to a true value to avoid this. The default is false, unless \fBon_error\fR is also specified, in which case it is true. .IP "\fBincludes_root\fR" 4 .IX Item "includes_root" An optional parameter. By default, any \f(CW$INCLUDE\fR directives encountered will be tested for existence and readability. If the base path of the included filename is not your current working directory, this test will fail. Set the \fBincludes_root\fR to the same as your named.conf file to avoid this failure. .IP "\fBquiet\fR" 4 .IX Item "quiet" An optional parameter. By default, on any error, the error description is printed via \fIwarn()\fR. Set \fBquiet\fR to a true value if you don't want this. The default is false, unless \fBon_error\fR is also specified, in which case it is true. .IP "\fBdebug\fR" 4 .IX Item "debug" An optional parameter. If set to true, will produce some debug printing. You probably don't want to use that. .RE .RS 4 .Sp One of \fBtext\fR, \fBfh\fR, \fBfile\fR must be specified. If more than one is specified at the same time, \fBfh\fR takes precedence over \fBfile\fR, which takes precedence over \fBtext\fR. .Sp As a special case, if \fIparse\fR is called with a single, unnamed parameter, it is assumed to be a zone text. .Sp If \fIparse\fR is unsuccessful, and does not throw an exception (because either \fBon_error\fR or \fBsoft_errors\fR was specified), \fIparse\fR returns undef. .Sp The returned \fINet::DNS::RR\fR are normal in every respect, except that each of them has two extra keys, Line and Lines, which correspondingly are the line number in the zone text where the record starts, and the number of lines the record spans. This information can be accessed either via hash lookup (\f(CW\*(C`$rr\->{Line}\*(C'\fR), or via an accessor method (\f(CW\*(C`$rr\->Line\*(C'\fR). .RE .SH "BUGS" .IX Header "BUGS" The \fI\fIparse()\fI\fR subroutine is not re-entrant, and it probably will never be. .PP There is also no guarantee that \fI\fIparse()\fI\fR will successfully parse every zone parsable by \s-1BIND,\s0 and no guarantee that \s-1BIND\s0 will parse every zone parsable by \fI\fIparse()\fI\fR. That said, \fI\fIparse()\fI\fR appears to do the right thing on around 50000 real life zones I tested it with. .PP \&\s-1SOA\s0 serial numbers with a decimal point are not supported (they're not a legal zonefile contstruct, although bind8 supported them. Even bind is dropping support for them in future releases). .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2003 by Anton Berezin and catpipe Systems ApS .PP .Vb 4 \& "THE BEER\-WARE LICENSE" (Revision 42) \& wrote this module. As long as you retain this notice \& you can do whatever you want with this stuff. If we meet some day, and \& you think this stuff is worth it, you can buy me a beer in return. \& \& Anton Berezin .Ve .PP Copyright (c) 2004\-2011 \s-1SPARTA,\s0 Inc. All rights reserved. .PP .Vb 2 \& Redistribution and use in source and binary forms, with or without \& modification, are permitted provided that the following conditions are met: \& \& * Redistributions of source code must retain the above copyright notice, \& this list of conditions and the following disclaimer. \& \& * Redistributions in binary form must reproduce the above copyright \& notice, this list of conditions and the following disclaimer in the \& documentation and/or other materials provided with the distribution. \& \& * Neither the name of SPARTA, Inc nor the names of its contributors may \& be used to endorse or promote products derived from this software \& without specific prior written permission. \& \& THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \`\`AS \& IS\*(Aq\*(Aq AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, \& THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR \& PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR \& CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, \& EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, \& PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; \& OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, \& WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR \& OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF \& ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .Ve .PP Copyright (c) 2013\-2013 \s-1PARSONS,\s0 Inc. All rights reserved. .PP .Vb 2 \& Redistribution and use in source and binary forms, with or without \& modification, are permitted provided that the following conditions are met: \& \& * Redistributions of source code must retain the above copyright notice, \& this list of conditions and the following disclaimer. \& \& * Redistributions in binary form must reproduce the above copyright \& notice, this list of conditions and the following disclaimer in the \& documentation and/or other materials provided with the distribution. \& \& * Neither the name of SPARTA, Inc nor the names of its contributors may \& be used to endorse or promote products derived from this software \& without specific prior written permission. \& \& THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \`\`AS \& IS\*(Aq\*(Aq AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, \& THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR \& PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR \& CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, \& EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, \& PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; \& OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, \& WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR \& OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF \& ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .Ve .SH "CREDITS" .IX Header "CREDITS" Anton Berezin created the versions up until 0.5. Wes Hardaker at Sparta implemented the \s-1DNSSEC\s0 patches and took over maintenance of the module from 0.6 onward. .PP Anton's original \s-1CREDITS\s0 section: .PP .Vb 2 \& This module was largely inspired by the I module \& by Luis E. Munoz. \& \& Many thanks to Phil Regnauld and Luis E. Munoz for discussions. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" http://www.dnssec\-tools.org/, \fINet::DNS\fR\|(3), \fINet::DNS::RR\fR\|(3), \fINet::DNS::SEC\fR\|(3)