getaddrinfo(3N)getaddrinfo(3N)NAMEgetaddrinfo(), getnameinfo(), freeaddrinfo(), gai_strerror() - get
hostname and address entry
SYNOPSISDESCRIPTIONgetaddrinfo()
Hostname-to-address translation is done in a protocol-independent fash‐
ion 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 speci‐
fied. The non-NULL hostname string can be either a hostname or a
numeric host address string (a dotted-decimal IPv4 address or a hexa‐
decimal IPv6 address). The non-NULL servname string can be either a
service name or a decimal port number. However, in the server sce‐
nario, 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 func‐
tion 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 con‐
figured in the local system, 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 fam‐
ily. 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 pro‐
tocol.
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 infor‐
mation 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 arguments 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 struc‐
tures, the socket address structures, and canonical host name strings
pointed to by the structures. To return this information to the sys‐
tem, 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 con‐
tents 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 struc‐
ture (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 num‐
ber) 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 configured
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 addi‐
tional 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 reso‐
lution. 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 encoun‐
tered. The host names are matched irrespec‐
tive 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)