.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::DNS 3pm"
.TH Net::DNS 3pm "2009-12-30" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::DNS \- Perl interface to the DNS resolver
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`use Net::DNS;\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::DNS is a collection of Perl modules that act as a Domain
Name System (\s-1DNS\s0) resolver.  It allows the programmer to perform
\&\s-1DNS\s0 queries that are beyond the capabilities of \f(CW\*(C`gethostbyname\*(C'\fR
and \f(CW\*(C`gethostbyaddr\*(C'\fR.
.PP
The programmer should be somewhat familiar with the format of
a \s-1DNS\s0 packet and its various sections.  See \s-1RFC\s0 1035 or
\&\fI\s-1DNS\s0 and \s-1BIND\s0\fR (Albitz & Liu) for details.
.SS "Resolver Objects"
.IX Subsection "Resolver Objects"
A resolver object is an instance of the
Net::DNS::Resolver class. A program can have
multiple resolver objects, each maintaining its own state information
such as the nameservers to be queried, whether recursion is desired,
etc.
.SS "Packet Objects"
.IX Subsection "Packet Objects"
Net::DNS::Resolver queries return
Net::DNS::Packet objects.  Packet objects have five
sections:
.IP "\(bu" 3
The header section, a Net::DNS::Header object.
.IP "\(bu" 3
The question section, a list of Net::DNS::Question
objects.
.IP "\(bu" 3
The answer section, a list of Net::DNS::RR objects.
.IP "\(bu" 3
The authority section, a list of Net::DNS::RR objects.
.IP "\(bu" 3
The additional section, a list of Net::DNS::RR objects.
.SS "Update Objects"
.IX Subsection "Update Objects"
The Net::DNS::Update package is a subclass of
Net::DNS::Packet for creating packet objects to be
used in dynamic updates.
.SS "Header Objects"
.IX Subsection "Header Objects"
Net::DNS::Header objects represent the header
section of a \s-1DNS\s0 packet.
.SS "Question Objects"
.IX Subsection "Question Objects"
Net::DNS::Question objects represent the question
section of a \s-1DNS\s0 packet.
.SS "\s-1RR\s0 Objects"
.IX Subsection "RR Objects"
Net::DNS::RR is the base class for \s-1DNS\s0 resource record
(\s-1RR\s0) objects in the answer, authority, and additional sections of a \s-1DNS\s0
packet.
.PP
Don't assume that \s-1RR\s0 objects will be of the type you requested \*(-- always
check an \s-1RR\s0 object's type before calling any of its methods.
.SH "METHODS"
.IX Header "METHODS"
See the manual pages listed above for other class-specific methods.
.SS "version"
.IX Subsection "version"
.Vb 1
\&    print Net::DNS\->version, "\en";
.Ve
.PP
Returns the version of Net::DNS.
.SS "mx"
.IX Subsection "mx"
.Vb 3
\&    # Use a default resolver \-\- can\*(Aqt get an error string this way.
\&    use Net::DNS;
\&    my @mx = mx("example.com");
\&
\&    # Use your own resolver object.
\&    use Net::DNS;
\&    my $res = Net::DNS::Resolver\->new;
\&    my  @mx = mx($res, "example.com");
.Ve
.PP
Returns a list of Net::DNS::RR::MX objects
representing the \s-1MX\s0 records for the specified name; the list will be
sorted by preference. Returns an empty list if the query failed or no \s-1MX\s0
records were found.
.PP
This method does not look up A records \*(-- it only performs \s-1MX\s0 queries.
.PP
See \*(L"\s-1EXAMPLES\s0\*(R" for a more complete example.
.SS "yxrrset"
.IX Subsection "yxrrset"
Use this method to add an \*(L"RRset exists\*(R" prerequisite to a dynamic
update packet.  There are two forms, value-independent and
value-dependent:
.PP
.Vb 2
\&    # RRset exists (value\-independent)
\&    $update\->push(pre => yxrrset("host.example.com A"));
.Ve
.PP
Meaning:  At least one \s-1RR\s0 with the specified name and type must
exist.
.PP
.Vb 2
\&    # RRset exists (value\-dependent)
\&    $packet\->push(pre => yxrrset("host.example.com A 10.1.2.3"));
.Ve
.PP
Meaning:  At least one \s-1RR\s0 with the specified name and type must
exist and must have matching data.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "nxrrset"
.IX Subsection "nxrrset"
Use this method to add an \*(L"RRset does not exist\*(R" prerequisite to
a dynamic update packet.
.PP
.Vb 1
\&    $packet\->push(pre => nxrrset("host.example.com A"));
.Ve
.PP
Meaning:  No RRs with the specified name and type can exist.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "yxdomain"
.IX Subsection "yxdomain"
Use this method to add a \*(L"name is in use\*(R" prerequisite to a dynamic
update packet.
.PP
.Vb 1
\&    $packet\->push(pre => yxdomain("host.example.com"));
.Ve
.PP
Meaning:  At least one \s-1RR\s0 with the specified name must exist.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "nxdomain"
.IX Subsection "nxdomain"
Use this method to add a \*(L"name is not in use\*(R" prerequisite to a
dynamic update packet.
.PP
.Vb 1
\&    $packet\->push(pre => nxdomain("host.example.com"));
.Ve
.PP
Meaning:  No \s-1RR\s0 with the specified name can exist.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "rr_add"
.IX Subsection "rr_add"
Use this method to add RRs to a zone.
.PP
.Vb 1
\&    $packet\->push(update => rr_add("host.example.com A 10.1.2.3"));
.Ve
.PP
Meaning:  Add this \s-1RR\s0 to the zone.
.PP
\&\s-1RR\s0 objects created by this method should be added to the \*(L"update\*(R"
section of a dynamic update packet.  The \s-1TTL\s0 defaults to 86400
seconds (24 hours) if not specified.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "rr_del"
.IX Subsection "rr_del"
Use this method to delete RRs from a zone.  There are three forms:
delete an RRset, delete all RRsets, and delete an \s-1RR\s0.
.PP
.Vb 2
\&    # Delete an RRset.
\&    $packet\->push(update => rr_del("host.example.com A"));
.Ve
.PP
Meaning:  Delete all RRs having the specified name and type.
.PP
.Vb 2
\&    # Delete all RRsets.
\&    $packet\->push(update => rr_del("host.example.com"));
.Ve
.PP
Meaning:  Delete all RRs having the specified name.
.PP
.Vb 2
\&    # Delete an RR.
\&    $packet\->push(update => rr_del("host.example.com A 10.1.2.3"));
.Ve
.PP
Meaning:  Delete all RRs having the specified name, type, and data.
.PP
\&\s-1RR\s0 objects created by this method should be added to the \*(L"update\*(R"
section of a dynamic update packet.
.PP
Returns a \f(CW\*(C`Net::DNS::RR\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR if the object couldn't
be created.
.SS "Sorting of \s-1RR\s0 arrays"
.IX Subsection "Sorting of RR arrays"
As of version 0.55 there is functionality to help you sort \s-1RR\s0
arrays. '\fIrrsort()\fR' is the function that is available to do the
sorting. In most cases rrsort will give you the answer that you
want but you can specify your own sorting method by using the 
Net::DNS::RR::FOO\->\fIset_rrsort_func()\fR class method. See Net::DNS::RR
for details.
.PP
\fI\fIrrsort()\fI\fR
.IX Subsection "rrsort()"
.PP
.Vb 1
\&   use Net::DNS qw(rrsort);
\&
\&   my @prioritysorted=rrsort("SRV","priority",@rr_array);
.Ve
.PP
\&\fIrrsort()\fR selects all RRs from the input array that are of the type
that are defined in the first argument. Those RRs are sorted based on
the attribute that is specified as second argument.
.PP
There are a number of RRs for which the sorting function is
specifically defined for certain attributes.  If such sorting function
is defined in the code (it can be set or overwritten using the
\&\fIset_rrsort_func()\fR class method) that function is used.
.PP
For instance:
   my \f(CW@prioritysorted\fR=rrsort(\*(L"\s-1SRV\s0\*(R",\*(L"priority\*(R",@rr_array);
returns the \s-1SRV\s0 records sorted from lowest to heighest priority and
for equal priorities from heighes to lowes weight.
.PP
If the function does not exist then a numerical sort on the attribute
value is performed. 
   my \f(CW@portsorted\fR=rrsort(\*(L"\s-1SRV\s0\*(R",\*(L"port\*(R",@rr_array);
.PP
If the attribute does not exist for a certain \s-1RR\s0 than the RRs are
sorted on string comparrisson of the rdata.
.PP
If the attribute is not defined than either the default_sort function
will be defined or \*(L"Canonical sorting\*(R" (as defined by \s-1DNSSEC\s0) will be
used.
.PP
\&\fIrrsort()\fR returns a sorted array with only elements of the specified
\&\s-1RR\s0 type or undef.
.PP
\&\fIrrsort()\fR returns undef when arguments are incorrect.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The following examples show how to use the \f(CW\*(C`Net::DNS\*(C'\fR modules.
See the other manual pages and the demo scripts included with the
source code for additional examples.
.PP
See the \f(CW\*(C`Net::DNS::Update\*(C'\fR manual page for an example of performing
dynamic updates.
.SS "Look up a host's addresses."
.IX Subsection "Look up a host's addresses."
.Vb 3
\&  use Net::DNS;
\&  my $res   = Net::DNS::Resolver\->new;
\&  my $query = $res\->search("host.example.com");
\&  
\&  if ($query) {
\&      foreach my $rr ($query\->answer) {
\&          next unless $rr\->type eq "A";
\&          print $rr\->address, "\en";
\&      }
\&  } else {
\&      warn "query failed: ", $res\->errorstring, "\en";
\&  }
.Ve
.SS "Find the nameservers for a domain."
.IX Subsection "Find the nameservers for a domain."
.Vb 3
\&  use Net::DNS;
\&  my $res   = Net::DNS::Resolver\->new;
\&  my $query = $res\->query("example.com", "NS");
\&  
\&  if ($query) {
\&      foreach $rr (grep { $_\->type eq \*(AqNS\*(Aq } $query\->answer) {
\&          print $rr\->nsdname, "\en";
\&      }
\&  }
\&  else {
\&      warn "query failed: ", $res\->errorstring, "\en";
\&  }
.Ve
.SS "Find the \s-1MX\s0 records for a domain."
.IX Subsection "Find the MX records for a domain."
.Vb 4
\&  use Net::DNS;
\&  my $name = "example.com";
\&  my $res  = Net::DNS::Resolver\->new;
\&  my @mx   = mx($res, $name);
\&  
\&  if (@mx) {
\&      foreach $rr (@mx) {
\&          print $rr\->preference, " ", $rr\->exchange, "\en";
\&      }
\&  } else {
\&      warn "Can\*(Aqt find MX records for $name: ", $res\->errorstring, "\en";
\&  }
.Ve
.SS "Print a domain's \s-1SOA\s0 record in zone file format."
.IX Subsection "Print a domain's SOA record in zone file format."
.Vb 3
\&  use Net::DNS;
\&  my $res   = Net::DNS::Resolver\->new;
\&  my $query = $res\->query("example.com", "SOA");
\&  
\&  if ($query) {
\&      ($query\->answer)[0]\->print;
\&  } else {
\&      print "query failed: ", $res\->errorstring, "\en";
\&  }
.Ve
.SS "Perform a zone transfer and print all the records."
.IX Subsection "Perform a zone transfer and print all the records."
.Vb 3
\&  use Net::DNS;
\&  my $res  = Net::DNS::Resolver\->new;
\&  $res\->nameservers("ns.example.com");
\&  
\&  my @zone = $res\->axfr("example.com");
\&  
\&  foreach $rr (@zone) {
\&      $rr\->print;
\&  }
.Ve
.SS "Perform a background query and do some other work while waiting for the answer."
.IX Subsection "Perform a background query and do some other work while waiting for the answer."
.Vb 3
\&  use Net::DNS;
\&  my $res    = Net::DNS::Resolver\->new;
\&  my $socket = $res\->bgsend("host.example.com");
\&
\&  until ($res\->bgisready($socket)) {
\&      # do some work here while waiting for the answer
\&      # ...and some more here
\&  }
\&
\&  my $packet = $res\->bgread($socket);
\&  $packet\->print;
.Ve
.SS "Send a background query and use select to determine when the answer has arrived."
.IX Subsection "Send a background query and use select to determine when the answer has arrived."
.Vb 2
\&  use Net::DNS;
\&  use IO::Select;
\&  
\&  my $timeout = 5;
\&  my $res     = Net::DNS::Resolver\->new;
\&  my $bgsock  = $res\->bgsend("host.example.com");
\&  my $sel     = IO::Select\->new($bgsock);
\&  
\&  # Add more sockets to $sel if desired.
\&  my @ready = $sel\->can_read($timeout);
\&  if (@ready) {
\&      foreach my $sock (@ready) {
\&          if ($sock == $bgsock) {
\&              my $packet = $res\->bgread($bgsock);
\&              $packet\->print;
\&              $bgsock = undef;
\&          }
\&          # Check for the other sockets.
\&          $sel\->remove($sock);
\&          $sock = undef;
\&      }
\&  } else {
\&      warn "timed out after $timeout seconds\en";
\&  }
.Ve
.SH "BUGS"
.IX Header "BUGS"
\&\f(CW\*(C`Net::DNS\*(C'\fR is slow.
.PP
For other items to be fixed, please see the \s-1TODO\s0 file included with
the source distribution.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997\-2002 Michael Fuhr. 
Portions Copyright (c) 2002\-2004 Chris Reinhardt.
Portions Copyright (c) 2005 Olaf Kolkman (\s-1RIPE\s0 \s-1NCC\s0)
Portions Copyright (c) 2006 Olaf Kolkman (NLnet Labs)
.PP
All rights reserved.  This program is free software; you may redistribute
it and/or modify it under the same terms as Perl itself.
.SH "AUTHOR INFORMATION"
.IX Header "AUTHOR INFORMATION"
Net::DNS is currently maintained at NLnet Labs (www.nlnetlabs.nl) by:
        Olaf Kolkman
	olaf@net\-dns.org
.PP
Between 2002 and 2004 Net::DNS was maintained by:
       Chris Reinhardt
.PP
Net::DNS was created by:
	Michael Fuhr
	mike@fuhr.org
.PP
For more information see:
    http://www.net\-dns.org/
.PP
Stay tuned and syncicate:
    http://www.net\-dns.org/blog/
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Update,
Net::DNS::Header, Net::DNS::Question, Net::DNS::RR, \s-1RFC\s0 1035,
\&\fI\s-1DNS\s0 and \s-1BIND\s0\fR by Paul Albitz & Cricket Liu