File Coverage

blib/lib/Net/LDNS.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Net::LDNS;
2              
3 13     13   159272 use 5.10.1;
  13         35  
  13         563  
4              
5             our $VERSION = '0.73';
6              
7 13     13   4874 use parent 'Exporter';
  13         2811  
  13         46  
8             our @EXPORT_OK = qw[to_idn has_idn ldns_version load_zonefile];
9             our %EXPORT_TAGS = ( all => \@EXPORT_OK );
10              
11             require XSLoader;
12             XSLoader::load( __PACKAGE__, $VERSION );
13              
14 13     13   4331 use Net::LDNS::RR;
  13         28  
  13         322  
15 13     13   3812 use Net::LDNS::Packet;
  13         21  
  13         636  
16              
17             1;
18              
19             =head1 NAME
20              
21             Net::LDNS - DNS-talking module based on the ldns C library
22              
23             =head1 SYNOPSIS
24              
25             my $resolver = Net::LDNS->new('8.8.8.8');
26             my $packet = $resolver->query('www.iis.se');
27             say $packet->string;
28              
29             =head1 DESCRIPTION
30              
31             C represents a resolver, which is the part of the system responsible for sending queries and receiving answers to them.
32              
33             =head1 EXPORTABLE FUNCTIONS
34              
35             =over
36              
37             =item lib_version()
38              
39             Returns the ldns version string. Can be exported, but is not by default.
40              
41             =item to_idn($name, ...)
42              
43             Takes a number of strings and returns a list of them converted to IDNA format.
44             Assumes that the strings have been converted to Perl's internal encoding before
45             it's called. Can be exported, but is not by default.
46              
47             This function requires that GNU libidn was present when L was
48             compiled. If not, calling C will result in an exception getting thrown.
49              
50             =item has_idn()
51              
52             Takes no arguments. Returns true if libidn was present at compilation, false if not.
53              
54             =item has_gost()
55              
56             Takes no arguments. Returns true if GOST support was present at compilation, false if not.
57              
58             =item load_zonefile($filename)
59              
60             Load all resource records in a zone file, returning them as a list.
61              
62             =back
63              
64             =head1 CLASS METHOD
65              
66             =over
67              
68             =item new($addr,...)
69              
70             Creates a new resolver object. If given no arguments, if will pick up nameserver addresses from the system configuration (F or
71             equivalent). If given a single argument that is C, it will not know of any nameservers and all attempts to send queries will throw
72             exceptions. If given one or more arguments that are not C, attempts to parse them as IPv4 and IPv6 addresses will be made, and if successful
73             make up a list of servers to send queries to. If an argument cannot be parsed as an IP address, an exception will be thrown.
74              
75             =back
76              
77             =head1 INSTANCE METHODS
78              
79             =over
80              
81             =item query($name, $type, $class)
82              
83             Send a query for the given triple. If type or class are not provided they default to A and IN, respectively. Returns a L or
84             undef.
85              
86             =item name2addr($name)
87              
88             Asks this resolver to look up A and AAAA records for the given name, and return a list of the IP addresses (as strings). In scalar context, returns
89             the number of addresses found.
90              
91             =item addr2name($addr)
92              
93             Takes an IP address, asks the resolver to do PTR lookups and returns the names found. In scalar context, returns the number of names found.
94              
95             =item recurse($flag)
96              
97             Returns the setting of the recursion flag. If given an argument, it will be treated as a boolean and the flag set accordingly.
98              
99             =item debug($flag)
100              
101             Gets and optionally sets the debug flag.
102              
103             =item dnssec($flag)
104              
105             Get and optionally sets the DNSSEC flag.
106              
107             =item cd($flag)
108              
109             Get and optionally sets the CD flag.
110              
111             =item igntc($flag)
112              
113             Get and optionally sets the igntc flag.
114              
115             =item usevc($flag)
116              
117             Get and optionally sets the usevc flag.
118              
119             =item retry($count)
120              
121             Get and optionally set the number of retries.
122              
123             =item retrans($seconds)
124              
125             Get and optionally set the number of seconds between retries.
126              
127             =item port($port)
128              
129             Get and optionally set the destination port for requests.
130              
131             =item edns_size($size)
132              
133             Get and optionally set the EDNS0 UDP maximum size.
134              
135              
136             =item axfr( $domain, $callback, $class )
137              
138             Perform an AXFR operation. C<$callback> must be a code reference, which will be
139             called once for every received resource record with the RR object as its one
140             and only argument. After every such call, the return value of the callback will
141             be examined, and if the value is false the AXFR process will be aborted. The
142             return value of the C method itself will be true if the transfer
143             completed normally, and false if it was aborted because the callback returned a
144             false value.
145              
146             If anything goes wrong during the process, an exception will be thrown.
147              
148             As an example, saving all the RRs received from an AXFR can be done like this:
149              
150             my @rrs;
151             $resolver->axfr( $domain, sub { my ($rr) = @_; push @rrs, $rr; return 1;} );
152              
153             =item axfr_start($domain,$class)
154              
155             Deprecated. Use L instead.
156              
157             Set this resolver object up for a zone transfer of the specified domain. If C<$class> is not given, it defaults to IN.
158              
159             =item axfr_next()
160              
161             Deprecated. Use L instead.
162              
163             Get the next RR in the zone transfer. L must have been done before this is called, and after this is called L
164             should be used to check if there are more records to get. If there's any problem, an exception will be thrown. Basically, the sequence should be
165             something like:
166              
167             $res->axfr_start('example.org');
168             do {
169             push @rrlist, $res->axfr_next;
170             } until $res->axfr_complete;
171              
172             =item axfr_complete()
173              
174             Deprecated. Use L instead.
175              
176             Returns false if there is a started zone transfer with more records to get, and true if the started transfer has completed.
177              
178             =item axfr_last_packet()
179              
180             Deprecated. Use L instead.
181              
182             If L threw an exception, this method returns the L that made it do so. The packet's RCODE is likely to say what
183             the problem was (for example, NOTAUTH or NXDOMAIN).
184              
185             =item timeout($time)
186              
187             Get and/or set the socket timeout for the resolver.
188              
189             =back