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 = new Net::DNS::RR('example.com IN AAAA 2001:DB8::1');
12
13           $rr = new Net::DNS::RR(
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  = new Net::DNS::RR('host.example.com. 86400 AAAA 2001:DB8::1');
31           $mx    = new Net::DNS::RR('example.com. 7200 MX 10 mailhost.example.com.');
32           $cname = new Net::DNS::RR('www.example.com 300 IN CNAME host.example.com');
33           $txt   = new Net::DNS::RR('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 = new Net::DNS::RR(%hash);
51
52           $rr = new Net::DNS::RR(
53                   owner   => 'host.example.com',
54                   ttl     => 86400,
55                   class   => 'IN',
56                   type    => 'AAAA',
57                   address => '2001:DB8::1'
58                   );
59
60           $rr = new Net::DNS::RR(
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 ) = decode Net::DNS::RR( \$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.
82       Remaining arguments, if any, are passed as opaque data to subordinate
83       decoders.
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       Any remaining arguments are passed as opaque data to subordinate
92       decoders and do not form part of the published interface.
93
94   encode
95           $data = $rr->encode( $offset, @opaque );
96
97       Returns the "Net::DNS::RR" in binary format suitable for inclusion in a
98       DNS packet buffer.
99
100       The offset indicates the intended location within the packet data where
101       the "Net::DNS::RR" is to be stored.
102
103       Any remaining arguments are opaque data which are passed intact to
104       subordinate encoders.
105
106   canonical
107           $data = $rr->canonical;
108
109       Returns the "Net::DNS::RR" in canonical binary format suitable for
110       DNSSEC signature validation.
111
112       The absence of the associative array argument signals to subordinate
113       encoders that the canonical uncompressed lower case form of embedded
114       domain names is to be used.
115
116   print
117           $rr->print;
118
119       Prints the resource record to the currently selected output filehandle.
120       Calls the string method to get the formatted RR representation.
121
122   string
123           print $rr->string, "\n";
124
125       Returns a string representation of the RR using the master file format
126       mandated by RFC1035.  All domain names are fully qualified with
127       trailing dot.  This differs from RR attribute methods, which omit the
128       trailing dot.
129
130   plain
131           $plain = $rr->plain;
132
133       Returns a simplified single-line representation of the RR.  This
134       facilitates interaction with programs like nsupdate which have
135       rudimentary parsers.
136
137   token
138           @token = $rr->token;
139
140       Returns a token list representation of the RR zone file string.
141
142   generic
143           $generic = $rr->generic;
144
145       Returns the generic RR representation defined in RFC3597. This
146       facilitates creation of zone files containing RRs unrecognised by
147       outdated nameservers and provisioning software.
148
149   owner name
150           $name = $rr->owner;
151
152       Returns the owner name of the record.
153
154   type
155           $type = $rr->type;
156
157       Returns the record type.
158
159   class
160           $class = $rr->class;
161
162       Resource record class.
163
164   ttl
165           $ttl = $rr->ttl;
166           $ttl = $rr->ttl(3600);
167
168       Resource record time to live in seconds.
169
170   rdata
171           $rr = new Net::DNS::RR( type => NULL, rdata => 'arbitrary' );
172
173       Resource record data section when viewed as opaque octets.
174
175   rdstring
176           $rdstring = $rr->rdstring;
177
178       Returns a string representation of the RR-specific data.
179
180   rdlength
181           $rdlength = $rr->rdlength;
182
183       Returns the uncompressed length of the encoded RR-specific data.
184

Sorting of RR arrays

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

COPYRIGHT

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

LICENSE

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