getaddrinfo(3N) getaddrinfo(3N)
NAME
getaddrinfo(), getnameinfo(), freeaddrinfo(), gai_strerror() - get hostname and address entry
SYNOPSIS
DESCRIPTION
getaddrinfo()
Hostname-to-address translation is done in a protocol-independent fashion using the function.
The function returns an integer. The input arguments hostname and servname are pointers to null-terminated strings or NULL. One or both
of these two arguments must be a non-NULL pointer.
In the normal client scenario, both hostname and servname are specified. The non-NULL hostname string can be either a hostname or a
numeric host address string (a dotted-decimal IPv4 address or a hexadecimal IPv6 address). The non-NULL servname string can be either a
service name or a decimal port number. However, in the server scenario, only servname is specified.
The third input argument is a pointer to the structure of type defined as follows in
The members of this structure are:
The flag used to set the socket address structure for an IPv4 address
or an IPv6 address.
If the bit is then the returned socket address structure from the function will be used as an argument to the
function call. When this bit is set and the hostname argument to the function is a NULL pointer, then the IP
address portion of the socket address structure will be set to for an IPv4 address or for an IPv6 address.
If the is not set, then the returned socket address structure will be used as an argument to the or functions. In
this case, if the hostname argument is a NULL pointer, then the IP address portion of the socket address will be
set to address.
If the bit is set, then upon successful return, will return the member of the first structure, which is a NULL
terminated string containing the canonical name of the specified host.
If an flag is specified with an value of returns IPv4-mapped IPv6 addresses when it does not find any matching
IPv6 addresses. ignores an flag if the is not equal to
If an flag is used with an flag, returns all the matching IPv6 and IPv4 addresses. ignores an flag without an
flag.
If an flag is specified, then IPv4 addresses are returned only if an IPv4 address is configured in the local sys-
tem, and IPv6 addresses are returned only if an IPv6 address is configured in the local system. In this case, the
loopback address is not considered as a valid configured address.
The protocol family the caller will accept. If this member is set to
then the caller will accept any protocol family. If the caller handles only IPv4 stack and not IPv6 stack, then
the must be set to
The protocol the caller supports. If
is set to then the caller will accept any protocol.
The socket type the caller supports. If
is set to then the caller will accept any socket type. However, if the caller handles only TCP and not UDP, then
the must be set to
The length, in bytes, of the IPv4 or IPv6 address.
The canonical name of the host.
The binary address of the host.
The next structure in the linked list.
The above argument, is optional. If the caller wants to provide information such as the type of socket and protocol family that the caller
supports, the caller can specify them using the structure. When this information is passed to all the fields other than and must be set to
or a NULL pointer.
When returns successfully, holds a pointer to a linked list of one or more structures. The caller can process each structure in this list
by following the pointer, until a NULL pointer is encountered. In each of the returned structures, the three members and are used as argu-
ments to the function call. The member points to a socket address structure whose length is specified by the member.
Destination Address Selection
supports the Destination Address Selection algorithm defined in RFC 3484. This feature can be enabled by setting the ndd tunable, to See
ndd(1M) for information on setting a network tunable parameter. Upon enabling the feature, sorts the linked list of structures based on
the Destination Address Selection rules defined in RFC 3484. This sorting process ensures that the best possible addresses are at the
beginning of the list.
Return Value for getaddrinfo()
The return value from the function is upon success, or a nonzero error code.
The following are the nonzero error codes given by These are defined in
Address family for hostname not supported.
Temporary failure in name resolution.
Invalid value for
Non-recoverable failure in name resolution.
Argument buffer overflow
not supported.
Memory allocation failure.
No address associated with
hostname.
No hostname nor servname provided, or not known.
The servname is not supported for
not supported.
System error returned in errno.
freeaddrinfo()
All the information returned by is dynamically allocated: the structures, the socket address structures, and canonical host name strings
pointed to by the structures. To return this information to the system, the function is called:
The structure pointed to by the argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated
until a NULL pointer is encountered.
gai_strerror()
To aid applications in printing error messages based on the codes returned by the function is defined.
The argument is one of the values defined earlier, and the return value points to a string describing the error. If the argument is not
one of the values, the function still returns a pointer to a string whose contents indicate an unknown error.
getnameinfo()
The function is used to look up a hostname and service name, given the binary address and port. The function is defined as follows:
This function looks up an IP address and port number provided by the caller in the DNS and system-specific database, and returns text
strings for both in buffers provided by the caller.
The function indicates successful completion by a zero return value; a non-zero return value indicates failure.
If the address is IPv6 unspecified address ( :: ), then the following actions occur:
returns if the flag is set.
returns success, if the flag is not set.
The host argument contains the numeric form of the IPv6 address and does not perform a lookup for the IPv6 address.
The first argument, points to either a structure (for IPv4) or a structure (for IPv6) that holds the IP address and port number. The argu-
ment gives the length of the or structure.
The function returns the hostname associated with the IP address in the buffer pointed to by the argument. The caller provides the size of
this buffer via the argument. The service name associated with the port number is returned in the buffer pointed to by and the argument
gives the length of this buffer. The caller specifies not to return either string by providing zero values for the or arguments. Other-
wise, the caller must provide buffers large enough to hold the hostname and the service name, including the terminating null characters.
Unfortunately, most systems do not provide constants that specify the maximum size of either a fully-qualified domain name or a service
name. Therefore, to aid the application in allocating buffers for these two returned strings, the following constants are defined in
In recent versions of DNS/BIND, the first value is actually defined as the constant in the header file (Older versions of BIND define this
constant to be 256.)
The final argument to the function is a flag that changes the default actions of this function. By default, the fully-qualified domain
name (FQDN) for the host is looked up in the DNS and returned. If the flag bit is only the hostname portion of the FQDN is returned for
local hosts.
If the flag bit is or if the host's name cannot be located in the DNS, the numeric form of the host's address is returned instead of its
name (by calling instead of
If the flag bit is an error is returned if the host's name cannot be located in the DNS.
If the flag bit is the numeric form of the service address (port number) is returned instead of its name. The two flags are required to
support the flag that many commands provide.
A fifth flag bit, specifies that the service is a datagram service, and causes to be called with a second argument of "udp" instead of its
default of "tcp". This action is required for the few ports (512-514) that have different services for UDP and TCP.
These flags are defined in along with the flags already defined for
Name Service Switch-Based Operation
The and library routines internally call the name service switch to access the database lookup policy configured in the file (see nss-
witch.conf(4)) for the name/address resolution, and database lookup policy for the service/port resolution. The lookup policy defines the
order and criteria of the supported name services that can be used for resolution. If addresses are not gathered after contacting all the
directives, and if the caller has set the to or set to with an of use the directive in the file to resolve the hostname/address. In this
case, when the directive hostname/address resolution fails, the error number returned will be that of the error returned by the directive
lookup. The operations of these name services, Domain Name Server and Nonserver Modes, are described below: If the local system is config-
ured to use the BIND name server, (see named(1M) and resolver(4)) for name/address resolution, the function retrieves the host information
from the name server. The host names are matched irrespective of upper or lower case alphabets. For example, the domain names and match
the same entry in the name server database. When the directive is used for hostname/address resolution, a delay may be observed due to an
additional lookup using the sources specified for the directive.
Nonserver Operation
During a name/address resolution, if the database is configured for files resolution, and use the file for resolution. Similarly, if the
database is configured for files resolution, the file is used for resolution. If the file is used for name/address resolution, the method
used by the functions and to search an address is listed below:
Sequentially searches the
file until an address matching the src parameter is found or until the end of file is encountered.
Sequentially searches the
file until a host name (official name or an alias name) matching the name parameter is found or until the end of
file is encountered. The host names are matched irrespective of upper or lower case alphabets.
WARNINGS
Obsolescent Interfaces
The following interfaces are included to support existing applications and may be removed in future releases.
New applications must use the APIs and for name/address resolution.
Obsolescent Directive
The directive, which is used by the and APIs, may not be supported in future HP-UX releases. In order to minimize the impact to applica-
tions, HP recommends that you have the same configuration for the and the directives.
AUTHOR
was developed by HP.
FILES
SEE ALSO
ndd(1M), gethostent(3N), resolver(3N), nsswitch.conf(4).
getaddrinfo(3N)