.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\"
.\" 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 "Socket::GetAddrInfo 3pm"
.TH Socket::GetAddrInfo 3pm "2022-10-13" "perl v5.34.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"
"Socket::GetAddrInfo" \- address\-family independent name resolving functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use Socket qw( SOCK_STREAM );
\& use Socket::GetAddrInfo qw( getaddrinfo getnameinfo );
\& use IO::Socket;
\&
\& my %hints = ( socktype => SOCK_STREAM );
\& my ( $err, @res ) = getaddrinfo( "www.google.com", "www", \e%hints );
\&
\& die "Cannot resolve name \- $err" if $err;
\&
\& my $sock;
\&
\& foreach my $ai ( @res ) {
\&    my $candidate = IO::Socket\->new();
\&
\&    $candidate\->socket( $ai\->{family}, $ai\->{socktype}, $ai\->{protocol} )
\&       or next;
\&
\&    $candidate\->connect( $ai\->{addr} )
\&       or next;
\&
\&    $sock = $candidate;
\&    last;
\& }
\&
\& if( $sock ) {
\&    my ( $err, $host, $service ) = getnameinfo( $sock\->peername );
\&    print "Connected to $host:$service\en" if !$err;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1RFC 2553\s0 functions \f(CW\*(C`getaddrinfo\*(C'\fR and \f(CW\*(C`getnameinfo\*(C'\fR provide an abstracted
way to convert between a pair of host name/service name and socket addresses,
or vice versa. \f(CW\*(C`getaddrinfo\*(C'\fR converts names into a set of arguments to pass
to the \f(CW\*(C`socket()\*(C'\fR and \f(CW\*(C`connect()\*(C'\fR syscalls, and \f(CW\*(C`getnameinfo\*(C'\fR converts a
socket address back into its host name/service name pair.
.PP
These functions provide a useful interface for performing either of these name
resolution operation, without having to deal with IPv4/IPv6 transparency, or
whether the underlying host can support IPv6 at all, or other such issues.
However, not all platforms can support the underlying calls at the C layer,
which means a dilema for authors wishing to write forward-compatible code.
Either to support these functions, and cause the code not to work on older
platforms, or stick to the older \*(L"legacy\*(R" resolvers such as
\&\f(CW\*(C`gethostbyname()\*(C'\fR, which means the code becomes more portable.
.PP
This module attempts to solve this problem, by detecting at compiletime
whether the underlying \s-1OS\s0 will support these functions. If it does not, the
module will use pure-perl emulations of the functions using the legacy
resolver functions instead. The emulations support the same interface as the
real functions, and behave as close as is resonably possible to emulate using
the legacy resolvers. See Socket::GetAddrInfo::Emul for details on the
limits of this emulation.
.PP
As of Perl version 5.14.0, Perl already supports \f(CW\*(C`getaddrinfo\*(C'\fR in core. On
such a system, this module simply uses the functions provided by \f(CW\*(C`Socket\*(C'\fR,
and does not need to use its own compiled \s-1XS,\s0 or pure-perl legacy emulation.
.PP
As \f(CW\*(C`Socket\*(C'\fR in core now provides all the functions also provided by this
module, it is likely this may be the last released version of this module. And
code currently using this module would be advised to switch to using core
\&\f(CW\*(C`Socket\*(C'\fR instead.
.SH "EXPORT TAGS"
.IX Header "EXPORT TAGS"
The following tags may be imported by \f(CW\*(C`use Socket::GetAddrInfo qw( :tag )\*(C'\fR:
.IP "\s-1AI\s0" 8
.IX Item "AI"
Imports all of the \f(CW\*(C`AI_*\*(C'\fR constants for \f(CW\*(C`getaddrinfo\*(C'\fR flags
.IP "\s-1NI\s0" 8
.IX Item "NI"
Imports all of the \f(CW\*(C`NI_*\*(C'\fR constants for \f(CW\*(C`getnameinfo\*(C'\fR flags
.IP "\s-1EAI\s0" 8
.IX Item "EAI"
Imports all of the \f(CW\*(C`EAI_*\*(C'\fR for error values
.IP "constants" 8
.IX Item "constants"
Imports all of the above constants
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "( $err, @res ) = getaddrinfo( $host, $service, $hints )"
.el .SS "( \f(CW$err\fP, \f(CW@res\fP ) = getaddrinfo( \f(CW$host\fP, \f(CW$service\fP, \f(CW$hints\fP )"
.IX Subsection "( $err, @res ) = getaddrinfo( $host, $service, $hints )"
\&\f(CW\*(C`getaddrinfo\*(C'\fR turns human-readable text strings (containing hostnames,
numeric addresses, service names, or port numbers) into sets of binary values
containing socket-level representations of these addresses.
.PP
When given both host and service, this function attempts to resolve the host
name to a set of network addresses, and the service name into a protocol and
port number, and then returns a list of address structures suitable to
\&\fBconnect()\fR to it.
.PP
When given just a host name, this function attempts to resolve it to a set of
network addresses, and then returns a list of these addresses in the returned
structures.
.PP
When given just a service name, this function attempts to resolve it to a
protocol and port number, and then returns a list of address structures that
represent it suitable to \fBbind()\fR to.
.PP
When given neither name, it generates an error.
.PP
The optional \f(CW$hints\fR parameter can be passed a \s-1HASH\s0 reference to indicate
how the results are generated. It may contain any of the following four
fields:
.IP "flags => \s-1INT\s0" 8
.IX Item "flags => INT"
A bitfield containing \f(CW\*(C`AI_*\*(C'\fR constants. At least the following flags will be
available:
.RS 8
.IP "\(bu" 2
\&\f(CW\*(C`AI_PASSIVE\*(C'\fR
.Sp
Indicates that this resolution is for a local \f(CW\*(C`bind()\*(C'\fR for a passive (i.e.
listening) socket, rather than an active (i.e. connecting) socket.
.IP "\(bu" 2
\&\f(CW\*(C`AI_CANONNAME\*(C'\fR
.Sp
Indicates that the caller wishes the canonical hostname (\f(CW\*(C`canonname\*(C'\fR) field
of the result to be filled in.
.IP "\(bu" 2
\&\f(CW\*(C`AI_NUMERICHOST\*(C'\fR
.Sp
Indicates that the caller will pass a numeric address, rather than a hostname,
and that \f(CW\*(C`getaddrinfo\*(C'\fR must not perform a resolve operation on this name.
This flag will prevent a possibly-slow network lookup operation, and instead
return an error, if a hostname is passed.
.RE
.RS 8
.Sp
Other flags may be provided by the \s-1OS.\s0
.RE
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
Restrict to only generating addresses in this address family
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
Restrict to only generating addresses of this socket type
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
Restrict to only generating addresses for this protocol
.PP
Errors are indicated by the \f(CW$err\fR value returned; which will be non-zero in
numeric context, and contain a string error message as a string. The value can
be compared against any of the \f(CW\*(C`EAI_*\*(C'\fR constants to determine what the error
is. Rather than explicitly checking, see also Socket::GetAddrInfo::Strict
which provides functions that throw exceptions on errors.
.PP
If no error occurs, \f(CW@res\fR will contain \s-1HASH\s0 references, each representing
one address. It will contain the following five fields:
.IP "family => \s-1INT\s0" 8
.IX Item "family => INT"
The address family (e.g. \s-1AF_INET\s0)
.IP "socktype => \s-1INT\s0" 8
.IX Item "socktype => INT"
The socket type (e.g. \s-1SOCK_STREAM\s0)
.IP "protocol => \s-1INT\s0" 8
.IX Item "protocol => INT"
The protocol (e.g. \s-1IPPROTO_TCP\s0)
.IP "addr => \s-1STRING\s0" 8
.IX Item "addr => STRING"
The address in a packed string (such as would be returned by pack_sockaddr_in)
.IP "canonname => \s-1STRING\s0" 8
.IX Item "canonname => STRING"
The canonical name for the host if the \f(CW\*(C`AI_CANONNAME\*(C'\fR flag was provided, or
\&\f(CW\*(C`undef\*(C'\fR otherwise. This field will only be present on the first returned
address.
.ie n .SS "( $err, $host, $service ) = getnameinfo( $addr, $flags, $xflags )"
.el .SS "( \f(CW$err\fP, \f(CW$host\fP, \f(CW$service\fP ) = getnameinfo( \f(CW$addr\fP, \f(CW$flags\fP, \f(CW$xflags\fP )"
.IX Subsection "( $err, $host, $service ) = getnameinfo( $addr, $flags, $xflags )"
\&\f(CW\*(C`getnameinfo\*(C'\fR turns a binary socket address into a pair of human-readable
strings, containing the host name, numeric address, service name, or port
number.
.PP
The optional \f(CW$flags\fR parameter is a bitfield containing \f(CW\*(C`NI_*\*(C'\fR constants.
At least the following flags will be available:
.IP "\(bu" 2
\&\f(CW\*(C`NI_NUMERICHOST\*(C'\fR
.Sp
Requests that a human-readable string representation of the numeric address is
returned directly, rather than performing a name resolve operation that may
convert it into a hostname.
.IP "\(bu" 2
\&\f(CW\*(C`NI_NUMERICSERV\*(C'\fR
.Sp
Requests that the port number be returned directly as a number representation
rather than performing a name resolve operation that may convert it into a
service name.
.IP "\(bu" 2
\&\f(CW\*(C`NI_NAMEREQD\*(C'\fR
.Sp
If a name resolve operation fails to provide a name, then this flag will cause
\&\f(CW\*(C`getnameinfo\*(C'\fR to indicate an error, rather than returning the numeric
representation as a human-readable string.
.IP "\(bu" 2
\&\f(CW\*(C`NI_DGRAM\*(C'\fR
.Sp
Indicates that the socket address relates to a \f(CW\*(C`SOCK_DGRAM\*(C'\fR socket, for the
services whose name differs between \f(CW\*(C`TCP\*(C'\fR and \f(CW\*(C`UDP\*(C'\fR protocols.
.PP
Other flags may be provided by the \s-1OS.\s0
.PP
The optional \f(CW$xflags\fR parameter is a bitfield containing \f(CW\*(C`NIx_*\*(C'\fR constants.
These are a Perl-level extension to the \s-1API,\s0 to indicate extra information.
.IP "\(bu" 2
\&\f(CW\*(C`NIx_NOHOST\*(C'\fR
.Sp
Indicates that the caller is not interested in the hostname of the result, so
it does not have to be converted; \f(CW\*(C`undef\*(C'\fR will be returned as the hostname.
.IP "\(bu" 2
\&\f(CW\*(C`NIx_NOSERV\*(C'\fR
.Sp
Indicates that the caller is not interested in the service name of the result,
so it does not have to be converted; \f(CW\*(C`undef\*(C'\fR will be returned as the service
name.
.PP
Errors are indicated by the \f(CW$err\fR value returned; which will be non-zero in
numeric context, and contain a string error message as a string. The value can
be compared against any of the \f(CW\*(C`EAI_*\*(C'\fR constants to determine what the error
is. Rather than explicitly checking, see also Socket::GetAddrInfo::Strict
which provides functions that throw exceptions on errors.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.ie n .SS "Lookup for ""connect"""
.el .SS "Lookup for \f(CWconnect\fP"
.IX Subsection "Lookup for connect"
The \f(CW\*(C`getaddrinfo\*(C'\fR function converts a hostname and a service name into a list
of structures, each containing a potential way to \f(CW\*(C`connect()\*(C'\fR to the named
service on the named host.
.PP
.Vb 3
\& my %hints = ( socktype => SOCK_STREAM );
\& my ( $err, @res ) = getaddrinfo( $hostname, $servicename, \e%hints );
\& die "Cannot getaddrinfo \- $err" if $err;
\&
\& my $sock;
\&
\& foreach my $ai ( @res ) {
\&    my $candidate = IO::Socket\->new();
\&
\&    $candidate\->socket( $ai\->{family}, $ai\->{socktype}, $ai\->{protocol} )
\&       or next;
\&
\&    $candidate\->connect( $ai\->{addr} )
\&       or next;
\&
\&    $sock = $candidate;
\&    last;
\& }
.Ve
.PP
Because a list of potential candidates is returned, the \f(CW\*(C`while\*(C'\fR loop tries
each in turn until it it finds one that succeeds both the \f(CW\*(C`socket()\*(C'\fR and
\&\f(CW\*(C`connect()\*(C'\fR calls.
.PP
This function performs the work of the legacy functions \f(CW\*(C`gethostbyname\*(C'\fR,
\&\f(CW\*(C`getservbyname\*(C'\fR, \f(CW\*(C`inet_aton\*(C'\fR and \f(CW\*(C`pack_sockaddr_in\*(C'\fR.
.SS "Making a human-readable string out of an address"
.IX Subsection "Making a human-readable string out of an address"
The \f(CW\*(C`getnameinfo\*(C'\fR function converts a socket address, such as returned by
\&\f(CW\*(C`getsockname\*(C'\fR or \f(CW\*(C`getpeername\*(C'\fR, into a pair of human-readable strings
representing the address and service name.
.PP
.Vb 2
\& my ( $err, $hostname, $servicename ) = getnameinfo( $socket\->peername );
\& die "Cannot getnameinfo \- $err" if $err;
\&
\& print "The peer is connected from $hostname\en";
.Ve
.PP
Since in this example only the hostname was used, the redundant conversion of
the port number into a service name may be omitted by passing the
\&\f(CW\*(C`NIx_NOSERV\*(C'\fR flag.
.PP
.Vb 1
\& my ( $err, $hostname ) = getnameinfo( $socket\->peername, 0, NIx_NOSERV );
.Ve
.PP
This function performs the work of the legacy functions \f(CW\*(C`unpack_sockaddr_in\*(C'\fR,
\&\f(CW\*(C`inet_ntoa\*(C'\fR, \f(CW\*(C`gethostbyaddr\*(C'\fR and \f(CW\*(C`getservbyport\*(C'\fR.
.SS "Resolving hostnames into \s-1IP\s0 addresses"
.IX Subsection "Resolving hostnames into IP addresses"
To turn a hostname into a human-readable plain \s-1IP\s0 address use \f(CW\*(C`getaddrinfo\*(C'\fR
to turn the hostname into a list of socket structures, then \f(CW\*(C`getnameinfo\*(C'\fR on
each one to make it a readable \s-1IP\s0 address again.
.PP
.Vb 2
\& my ( $err, @res ) = getaddrinfo( $hostname, "", { socktype => SOCK_RAW } );
\& die "Cannot getaddrinfo \- $err" if $err;
\&
\& while( my $ai = shift @res ) {
\&    my ( $err, $ipaddr ) = getnameinfo( $ai\->{addr}, NI_NUMERICHOST, NIx_NOSERV );
\&    die "Cannot getnameinfo \- $err" if $err;
\&
\&    print "$ipaddr\en";
\& }
.Ve
.PP
The \f(CW\*(C`socktype\*(C'\fR hint to \f(CW\*(C`getaddrinfo\*(C'\fR filters the results to only include one
socket type and protocol. Without this most OSes return three combinations,
for \f(CW\*(C`SOCK_STREAM\*(C'\fR, \f(CW\*(C`SOCK_DGRAM\*(C'\fR and \f(CW\*(C`SOCK_RAW\*(C'\fR, resulting in triplicate
output of addresses. The \f(CW\*(C`NI_NUMERICHOST\*(C'\fR flag to \f(CW\*(C`getnameinfo\*(C'\fR causes it to
return a string-formatted plain \s-1IP\s0 address, rather than reverse resolving it
back into a hostname.
.PP
This combination performs the work of the legacy functions \f(CW\*(C`gethostbyname\*(C'\fR
and \f(CW\*(C`inet_ntoa\*(C'\fR.
.SH "BUILDING WITHOUT XS CODE"
.IX Header "BUILDING WITHOUT XS CODE"
In some environments it may be preferred not to build the \s-1XS\s0 implementation,
leaving a choice only of the core or pure-perl emulation implementations.
.PP
.Vb 1
\& $ perl Build.PL \-\-pp
.Ve
.PP
or
.PP
.Vb 1
\& $ PERL_SOCKET_GETADDRINFO_NO_BUILD_XS=1 perl Build.PL
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 4
Appears to \s-1FAIL\s0 on older Darwin machines (e.g. \f(CW\*(C`osvers=8.11.1\*(C'\fR). The failure
mode occurs in \fIt/02getnameinfo.t\fR and appears to relate to an endian bug;
expecting to receive \f(CW80\fR and instead receiving \f(CW20480\fR (which is a 16\-bit
\&\f(CW80\fR byte-swapped).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
<http://tools.ietf.org/html/rfc2553> \- Basic Socket Interface Extensions for
IPv6
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Christian Hansen <chansen@cpan.org> \- for help with some \s-1XS\s0 features and Win32
build fixes.
.PP
Zefram <zefram@fysh.org> \- for help with fixing some bugs in the \s-1XS\s0 code.
.PP
Reini Urban <rurban@cpan.org> \- for help with older perls and more Win32
build fixes.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>