( $err, @res ) = getaddrinfo( $host, $service, $hints )

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:

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 )

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.

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.

Lookup for "connect"

 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

 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

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