Socket...ddrInfo(3pm)

📦
version 0.22 · 11 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

okay so this page is Socket...ddrInfo(3pm) from the User Contributed Perl Documentation set (yeah the header literally truncates the name, iykyk 💀), and the module it's all about is Socket::GetAddrInfo — address-family independent name resolving functions ✨

that's the whole vibe bestie. resolving names. no matter what address family you're in. slay 💅

🎀 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;
}

like, that's the whole plot. you ask for addresses, you try them one by one, you connect, and then you turn the connected address back into a cute lil host:service pair. periodt. 🦋

💜 DESCRIPTION 💜

so the RFC 2553 functions getaddrinfo and getnameinfo give you a whole abstracted way to convert between a pair of host name/service name and socket addresses, or the other way around. getaddrinfo converts names into a set of arguments you then pass to the socket() and connect() syscalls, and getnameinfo converts a socket address back into its host name/service name pair. it's giving bidirectional glow-up 💖

these functions are a genuinely useful interface for doing either of those name resolution operations, without you having to deal with IPv4/IPv6 transparency, or whether the underlying host can support IPv6 at all, or any of those other such issues. however — and this is the messy part — not all platforms can support the underlying calls at the C layer, which means a whole dilema for authors wishing to write forward-compatible code. either you support these functions and cause the code not to work on older platforms, or you stick to the older "legacy" resolvers such as gethostbyname(), which means the code becomes more portable. it's giving "pick your struggle" 😭

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 the details on the limits of this emulation — it's not magic, bestie, it's a fallback. 🫶

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. iconic behavior honestly. 👑

and since 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. so like… no cap, if you're still on this, it's giving vintage 💅

✨ 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

so basically pick your favorite or just take the whole bundle, no judgment 🎀

🔥 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. so like, words go in, binary socket addresses come out. the glow-up is real ✨

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. like, bestie, you have to give me something 💀

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. so it's the "don't you dare do a network call" flag, lowkey iconic 🛑
    • 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. so don't go looking for it on all of them, it's a first-born situation 💅

🌈 ( $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. it's the reverse glow-up of getaddrinfo — binary in, cute readable strings out 🦋

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. it's giving "name or nothing" 😤
  • 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. special little bonus features, we love to see it ✨

  • 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. 💖

✨ 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. It's giving matchmaking, honestly 💖

 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 one in turn until it finds one that succeeds both the socket() and connect() calls. Basically speed-dating for sockets, and bestie, only the one that passes both vibe checks gets to stay 🫶

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. Translating robot-speak into people-speak, iconic behaviour ✨

 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. No cap, why do extra work when you don't have to 💅

 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. Two-step glow-up 💖

 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. Not the triple-text energy we're going for, bestie 😭 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. Sometimes you just want the low-key version, and that's valid 🌸

 $ 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).
Okay so this one is genuinely cursed 🙈 an endian bug just flipping your numbers around for no reason. If you're on an old Darwin machine, just know it's not you, it's the bytes.

👀 SEE ALSO

🫶 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>

and that's the whole page, bestie 💜 you read every last bit, which is honestly main character energy. go forth and resolve some addresses, you absolute icon 👑

this was perl v5.40.0, dated 2025-02-01 — the Socket...ddrInfo(3pm) page from the User Contributed Perl Documentation, and yes that truncated title is just how it's spelled, no notes 💅

mwah, go slay 🎀✨

📦 where this page comes from