Provided by: libnet-dns-zonefile-fast-perl_1.24-3_all bug

NAME

       Net::DNS::ZoneFile::Fast -- parse BIND8/9 zone files

SYNOPSIS

         use Net::DNS::ZoneFile::Fast;

         my $rr = Net::DNS::ZoneFile::Fast::parse($zone_text);

DESCRIPTION

       The Net::DNS::ZoneFile::Fast module provides an ability to parse zone files that BIND8 and
       BIND9 use, fast.  Currently it provides a single function, parse(), which returns a
       reference to an array of traditional Net::DNS::RR objects, so that no new API has to be
       learned in order to manipulate zone records.

       Great care was taken to ensure that parse() 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 MB zone with about 72000 records on an Athlon XP 2600+
       box.

       On the other hand, it is likely that Net::DNS::RR objects that parse() 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 `CNAME and other data' back to the user, or to do
       a zone file modification), parse() inserts line numbering information into Net::DNS::RR
       objects.

       The module currently understands:

       $GENERATE directive
       $ORIGIN directive
       $TTL directive
       $INCLUDE directive (only while processing files or filehandles)
       A records
       AAAA records
       CNAME records
       DNAME records
       HINFO records
       LOC records
       MX records
       NS records
       PTR records
       RP records
       SOA records
       SRV records
       TXT records
       RRSIG records
       DNSKEY records
       DS records
       NSEC records
       RRSIG records

   Non-standard third-party modules
       Net::DNS.

   Exports
       None.

   Subroutines
       parse
           Parses zone data and returns a reference to an array of Net::DNS::RR objects if
           successful.  Takes the following named (no pun intended) parameters:

           text
               A semi-mandatory parameter, textual contents of the zone to be parsed.

           fh  A semi-mandatory parameter, a file handle from which zone contents can be read for
               parsing.

           file
               A semi-mandatory parameter, a file name with the zone to parse.

           origin
               An optional parameter specifying zone origin.  The default is ".".  A trailing "."
               is appended if necessary.

           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.

           soft_errors
               By default, parse throws an exception on any error.  Set this optional parameter
               to a true value to avoid this.  The default is false, unless on_error is also
               specified, in which case it is true.

           includes_root
               An optional parameter.  By default, any $INCLUDE 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 includes_root
               to the same as your named.conf file to avoid this failure.

           quiet
               An optional parameter.  By default, on any error, the error description is printed
               via warn().  Set quiet to a true value if you don't want this.  The default is
               false, unless on_error is also specified, in which case it is true.

           debug
               An optional parameter.  If set to true, will produce some debug printing.  You
               probably don't want to use that.

           One of text, fh, file must be specified.  If more than one is specified at the same
           time, fh takes precedence over file, which takes precedence over text.

           As a special case, if parse is called with a single, unnamed parameter, it is assumed
           to be a zone text.

           If parse is unsuccessful, and does not throw an exception (because either on_error or
           soft_errors was specified), parse returns undef.

           The returned Net::DNS::RR 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 ("$rr->{Line}"), or via an accessor
           method ("$rr->Line").

BUGS

       The parse() subroutine is not re-entrant, and it probably will never be.

       There is also no guarantee that parse() will successfully parse every zone parsable by
       BIND, and no guarantee that BIND will parse every zone parsable by parse().  That said,
       parse() appears to do the right thing on around 50000 real life zones I tested it with.

       SOA 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).

COPYRIGHT AND LICENSE

       Copyright 2003 by Anton Berezin and catpipe Systems ApS

         "THE BEER-WARE LICENSE" (Revision 42)
         <tobez@tobez.org> 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

       Copyright (c) 2004-2011 SPARTA, Inc.
         All rights reserved.

         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'' 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.

       Copyright (c) 2013-2013 PARSONS, Inc.
         All rights reserved.

         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'' 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.

CREDITS

       Anton Berezin created the versions up until 0.5.  Wes Hardaker at Sparta implemented the
       DNSSEC patches and took over maintenance of the module from 0.6 onward.

       Anton's original CREDITS section:

         This module was largely inspired by the I<Net::DNS::ZoneFile> module
         by Luis E. Munoz.

         Many thanks to Phil Regnauld and Luis E. Munoz for discussions.

SEE ALSO

       http://www.dnssec-tools.org/, Net::DNS(3), Net::DNS::RR(3), Net::DNS::SEC(3)