Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > G


HP-UX 11i Version 3: February 2007

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index


getaddrinfo(), getnameinfo(), freeaddrinfo(), gai_strerror() — get hostname and address entry


#include <sys/socket.h> #include <netdb.h> int getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res); int getnameinfo(const struct sockaddr *sa, size_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags); _XOPEN_SOURCE_EXTENDED int getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host, socklen_t hostlen, char *serv, socklen_t servlen, int flags); void freeaddrinfo(struct addrinfo *ai); char *gai_strerror(int encode); _XOPEN_SOURCE_EXTENDED const char *gai_strerror(int encode);



Hostname-to-address translation is done in a protocol-independent fashion using the getaddrinfo() function.

The getaddrinfo() 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 addrinfo defined as follows in <netdb.h>:

struct addrinfo { int ai_flags; int ai_family; int ai_socktype; int ai_protocol; size_t ai_addrlen; char *ai_canonname; struct sockaddr *ai_addr; struct addrinfo *ai_next; };

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 AI_PASSIVE bit is set, then the returned socket address structure from the getaddrinfo() function will be used as an argument to the bind() function call. When this bit is set and the hostname argument to the getaddrinfo() function is a NULL pointer, then the IP address portion of the socket address structure will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address.

If the AI_PASSIVE is not set, then the returned socket address structure will be used as an argument to the connect(), sendto(), or sendmsg() 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 loopback address.

If the AI_CANONNAME bit is set, then upon successful return, getaddrinfo() will return the ai_canonname member of the first addrinfo structure, which is a NULL terminated string containing the canonical name of the specified host.

If an AI_V4MAPPED flag is specified with an ai_family value of AF_INET6, getaddrinfo() returns IPv4-mapped IPv6 addresses when it does not find any matching IPv6 addresses. getaddrinfo() ignores an AI_V4MAPPED flag if the ai_family is not equal to AF_INET6.

If an AI_ALL flag is used with an AI_V4MAPPED flag, getaddrinfo() returns all the matching IPv6 and IPv4 addresses. getaddrinfo() ignores an AI_ALL flag without an AI_V4MAPPED flag.

If an AI_ADDRCONFIG flag is specified, then IPv4 addresses are returned only if an IPv4 address is configured 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 PF_UNSPEC, then the caller will accept any protocol family. If the caller handles only IPv4 stack and not IPv6 stack, then the ai_family must be set to PF_INET.


The protocol the caller supports. If ai_protocol is set to 0, then the caller will accept any protocol.


The socket type the caller supports. If ai_socktype is set to 0, then the caller will accept any socket type. However, if the caller handles only TCP and not UDP, then the ai_socktype must be set to SOCK_STREAM.


The length, in bytes, of the IPv4 or IPv6 address.


The canonical name of the host.


The binary address of the host.


The next addrinfo 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 addrinfo structure. When this information is passed to getaddrinfo(), all the fields other then ai_flags, ai_family, ai_socktype, and ai_protocol must be set to zero or a NULL pointer.

When it returns successfully, **res holds a pointer to a linked list of one or more addrinfo structures. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a NULL pointer is encountered. In each of the returned addrinfo structures, the three members ai_family, ai_socktype, and ai_protocol are used as arguments to the socket() function call. The ai_addr member points to a socket address structure whose length is specified by the ai_addrlen member.

The return value from the getaddrinfo() function is 0 upon success, or a nonzero error code. The following are the nonzero error codes given by getaddrinfo(). These are defined in <netdb.h>:


Address family for hostname not supported.


Temporary failure in name resolution.


Invalid value for ai_flags.


Non-recoverable failure in name resolution.


Argument buffer overflow


ai_family not supported.


Memory allocation failure.


No address associated with hostname.


No hostname nor servname provided, or not known.


The servname is not supported for ai_socktype.


ai_socktype not supported.


System error returned in errno.


All the information returned by getaddrinfo() is dynamically allocated: the addrinfo structures, the socket address structures, and canonical host name strings pointed to by the addrinfo structures. To return this information to the system, the function freeaddrinfo() is called:

#include <sys/socket.h> #include <netdb.h> void freeaddrinfo(struct addrinfo *ai);

The addrinfo structure pointed to by the ai argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated until a NULL ai_next pointer is encountered.


To aid applications in printing error messages based on the EAI_xxx codes returned by getaddrinfo(), the gai_strerror function is defined.

#include <sys/socket.h> #include <netdb.h> const char *gai_strerror(int ecode);

The argument is one of the EAI_xxx values defined earlier, and the return value points to a string describing the error. If the argument is not one of the EAI_xxx values, the function still returns a pointer to a string whose contents indicate an unknown error.


The getnameinfo() function is used to look up a hostname and service name, given the binary address and port. The function is defined as follows:

#include <sys/socket.h> #include <netdb.h> int getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host, socklen_t hostlen, char *serv, socklen_t servlen, int flags);

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:

  • getnameinfo() returns EAI_NONAME, if the NI_NAMEREQD flag is set.

  • getnameinfo() returns success, if the NI_NAMEREQD flag is not set.

The host argument contains the numeric form of the IPv6 address and getnameinfo() does not perform a lookup for the IPv6 address.

The first argument, sa, points to either a sockaddr_in structure (for IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address and port number. The salen argument gives the length of the sockaddr_in or sockaddr_in6 structure.

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 associated 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 gethostbyaddr()).

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 getservbyport() to be called with a second argument of "udp" instead of its default of "tcp". This 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 getaddrinfo().

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 directives, 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 information 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 is used for name/address resolution, the method used by the functions getnameinfo() and getaddrinfo() to search an address is listed below:


Sequentially searches the /etc/hosts file until an address matching the src parameter is found or until the end of file is encountered.


Sequentially searches the /etc/hosts 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.


Obsolescent Interfaces

The following interfaces are included to support existing applications and may be removed in future releases.

struct hostent *getipnodebyname(const char *name, int af, int flags, int *error_num); int getipnodebyaddr(const void *src, size_t len, int af, int *error_num);

New applications must use the APIs getaddrinfo() and getnameinfo() for name/address resolution.

Obsolescent Directive

The ipnodes directive, which is used by the getaddrinfo() and getnameinfo() APIs, may not be supported in future HP-UX releases. In order to minimize the impact to applications, it is recommended that you have the same configuration for the hosts and the ipnodes directives.


getaddrinfo() was developed by HP.




Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.