getaddrinfo.3n (2010 09)

g
getaddrinfo(3N) getaddrinfo(3N)
The function returns the hostname associated with the IP address in the buffer pointed to by the
host
argument. The caller provides the size of this buffer via the
hostlen argument. The service name asso-
ciated with the port number is returned in the buffer pointed to by
serv, and the servlen argument
gives the length of this buffer. The caller specifies not to return either string by providing zero values for
the
hostlen or servlen arguments. Otherwise, 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
<netdb.h>:
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
In recent versions of DNS/BIND, the first value
NI_MAXHOST is actually defined as the constant
MAXDNAME in the header file <arpa/nameser.h>
. (Older versions of BIND define this constant to be
256.)
The final argument to the
getnameinfo()
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
NI_NOFQDN is
set, only the hostname portion of the FQDN is returned for local
hosts.
If the flag bit
NI_NUMERICHOST
is set, 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
inet_ntop() instead of gethost-
byaddr()).
If the flag bit
NI_NAMEREQD is set, an error is returned if the host’s name cannot be located in the
DNS.
If the flag bit
NI_NUMERICSERV
is set, the numeric form of the service address (port number) is
returned instead of its name. The two
NI_NUMERICxxx flags are required to support the -n
flag that
many commands provide.
A fifth flag bit,
NI_DGRAM, specifies that the service is a datagram service, and causes
get-
servbyport() 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
NI_xxx flags are defined in <netdb.h> along with the AI_xxx flags already defined for
getad-
drinfo().
Name Service Switch-Based Operation
The
getnameinfo() and getaddrinfo()
library routines internally call the name service switch to
access the
ipnodes database lookup policy configured in the /etc/nsswitch.conf
file (see
nsswitch.conf(4)) for the name/address resolution, and
services 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
ipnodes
direc-
tives, and if the caller has set the
ai_family to AF_INET or set ai_flags to AI_V4MAPPED with an
ai_family of AF_INET6, getaddrinfo()/getnameinfo() use the hosts
directive in the
/etc/nsswitch.conf file to resolve the hostname/address. In this case, when the
hosts directive
hostname/address resolution fails, the error number returned will be that of the error returned by the
hosts directive lookup. The operations of these name services, Domain Name Server and Nonserver
Modes, are described below:
Domain Name Server Operation
If the local system is configured to use the BIND name server,
named (see named (1M) and resolver (4))
for name/address resolution, the function getnameinfo()/getaddrinfo()
retrieves the host infor-
mation from the name server. The host names are matched irrespective of upper or lower case alphabets.
For example, the domain names
berkeley.edu, Berkeley.EDU, and BERKELEY.EDU match the
same entry berkeley.edu in the name server database. When the hosts directive is used for
hostname/address resolution, a delay may be observed due to an additional lookup using the sources
specified for the hosts directive.
Nonserver Operation
During a name/address resolution, if the database is configured for files resolution,
getnameinfo()
and getaddrinfo() use the /etc/hosts file for resolution. Similarly, if the services database is
configured for files resolution, the /etc/services file is used for resolution. If the /etc/hosts file
4 Hewlett-Packard Company − 4 − HP-UX 11i Version 3: September 2010