.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Zonemaster::Engine::Zone 3pm"
.TH Zonemaster::Engine::Zone 3pm 2024-04-22 "perl v5.38.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
Zonemaster::Engine::Zone \- Object representing a DNS zone
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    my $zone = Zonemaster::Engine::Zone\->new({ name => \*(Aqnic.se\*(Aq });
\&    my $packet = $zone\->parent\->query_one($zone\->name, \*(AqNS\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Objects of this class represent zones in DNS. As far as possible, test
implementations should access information about zones via these
objects. Doing so will provide lazy-loading of the information,
well-defined methods in which the information is fetched, logging and
the ability to do things like testing zones that have not yet been
delegated.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
.IP name 4
.IX Item "name"
A Zonemaster::Engine::DNSName object representing the name of the zone.
.IP parent 4
.IX Item "parent"
A Zonemaster::Engine::Zone object for this domain's parent domain. As a
special case, the root zone is considered to be its own parent (so
look for that if you recurse up the tree).
.IP ns_names 4
.IX Item "ns_names"
A reference to an array of Zonemaster::Engine::DNSName objects, holding the
names of the nameservers for the domain, as returned by the first
responding nameserver in the glue list.
.IP ns 4
.IX Item "ns"
A reference to an array of Zonemaster::Engine::Nameserver objects for the
domain, built by taking the list returned from \fBns_names()\fR and
looking up addresses for the names. One element will be added to this
list for each unique name/IP pair. Names for which no addresses could
be found will not be in this list. The list is lazy-loading, so take
care to only look at as many entries as you really need. There are
zones with more than 20 nameserver, and looking up the addresses of
them all can take som considerable time.
.IP glue_names 4
.IX Item "glue_names"
A reference to a an array of Zonemaster::Engine::DNSName objects, holding the names
of this zones nameservers as listed at the first responding nameserver of the
parent zone.
.IP glue 4
.IX Item "glue"
A reference to an array of Zonemaster::Engine::Nameserver objects for the
domain, built by taking the list returned from \fBglue_names()\fR and
looking up addresses for the names. One element will be added to this
list for each unique name/IP pair. Names for which no addresses could
be found will not be in this list. In this case, the list is lazy-loading, so take
care to only look at as many entries as you really need. In case of 
undelegated tests and fake delegation the IP associated with name servers
for the tested zone will be the ones set by users (saved in 
\&\f(CW%Zonemaster::Engine::Recursor::fake_addresses_cache\fR), instead of the ones
found recursively.
.IP glue_addresses 4
.IX Item "glue_addresses"
A list of Zonemaster::LDNS::RR::A and Zonemaster::LDNS::RR::AAAA records returned in
the Additional section of an NS query to the first listed nameserver for the
parent domain.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "query_one($name[, $type[, $flags]])" 4
.el .IP "query_one($name[, \f(CW$type\fR[, \f(CW$flags\fR]])" 4
.IX Item "query_one($name[, $type[, $flags]])"
Sends (or retrieves from cache) a query for the given name, type and flags sent to the first nameserver in the zone's ns list. If there is a
response, it will be returned in a Zonemaster::Engine::Packet object. If the type arguments is not given, it defaults to 'A'. If the flags are not given, they default to \f(CW\*(C`class\*(C'\fR IN and \f(CW\*(C`dnssec\*(C'\fR, \f(CW\*(C`usevc\*(C'\fR and \f(CW\*(C`recurse\*(C'\fR according to configuration (which is by default off on all three).
.ie n .IP "query_persistent($name[, $type[, $flags]])" 4
.el .IP "query_persistent($name[, \f(CW$type\fR[, \f(CW$flags\fR]])" 4
.IX Item "query_persistent($name[, $type[, $flags]])"
Identical to query_one, except that instead of returning the packet from the
first server that returns one, it returns the first packet that actually
contains a resource record matching the requested name and type.
.ie n .IP "query_auth($name[, $type[, $flags]])" 4
.el .IP "query_auth($name[, \f(CW$type\fR[, \f(CW$flags\fR]])" 4
.IX Item "query_auth($name[, $type[, $flags]])"
Identical to query_one, except that instead of returning the packet from the
first server that returns one, it returns the first packet that has the AA flag set.
.ie n .IP "query_all($name, $type, $flags)" 4
.el .IP "query_all($name, \f(CW$type\fR, \f(CW$flags\fR)" 4
.IX Item "query_all($name, $type, $flags)"
Sends (or retrieves from cache) queries to all the nameservers listed in the zone's ns list, and returns a reference to an array with the
responses. The responses can be either Zonemaster::Engine::Packet objects or \f(CW\*(C`undef\*(C'\fR values. The arguments are the same as for query_one.
.IP is_in_zone($name) 4
.IX Item "is_in_zone($name)"
Returns true if the given name is in the zone, false if not. If it could not be
determined with a sufficient degree of certainty if the name is in the zone or
not, \f(CW\*(C`undef\*(C'\fR is returned.