Net::DNS::RR(3pm)

1Net::DNS::RR(3)       User Contributed Perl Documentation      Net::DNS::RR(3)
2
3
4

NAME

6       Net::DNS::RR - DNS resource record base class
7

SYNOPSIS

9           use Net::DNS;
10
11           $rr = Net::DNS::RR->new('example.com IN AAAA 2001:DB8::1');
12
13           $rr = Net::DNS::RR->new(
14                   owner   => 'example.com',
15                   type    => 'AAAA',
16                   address => '2001:DB8::1'
17                   );
18

DESCRIPTION

20       Net::DNS::RR is the base class for DNS Resource Record (RR) objects.
21       See also the manual pages for each specific RR type.
22

METHODS

24       WARNING!!!  Do not assume the RR objects you receive from a query are
25       of a particular type.  You must always check the object type before
26       calling any of its methods.  If you call an unknown method, you will
27       get an error message and execution will be terminated.
28
29   new (from string)
30           $aaaa  = Net::DNS::RR->new('host.example.com. 86400 AAAA 2001:DB8::1');
31           $mx    = Net::DNS::RR->new('example.com. 7200 MX 10 mailhost.example.com.');
32           $cname = Net::DNS::RR->new('www.example.com 300 IN CNAME host.example.com');
33           $txt   = Net::DNS::RR->new('txt.example.com 3600 HS TXT "text data"');
34
35       Returns an object of the appropriate RR type, or a Net::DNS::RR object
36       if the type is not implemented. The attribute values are extracted from
37       the string passed by the user. The syntax of the argument string
38       follows the RFC1035 specification for zone files, and is compatible
39       with the result returned by the string method.
40
41       The owner and RR type are required; all other information is optional.
42       Omitting the optional fields is useful for creating the empty RDATA
43       sections required for certain dynamic update operations.  See the
44       Net::DNS::Update manual page for additional examples.
45
46       All names are interpreted as fully qualified domain names.  The
47       trailing dot (.) is optional.
48
49   new (from hash)
50           $rr = Net::DNS::RR->new(%hash);
51
52           $rr = Net::DNS::RR->new(
53                   owner   => 'host.example.com',
54                   ttl     => 86400,
55                   class   => 'IN',
56                   type    => 'AAAA',
57                   address => '2001:DB8::1'
58                   );
59
60           $rr = Net::DNS::RR->new(
61                   owner   => 'txt.example.com',
62                   type    => 'TXT',
63                   txtdata => [ 'one', 'two' ]
64                   );
65
66       Returns an object of the appropriate RR type, or a Net::DNS::RR object
67       if the type is not implemented. Consult the relevant manual pages for
68       the usage of type specific attributes.
69
70       The owner and RR type are required; all other information is optional.
71       Omitting optional attributes is useful for creating the empty RDATA
72       sections required for certain dynamic update operations.
73
74   decode
75           ( $rr, $next ) = Net::DNS::RR->decode( \$data, $offset, @opaque );
76
77       Decodes a DNS resource record at the specified location within a DNS
78       packet.
79
80       The argument list consists of a reference to the buffer containing the
81       packet data and offset indicating where resource record begins.  Any
82       remaining arguments are passed as opaque data to subordinate decoders
83       and do not form part of the published interface.
84
85       Returns a "Net::DNS::RR" object and the offset of the next record in
86       the packet.
87
88       An exception is raised if the data buffer contains insufficient or
89       corrupt data.
90
91   encode
92           $data = $rr->encode( $offset, @opaque );
93
94       Returns the "Net::DNS::RR" in binary format suitable for inclusion in a
95       DNS packet buffer.
96
97       The offset indicates the intended location within the packet data where
98       the "Net::DNS::RR" is to be stored.
99
100       Any remaining arguments are opaque data which are passed intact to
101       subordinate encoders.
102
103   canonical
104           $data = $rr->canonical;
105
106       Returns the "Net::DNS::RR" in canonical binary format suitable for
107       DNSSEC signature validation.
108
109       The absence of the associative array argument signals to subordinate
110       encoders that the canonical uncompressed lower case form of embedded
111       domain names is to be used.
112
113   print
114           $rr->print;
115
116       Prints the resource record to the currently selected output filehandle.
117       Calls the string method to get the formatted RR representation.
118
119   string
120           print $rr->string, "\n";
121
122       Returns a string representation of the RR using the master file format
123       mandated by RFC1035.  All domain names are fully qualified with
124       trailing dot.  This differs from RR attribute methods, which omit the
125       trailing dot.
126
127   plain
128           $plain = $rr->plain;
129
130       Returns a simplified single-line representation of the RR.  This
131       facilitates interaction with programs like nsupdate which have
132       rudimentary parsers.
133
134   token
135           @token = $rr->token;
136
137       Returns a token list representation of the RR zone file string.
138
139   generic
140           $generic = $rr->generic;
141
142       Returns the generic RR representation defined in RFC3597. This
143       facilitates creation of zone files containing RRs unrecognised by
144       outdated nameservers and provisioning software.
145
146   owner name
147           $name = $rr->owner;
148
149       Returns the owner name of the record.
150
151   type
152           $type = $rr->type;
153
154       Returns the record type.
155
156   class
157           $class = $rr->class;
158
159       Resource record class.
160
161   ttl
162           $ttl = $rr->ttl;
163           $ttl = $rr->ttl(3600);
164
165       Resource record time to live in seconds.
166
167   rdata
168           $rr = Net::DNS::RR->new( type => NULL, rdata => 'arbitrary' );
169
170       Resource record data section when viewed as opaque octets.
171
172   rdstring
173           $rdstring = $rr->rdstring;
174
175       Returns a string representation of the RR-specific data.
176
177   rdlength
178           $rdlength = $rr->rdlength;
179
180       Returns the uncompressed length of the encoded RR-specific data.
181

Sorting of RR arrays

183       Sorting of RR arrays is done by Net::DNS::rrsort(), see documentation
184       for Net::DNS. This package provides class methods to set the comparator
185       function used for a particular RR based on its attributes.
186
187   set_rrsort_func
188           my $function = sub {        ## numerically ascending order
189               $Net::DNS::a->{'preference'} <=> $Net::DNS::b->{'preference'};
190           };
191
192           Net::DNS::RR::MX->set_rrsort_func( 'preference', $function );
193
194           Net::DNS::RR::MX->set_rrsort_func( 'default_sort', $function );
195
196       set_rrsort_func() must be called as a class method. The first argument
197       is the attribute name on which the sorting is to take place. If you
198       specify "default_sort" then that is the sort algorithm that will be
199       used when get_rrsort_func() is called without an RR attribute as
200       argument.
201
202       The second argument is a reference to a comparator function that uses
203       the global variables $a and $b in the Net::DNS package. During sorting,
204       the variables $a and $b will contain references to objects of the class
205       whose set_rrsort_func() was called. The above sorting function will
206       only be applied to Net::DNS::RR::MX objects.
207
208       The above example is the sorting function implemented in MX.
209
210   get_rrsort_func
211           $function = Net::DNS::RR::MX->get_rrsort_func('preference');
212           $function = Net::DNS::RR::MX->get_rrsort_func();
213
214       get_rrsort_func() returns a reference to the comparator function.
215

COPYRIGHT

217       Copyright (c)1997-2001 Michael Fuhr.
218
219       Portions Copyright (c)2002,2003 Chris Reinhardt.
220
221       Portions Copyright (c)2005-2007 Olaf Kolkman.
222
223       Portions Copyright (c)2007,2012 Dick Franks.
224
225       All rights reserved.
226

LICENSE

228       Permission to use, copy, modify, and distribute this software and its
229       documentation for any purpose and without fee is hereby granted,
230       provided that the original copyright notices appear in all copies and
231       that both copyright notice and this permission notice appear in
232       supporting documentation, and that the name of the author not be used
233       in advertising or publicity pertaining to distribution of the software
234       without specific prior written permission.
235
236       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
237       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
238       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
239       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
240       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
241       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
242       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
243