Ubuntu Manpage: "Socket::GetAddrInfo" - address-family independent name resolving functions

Provided by: libsocket-getaddrinfo-perl_0.22-3_all

NAME

       "Socket::GetAddrInfo" - address-family independent name resolving functions

SYNOPSIS

        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", \%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\n" if !$err;
        }

DESCRIPTION

The RFC 2553 functions "getaddrinfo" and "getnameinfo" provide an abstracted way to
convert between a pair of host name/service name and socket addresses, or vice versa.
"getaddrinfo" converts names into a set of arguments to pass to the "socket()" and
"connect()" syscalls, and "getnameinfo" converts a socket address back into its host
name/service name pair.

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 "legacy" resolvers such as
"gethostbyname()", which means the code becomes more portable.

This module attempts to solve this problem, by detecting at compiletime whether the
underlying OS 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.

As of Perl version 5.14.0, Perl already supports "getaddrinfo" in core. On such a system,
this module simply uses the functions provided by "Socket", and does not need to use its
own compiled XS, or pure-perl legacy emulation.

As "Socket" 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 "Socket" instead.

EXPORT TAGS

       The following tags may be imported by "use Socket::GetAddrInfo qw( :tag )":

       AI      Imports all of the "AI_*" constants for "getaddrinfo" flags

       NI      Imports all of the "NI_*" constants for "getnameinfo" flags

       EAI     Imports all of the "EAI_*" for error values

       constants
               Imports all of the above constants

FUNCTIONS

( $err, @res ) = getaddrinfo( $host, $service, $hints )
"getaddrinfo" 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.

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 connect() to it.

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.

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
bind() to.

When given neither name, it generates an error.

The optional $hints parameter can be passed a HASH reference to indicate how the results
are generated. It may contain any of the following four fields:

flags => INT
A bitfield containing "AI_*" constants. At least the following flags will be
available:

• "AI_PASSIVE"

Indicates that this resolution is for a local "bind()" for a passive (i.e.
listening) socket, rather than an active (i.e. connecting) socket.

• "AI_CANONNAME"

Indicates that the caller wishes the canonical hostname ("canonname") field of
the result to be filled in.

• "AI_NUMERICHOST"

Indicates that the caller will pass a numeric address, rather than a hostname,
and that "getaddrinfo" 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.

Other flags may be provided by the OS.

family => INT
Restrict to only generating addresses in this address family

socktype => INT
Restrict to only generating addresses of this socket type

protocol => INT
Restrict to only generating addresses for this protocol

Errors are indicated by the $err 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 "EAI_*" constants to determine what the error is. Rather than explicitly
checking, see also Socket::GetAddrInfo::Strict which provides functions that throw
exceptions on errors.

If no error occurs, @res will contain HASH references, each representing one address. It
will contain the following five fields:

family => INT
The address family (e.g. AF_INET)

socktype => INT
The socket type (e.g. SOCK_STREAM)

protocol => INT
The protocol (e.g. IPPROTO_TCP)

addr => STRING
The address in a packed string (such as would be returned by pack_sockaddr_in)

canonname => STRING
The canonical name for the host if the "AI_CANONNAME" flag was provided, or
"undef" otherwise. This field will only be present on the first returned address.

( $err, $host, $service ) = getnameinfo( $addr, $flags, $xflags )
"getnameinfo" turns a binary socket address into a pair of human-readable strings,
containing the host name, numeric address, service name, or port number.

The optional $flags parameter is a bitfield containing "NI_*" constants. At least the
following flags will be available:

• "NI_NUMERICHOST"

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.

• "NI_NUMERICSERV"

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.

• "NI_NAMEREQD"

If a name resolve operation fails to provide a name, then this flag will cause
"getnameinfo" to indicate an error, rather than returning the numeric representation as
a human-readable string.

• "NI_DGRAM"

Indicates that the socket address relates to a "SOCK_DGRAM" socket, for the services
whose name differs between "TCP" and "UDP" protocols.

Other flags may be provided by the OS.

The optional $xflags parameter is a bitfield containing "NIx_*" constants. These are a
Perl-level extension to the API, to indicate extra information.

• "NIx_NOHOST"

Indicates that the caller is not interested in the hostname of the result, so it does
not have to be converted; "undef" will be returned as the hostname.

• "NIx_NOSERV"

Indicates that the caller is not interested in the service name of the result, so it
does not have to be converted; "undef" will be returned as the service name.

EXAMPLES

   Lookup for "connect"
       The "getaddrinfo" function converts a hostname and a service name into a list of
       structures, each containing a potential way to "connect()" to the named service on the
       named host.

        my %hints = ( socktype => SOCK_STREAM );
        my ( $err, @res ) = getaddrinfo( $hostname, $servicename, \%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;
        }

       Because a list of potential candidates is returned, the "while" loop tries each in turn
       until it it finds one that succeeds both the "socket()" and "connect()" calls.

       This function performs the work of the legacy functions "gethostbyname", "getservbyname",
       "inet_aton" and "pack_sockaddr_in".

   Making a human-readable string out of an address
       The "getnameinfo" function converts a socket address, such as returned by "getsockname" or
       "getpeername", into a pair of human-readable strings representing the address and service
       name.

        my ( $err, $hostname, $servicename ) = getnameinfo( $socket->peername );
        die "Cannot getnameinfo - $err" if $err;

        print "The peer is connected from $hostname\n";

       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 "NIx_NOSERV" flag.

        my ( $err, $hostname ) = getnameinfo( $socket->peername, 0, NIx_NOSERV );

       This function performs the work of the legacy functions "unpack_sockaddr_in", "inet_ntoa",
       "gethostbyaddr" and "getservbyport".

   Resolving hostnames into IP addresses
       To turn a hostname into a human-readable plain IP address use "getaddrinfo" to turn the
       hostname into a list of socket structures, then "getnameinfo" on each one to make it a
       readable IP address again.

        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\n";
        }

       The "socktype" hint to "getaddrinfo" filters the results to only include one socket type
       and protocol. Without this most OSes return three combinations, for "SOCK_STREAM",
       "SOCK_DGRAM" and "SOCK_RAW", resulting in triplicate output of addresses. The
       "NI_NUMERICHOST" flag to "getnameinfo" causes it to return a string-formatted plain IP
       address, rather than reverse resolving it back into a hostname.

       This combination performs the work of the legacy functions "gethostbyname" and
       "inet_ntoa".

BUILDING WITHOUT XS CODE

       In some environments it may be preferred not to build the XS implementation, leaving a
       choice only of the core or pure-perl emulation implementations.

        $ perl Build.PL --pp

       or

        $ PERL_SOCKET_GETADDRINFO_NO_BUILD_XS=1 perl Build.PL

BUGS

       •   Appears to FAIL on older Darwin machines (e.g. "osvers=8.11.1"). The failure mode
           occurs in t/02getnameinfo.t and appears to relate to an endian bug; expecting to
           receive 80 and instead receiving 20480 (which is a 16-bit 80 byte-swapped).

ACKNOWLEDGEMENTS

       Christian Hansen <chansen@cpan.org> - for help with some XS features and Win32 build
       fixes.

       Zefram <zefram@fysh.org> - for help with fixing some bugs in the XS code.

       Reini Urban <rurban@cpan.org> - for help with older perls and more Win32 build fixes.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>