=head1 NAME

AnyEvent::DNS - fully asynchronous DNS resolution

=head1 SYNOPSIS

   use AnyEvent::DNS;
   
   my $cv = AnyEvent->condvar;
   AnyEvent::DNS::a "www.google.de", $cv;
   # ... later
   my @addrs = $cv->recv;

=head1 DESCRIPTION

This module offers both a number of DNS convenience functions as well
as a fully asynchronous and high-performance pure-perl stub resolver.

The stub resolver supports DNS over IPv4 and IPv6, UDP and TCP, optional
EDNS0 support for up to 4kiB datagrams and automatically falls back to
virtual circuit mode for large responses.

=head2 CONVENIENCE FUNCTIONS

=over 4

=cut

package AnyEvent::DNS;

no warnings;
use strict;

use Socket qw(AF_INET SOCK_DGRAM SOCK_STREAM);

use AnyEvent ();
use AnyEvent::Handle ();
use AnyEvent::Util qw(AF_INET6);

our $VERSION = 4.151;

our @DNS_FALLBACK = (v208.67.220.220, v208.67.222.222);

=item AnyEvent::DNS::a $domain, $cb->(@addrs)

Tries to resolve the given domain to IPv4 address(es).

=item AnyEvent::DNS::aaaa $domain, $cb->(@addrs)

Tries to resolve the given domain to IPv6 address(es).

=item AnyEvent::DNS::mx $domain, $cb->(@hostnames)

Tries to resolve the given domain into a sorted (lower preference value
first) list of domain names.

=item AnyEvent::DNS::ns $domain, $cb->(@hostnames)

Tries to resolve the given domain name into a list of name servers.

=item AnyEvent::DNS::txt $domain, $cb->(@hostnames)

Tries to resolve the given domain name into a list of text records.

=item AnyEvent::DNS::srv $service, $proto, $domain, $cb->(@srv_rr)

Tries to resolve the given service, protocol and domain name into a list
of service records.

Each C<$srv_rr> is an array reference with the following contents: 
C<[$priority, $weight, $transport, $target]>.

They will be sorted with lowest priority first, then randomly
distributed by weight as per RFC 2782.

Example:

   AnyEvent::DNS::srv "sip", "udp", "schmorp.de", sub { ...
   # @_ = ( [10, 10, 5060, "sip1.schmorp.de" ] )

=item AnyEvent::DNS::ptr $domain, $cb->(@hostnames)

Tries to make a PTR lookup on the given domain. See C<reverse_lookup>
and C<reverse_verify> if you want to resolve an IP address to a hostname
instead.

=item AnyEvent::DNS::any $domain, $cb->(@rrs)

Tries to resolve the given domain and passes all resource records found to
the callback.

=item AnyEvent::DNS::reverse_lookup $ipv4_or_6, $cb->(@hostnames)

Tries to reverse-resolve the given IPv4 or IPv6 address (in textual form)
into it's hostname(s). Handles V4MAPPED and V4COMPAT IPv6 addresses
transparently.

=item AnyEvent::DNS::reverse_verify $ipv4_or_6, $cb->(@hostnames)

The same as C<reverse_lookup>, but does forward-lookups to verify that