1Fast(3) User Contributed Perl Documentation Fast(3)
2
6 Net::DNS::ZoneFile::Fast -- parse BIND8/9 zone files
7
9 use Net::DNS::ZoneFile::Fast;
10 my $rr = Net::DNS::ZoneFile::Fast::parse($zone_text);
12
14 The Net::DNS::ZoneFile::Fast module provides an ability to parse zone
15 files that BIND8 and BIND9 use, fast. Currently it provides a single
16 function, parse(), which returns a reference to an array of traditional
17 Net::DNS::RR objects, so that no new API has to be learned in order to
18 manipulate zone records.
19 Great care was taken to ensure that parse() does its job as fast as
21 possible, so it is interesting to use this module to parse huge zones.
22 As an example datapoint, it takes less than 5 seconds to parse a 2.2 MB
23 zone with about 72000 records on an Athlon XP 2600+ box.
24 On the other hand, it is likely that Net::DNS::RR objects that parse()
26 returns are going to be further processed. To make it easier to link
27 any record back to the zone file (say, to report a logical error like
28 infamous `CNAME and other data' back to the user, or to do a zone file
29 modification), parse() inserts line numbering information into
30 Net::DNS::RR objects.
31 The module currently understands:
33 $GENERATE directive
35 $ORIGIN directive
36 $TTL directive
37 $INCLUDE directive (only while processing files or filehandles)
38 A records
39 AAAA records
40 CNAME records
41 DNAME records
42 HINFO records
43 LOC records
44 MX records
45 NS records
46 PTR records
47 RP records
48 SOA records
49 SRV records
50 TXT records
51 RRSIG records
52 DNSKEY records
53 DS records
54 NSEC records
55 RRSIG records
56 Non-standard third-party modules
58 Net::DNS.
60 Exports
62 None.
64 Subroutines
66 parse
68 Parses zone data and returns a reference to an array of
69 Net::DNS::RR objects if successful. Takes the following named (no
70 pun intended) parameters:
71 text
73 A semi-mandatory parameter, textual contents of the zone to be
74 parsed.
75 fh A semi-mandatory parameter, a file handle from which zone con‐
77 tents can be read for parsing.
78 file
80 A semi-mandatory parameter, a file name with the zone to parse.
81 origin
83 An optional parameter specifying zone origin. The default is
84 ".". A trailing "." is appended if necessary.
85 on_error
87 An optional parameter, user-defined error handler. If speci‐
88 fied, it must be a subroutine reference, which will be called
89 on any error. This subroutine will be passed two parameters: a
90 line number in the zone, where the error occurred, and the
91 error description.
92 soft_errors
94 By default, parse throws an exception on any error. Set this
95 optional parameter to a true value to avoid this. The default
96 is false, unless on_error is also specified, in which case it
97 is true.
98 includes_root
100 An optional parameter. By default, any $INCLUDE directives
101 encountered will be tested for existance and readablility. If
102 the base path of the included filename is not your current
103 working directory, this test will fail. Set the includes_root
104 to the same as your named.conf file to avoid this failure.
105 quiet
107 An optional parameter. By default, on any error, the error
108 description is printed via warn(). Set quiet to a true value
109 if you don't want this. The default is false, unless on_error
110 is also specified, in which case it is true.
111 debug
113 An optional parameter. If set to true, will produce some debug
114 printing. You probably don't want to use that.
115 One of text, fh, file must be specified. If more than one is spec‐
117 ified at the same time, fh takes precedence over file, which takes
118 precedence over text.
119 As a special case, if parse is called with a single, unnamed param‐
121 eter, it is assumed to be a zone text.
122 If parse is unsuccessful, and does not throw an exception (because
124 either on_error or soft_errors was specified), parse returns undef.
125 The returned Net::DNS::RR are normal in every respect, except that
127 each of them has two extra keys, Line and Lines, which correspond‐
128 ingly are the line number in the zone text where the record starts,
129 and the number of lines the record spans. This information can be
130 accessed either via hash lookup ("$rr->{Line}"), or via an accessor
131 method ("$rr->Line").
132
134 The parse() subroutine is not re-entrant. Plobably will never be.
135 There is also no guarantee that parse() will successfully parse every
137 zone parsable by BIND, and no guarantee that BIND will parse every zone
138 parsable by parse(). That said, parse() appears to do the right thing
139 on around 50000 real life zones I tested it with.
140
142 Copyright 2003 by Anton Berezin and catpipe Systems ApS
143 "THE BEER-WARE LICENSE" (Revision 42)
145 <tobez@tobez.org> wrote this module. As long as you retain this notice
146 you can do whatever you want with this stuff. If we meet some day, and
147 you think this stuff is worth it, you can buy me a beer in return.
148 Anton Berezin
150 Copyright (c) 2004-2006, SPARTA, Inc.
152 All rights reserved.
153 Redistribution and use in source and binary forms, with or without
155 modification, are permitted provided that the following conditions are met:
156 * Redistributions of source code must retain the above copyright notice,
158 this list of conditions and the following disclaimer.
159 * Redistributions in binary form must reproduce the above copyright
161 notice, this list of conditions and the following disclaimer in the
162 documentation and/or other materials provided with the distribution.
163 * Neither the name of SPARTA, Inc nor the names of its contributors may
165 be used to endorse or promote products derived from this software
166 without specific prior written permission.
167 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
169 IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
170 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
171 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
172 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
173 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
174 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
175 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
176 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
177 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
178 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
179
181 Anton Berezin created the versions up until 0.5. Wes Hardaker at
182 Sparta implemented the DNSSEC patches and took over maintaince of the
183 module from 0.6 onward.
184 Anton's original CREDITS section:
186 This module was largely inspired by the I<Net::DNS::ZoneFile> module
188 by Luis E. Munoz.
189 Many thanks to Phil Regnauld and Luis E. Munoz for discussions.
191
193 http://www.dnssec-tools.org/, Net::DNS(3), Net::DNS::RR(3),
194 Net::DNS::SEC(3)
195perl v5.8.8 2007-10-31 Fast(3)