Protocol-independent hostname-to-address translation.
Library (libc.a)
#include <sys/socket.h> #include <netdb.h> int getaddrinfo (hostname, servname, hints, res) const char *hostname; const char *servname; const struct addrinfo *hints; struct addrinfo **res;
The hostname and servname parameters describe the hostname and/or service name to be referenced. Zero or one of these arguments may be NULL. A non-NULL hostname may be either a hostname or a numeric host address string (a dotted-decimal for IPv4 or hex for IPv6). A non-NULL servname may be either a service name or a decimal port number.
The hints parameter specifies hints concerning the desired return information. The hostname and servname parameters are pointers to null-terminated strings or NULL. One or both of these arguments must be a non-NULL pointer. In a normal client scenario, both the hostname and servname parameters are specified. In the normal server scenario, only the servname parameter is specified. A non-NULL hostname string can be either a host name or a numeric host address string (for example, a dotted-decimal IPv4 address or an IPv6 hex address). A non-NULL servname string can be either a service name or a decimal port number.
The caller can optionally pass an addrinfo structure, pointed to by the hints parameter, to provide hints concerning the type of socket that the caller supports. In this hints structure, all members other than ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a NULL pointer. A value of PF_UNSPEC for ai_family means the caller will accept any protocol family. A value of zero for ai_socktype means the caller will accept any socket type. A value of zero for ai_protocol means the caller will accept any protocol. For example, if the caller handles only TCP and not UDP, the ai_socktype member of the hints structure should be set to SOCK_STREAM when the getaddrinfo subroutine is called. If the caller handles only IPv4 and not IPv6, the ai_family member of the hints structure should be set to PF_INET when getaddrinfo is called. If the hints parameter in getaddrinfo is a NULL pointer, it is the same as if the caller fills in an addrinfo structure initialized to zero with ai_family set to PF_UNSPEC.
Upon successful return, a pointer to a linked list of one or more addrinfo structures is returned through the res parameter. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a NULL pointer is encountered. In each returned addrinfo structure the three members ai_family, ai_socktype, and ai_protocol are the corresponding arguments for a call to the socket subroutine. In each addrinfo structure, the ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.
If the AI_PASSIVE bit is set in the ai_flags member of the hints structure, the caller plans to use the returned socket address structure in a call to the bind subroutine. If the hostname parameter is a NULL pointer, 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 bit is not set in the ai_flags member of the hints structure, the returned socket address structure will be ready for a call to the connect subroutine (for a connection-oriented protocol) or the connect, sendto, or sendmsg subroutine (for a connectionless protocol). If the hostname parameter is a NULL pointer, the IP address portion of the socket address structure will be set to the loopback address.
If the AI_CANONNAME bit is set in the ai_flags member of the hints structure, upon successful return the ai_canonname member of the first addrinfo structure in the linked list will point to a NULL-terminated string containing the canonical name of the specified hostname.
If the AI_NUMERICHOST flag is specified, a non-NULL nodename string supplied is a numeric host address string. Otherwise, an (EAI_NONAME) error is returned. This flag prevents any type of name resolution service (such as, DNS) from being invoked.
If the AI_NUMERICSERV flag is specified, a non-NULL servname string supplied is a numeric port string. Otherwise, an (EAI_NONAME) error is returned. This flag prevents any type of name resolution service (such as, NIS+) from being invoked.
If the AI_V4MAPPED flag is specified along with an ai_family value of AF_INET6, the getaddrinfo subroutine returns IPv4-mapped IPv6 addresses when no matching IPv6 addresses (ai_addrlen is 16) are found. For example, when using DNS, if no AAAA or A6 records are found, a query is made for A records. Any found are returned as IPv4-mapped IPv6 addresses. The AI_V4MAPPED flag is ignored unless ai_family equals AF_INET6.
If the AI_ALL flag is used with the AI_V4MAPPED flag, the getaddrinfo subroutine returns all matching IPv6 and IPv4 addresses. For example, when using DNS, a query is first made for AAAA/A6 records. If successful, those IPv6 addresses are returned. Another query is made for A records, and any IPv4 addresses found are returned as IPv4-mapped IPv6 addresses. The AI_ALL flag without the AI_V4MAPPED flag is ignored.
If the AI_ADDRCONFIG flag is specified, a query for AAAA or A6 records should occur only if the node has at least one IPv6 source address configured. A query for A records should occur only if the node has at least one IPv4 source address configured. The loopback address is not considered valid as a configured source address.
All of the information returned by the getaddrinfo subroutine 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, freeaddrinfo Subroutine is called.
The addrinfo structure is defined as:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IP=PROTO_xxx for IPv4 and IPv6 */
size_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canoncial name for hostname */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
}
If the query is successful, a pointer to a linked list of one or more addrinfo structures is returned via the res parameter. A zero return value indicates success. If the query fails, a non-zero error code will be returned.
The following names are the non-zero error codes. See netdb.h for further definition.
| EAI_ADDRFAMILY | Address family for hostname not supported |
| EAI_AGAIN | Temporary failure in name resolution |
| EAI_BADFLAGS | Invalid value for ai_flags |
| EAI_FAIL | Non-recoverable failure in name resolution |
| EAI_FAMILY | ai_family not supported |
| EAI_MEMORY | Memory allocation failure |
| EAI_NODATA | No address associated with hostname |
| EAI_NONAME | No hostname nor servname provided, or not known |
| EAI_SERVICE | servname not supported for ai_socktype |
| EAI_SOCKTYPE | ai_socktype not supported |
| EAI_SYSTEM | System error returned in errno |
freeaddrinfo Subroutine, and getnameinfo Subroutine.
The gai_strerror Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 1.