view release on metacpan or  search on metacpan

lib/Net/DNS/Resolver.pm  view on Meta::CPAN

When called in list context, C<axfr()> returns a list of L<Net::DNS::RR>
objects.  The redundant SOA record that terminates the zone transfer
is not returned to the caller.

In deferrence to RFC1035(6.3), a complete zone transfer is expected
to return all records in the zone or nothing at all.
When no resource records are returned by C<axfr()>,
the reason for failure may be determined using C<errorstring()>.

Here is an example that uses a timeout and TSIG verification:

	$resolver->tcp_timeout( 10 );
	$resolver->tsig( $keyfile );
	@zone = $resolver->axfr( 'example.com' );

	foreach $rr (@zone) {
		$rr->print;
	}


When called in scalar context, C<axfr()> returns an iterator object.
Each invocation of the iterator returns a single L<Net::DNS::RR>
or C<undef> when the zone is exhausted.

An exception is raised if the zone transfer can not be completed.

The redundant SOA record that terminates the zone transfer is not
returned to the caller.

Here is the example above, implemented using an iterator:

	$resolver->tcp_timeout( 10 );
	$resolver->tsig( $keyfile );
	$iterator = $resolver->axfr( 'example.com' );

	while ( $rr = $iterator->() ) {
		$rr->print;
	}


=head2 bgsend

	$handle = $resolver->bgsend( $packet ) || die $resolver->errorstring;

	$handle = $resolver->bgsend( 'host.example.com' );
	$handle = $resolver->bgsend( '2001:DB8::1' );
	$handle = $resolver->bgsend( 'example.com', 'MX' );
	$handle = $resolver->bgsend( 'annotation.example.com', 'TXT', 'IN' );

Performs a background DNS query for the given name and returns immediately
without waiting for the response. The program can then perform other tasks
while awaiting the response from the nameserver.

The argument list can be either a L<Net::DNS::Packet> object or a list
of strings.  The record type and class can be omitted; they default to
A and IN.  If the name looks like an IP address (IPv4 or IPv6),
then a query within in-addr.arpa or ip6.arpa will be performed.

Returns an opaque handle which is passed to subsequent invocations of
the C<bgbusy()> and C<bgread()> methods.
Errors are indicated by returning C<undef> in which case
the reason for failure may be determined using C<errorstring()>.

The response L<Net::DNS::Packet> object is obtained by calling C<bgread()>.

B<BEWARE>:
Programs should make no assumptions about the nature of the handles
returned by C<bgsend()> which should be used strictly as described here.


=head2 bgread

	$handle = $resolver->bgsend( 'www.example.com' );
	$packet = $resolver->bgread($handle);

Reads the response following a background query.
The argument is the handle returned by C<bgsend()>.

Returns a L<Net::DNS::Packet> object or C<undef> if no response was
received before the timeout interval expired. 


=head2 bgbusy

	$handle = $resolver->bgsend( 'foo.example.com' );

	while ($resolver->bgbusy($handle)) {
		...
	}

	$packet = $resolver->bgread($handle);

Returns true while awaiting the response or for the transaction to time out.
The argument is the handle returned by C<bgsend()>.

Truncated UDP packets will be retried transparently using TCP while
continuing to assert busy to the caller.


=head2 debug

	print 'debug flag: ', $resolver->debug, "\n";
	$resolver->debug(1);

Get or set the debug flag.
If set, calls to C<search()>, C<query()>, and C<send()> will print
debugging information on the standard output.
The default is false.


=head2 defnames

	print 'defnames flag: ', $resolver->defnames, "\n";
	$resolver->defnames(0);

Get or set the defnames flag.
If true, calls to C<query()> will append the default domain to
resolve names that are not fully qualified.
The default is true.


=head2 dnsrch

	print 'dnsrch flag: ', $resolver->dnsrch, "\n";
	$resolver->dnsrch(0);

Get or set the dnsrch flag.
If true, calls to C<search()> will apply the search list to resolve
names that are not fully qualified.
The default is true.


=head2 domain

	$domain = $resolver->domain;
	$resolver->domain( 'domain.example' );

Gets or sets the resolver default domain.


=head2 igntc

	print 'igntc flag: ', $resolver->igntc, "\n";
	$resolver->igntc(1);

Get or set the igntc flag.
If true, truncated packets will be ignored.
If false, the query will be retried using TCP.
The default is false.


=head2 nameserver, nameservers

	@nameservers = $resolver->nameservers();
	$resolver->nameservers( '2001:DB8::1', '192.0.2.1' );
	$resolver->nameservers( 'ns.domain.example.' );