.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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" ''
.    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 "Net::DNS::DomainName 3pm"
.TH Net::DNS::DomainName 3pm "2020-11-20" "perl v5.32.0" "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::DomainName \- DNS name representation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::DNS::DomainName;
\&
\&    $object = Net::DNS::DomainName\->new(\*(Aqexample.com\*(Aq);
\&    $name = $object\->name;
\&    $data = $object\->encode;
\&
\&    ( $object, $next ) = Net::DNS::DomainName\->decode( \e$data, $offset );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Net::DNS::DomainName module implements the concrete representation
of \s-1DNS\s0 domain names used within \s-1DNS\s0 packets.
.PP
Net::DNS::DomainName defines methods for encoding and decoding wire
format octet strings. All other behaviour is inherited from
Net::DNS::Domain.
.PP
The Net::DNS::DomainName1035 and Net::DNS::DomainName2535 packages
implement disjoint domain name subtypes which provide the name
compression and canonicalisation specified by \s-1RFC1035\s0 and \s-1RFC2535.\s0
These are necessary to meet the backward compatibility requirements
introduced by \s-1RFC3597.\s0
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    $object = Net::DNS::DomainName\->new(\*(Aqexample.com\*(Aq);
.Ve
.PP
Creates a domain name object which identifies the domain specified
by the character string argument.
.SS "canonical"
.IX Subsection "canonical"
.Vb 1
\&    $data = $object\->canonical;
.Ve
.PP
Returns the canonical wire-format representation of the domain name
as defined in \s-1RFC2535\s0(8.1).
.SS "decode"
.IX Subsection "decode"
.Vb 1
\&    $object = Net::DNS::DomainName\->decode( \e$buffer, $offset, $hash );
\&
\&    ( $object, $next ) = Net::DNS::DomainName\->decode( \e$buffer, $offset, $hash );
.Ve
.PP
Creates a domain name object which represents the \s-1DNS\s0 domain name
identified by the wire-format data at the indicated offset within
the data buffer.
.PP
The argument list consists of a reference to a scalar containing the
wire-format data and specified offset. The optional reference to a
hash table provides improved efficiency of decoding compressed names
by exploiting already cached compression pointers.
.PP
The returned offset value indicates the start of the next item in the
data buffer.
.SS "encode"
.IX Subsection "encode"
.Vb 1
\&    $data = $object\->encode;
.Ve
.PP
Returns the wire-format representation of the domain name suitable
for inclusion in a \s-1DNS\s0 packet buffer.
.SH "Net::DNS::DomainName1035"
.IX Header "Net::DNS::DomainName1035"
Net::DNS::DomainName1035 implements a subclass of domain name
objects which are to be encoded using the compressed wire format
defined in \s-1RFC1035.\s0
.PP
.Vb 1
\&    use Net::DNS::DomainName;
\&
\&    $object = Net::DNS::DomainName1035\->new(\*(Aqcompressible.example.com\*(Aq);
\&    $data   = $object\->encode( $offset, $hash );
\&
\&    ( $object, $next ) = Net::DNS::DomainName1035\->decode( \e$data, $offset );
.Ve
.PP
Note that \s-1RFC3597\s0 implies that the \s-1RR\s0 types defined in \s-1RFC1035\s0
section 3.3 are the only types eligible for compression.
.SS "encode"
.IX Subsection "encode"
.Vb 1
\&    $data = $object\->encode( $offset, $hash );
.Ve
.PP
Returns the wire-format representation of the domain name suitable
for inclusion in a \s-1DNS\s0 packet buffer.
.PP
The optional arguments are the offset within the packet data where
the domain name is to be stored and a reference to a hash table used
to index compressed names within the packet.
.PP
If the hash reference is undefined, \fBencode()\fR returns the lowercase
uncompressed canonical representation defined in \s-1RFC2535\s0(8.1).
.SH "Net::DNS::DomainName2535"
.IX Header "Net::DNS::DomainName2535"
Net::DNS::DomainName2535 implements a subclass of domain name
objects which are to be encoded using uncompressed wire format.
.PP
Note that \s-1RFC3597,\s0 and latterly \s-1RFC4034,\s0 specifies that the lower
case canonical encoding defined in \s-1RFC2535\s0 is to be used for \s-1RR\s0
types defined prior to \s-1RFC3597.\s0
.PP
.Vb 1
\&    use Net::DNS::DomainName;
\&
\&    $object = Net::DNS::DomainName2535\->new(\*(Aqincompressible.example.com\*(Aq);
\&    $data   = $object\->encode( $offset, $hash );
\&
\&    ( $object, $next ) = Net::DNS::DomainName2535\->decode( \e$data, $offset );
.Ve
.SS "encode"
.IX Subsection "encode"
.Vb 1
\&    $data = $object\->encode( $offset, $hash );
.Ve
.PP
Returns the uncompressed wire-format representation of the domain
name suitable for inclusion in a \s-1DNS\s0 packet buffer.
.PP
If the hash reference is undefined, \fBencode()\fR returns the lowercase
canonical form defined in \s-1RFC2535\s0(8.1).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c)2009\-2011 Dick Franks.
.PP
All rights reserved.
.SH "LICENSE"
.IX Header "LICENSE"
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of the author not be used in advertising
or publicity pertaining to distribution of the software without specific
prior written permission.
.PP
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, Net::DNS, Net::DNS::Domain, \s-1RFC1035, RFC2535,
RFC3597, RFC4034\s0