File Coverage

blib/lib/Zonemaster/LDNS.pm

Criterion	Covered	Total	%
statement	11	11	100.0
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	15	15	100.0

line	stmt	sub	time	code
1				package Zonemaster::LDNS;
2
3	13	13	541363	use 5.014;
	13		148
4
5				our $VERSION = '1.0.1';
6
7	13	13	3050	use parent 'Exporter';
	13		3134
	13		57
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	4275	use Zonemaster::LDNS::RR;
	13		42
	13		372
15	13	13	3263	use Zonemaster::LDNS::Packet;
	13		31
	13		561
16
17				1;
18
19				=head1 NAME
20
21				Zonemaster::LDNS - DNS-talking module based on the ldns C library
22
23				=head1 SYNOPSIS
24
25				my $resolver = Zonemaster::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				=item source($addr)
190
191				Get and/or set the IP address the resolver should try to send its queries from.
192
193				=back