Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Socket::GetAddrInfo(3)User Contributed Perl DocumentatioSocket::GetAddrInfo(3)

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:

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

	       o "AI_CANONNAME"

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

	       o "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:

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

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

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

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

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

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

	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
       o   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).

SEE ALSO
       o   <http://tools.ietf.org/html/rfc2553>	- Basic	Socket Interface
	   Extensions for IPv6

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>

perl v5.24.1			  2017-07-02		Socket::GetAddrInfo(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORT TAGS | FUNCTIONS | EXAMPLES | BUILDING WITHOUT XS CODE | BUGS | SEE ALSO | ACKNOWLEDGEMENTS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Socket::GetAddrInfo&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help