getaddrinfo

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function provides protocol-independent translation from host name to address.

Syntax

int getaddrinfo(
  const char FAR* nodename,
  const char FAR* servname,
  const struct addrinfo FAR* hints,
  struct addrinfo FAR* FAR* res
);

Parameters

nodename
[in] Pointer to a NULL-terminated string containing a host (node) name or a numeric host address string. The numeric host address string is a dotted-decimal IPv4 address or an IPv6 hexadecimal address.

servname
[in] Pointer to a NULL-terminated string containing either a service name or port number.

hints
[in] Pointer to an addrinfo structure that provides hints about the type of socket the caller supports.

res
[out] Pointer to a linked list of one or more addrinfo structures containing response information about the host.

Return Value

This function returns zero when successful. The return of a nonzero Windows Sockets error code indicates failure.

Nonzero error codes returned by this function also map to the set of errors outlined by IETF recommendations. The following table shows these error codes and their WSA* equivalents. The following table shows the WSA* error codes. It is recommended that these WSA* error codes be used, as they offer familiar and comprehensive error information for Windows Sockets programmers.

Error code	WSA* equivalent	Description
EAI_AGAIN	WSATRY_AGAIN	Temporary failure in name resolution.
EAI_BADFLAGS	WSAEINVAL	Invalid value for ai_flags.
EAI_FAIL	WSANO_RECOVERY	Nonrecoverable failure in name resolution.
EAI_FAMILY	WSAEAFNOSUPPORT	The ai_family member is not supported.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Memory allocation failure.
EAI_NODATA	WSANO_DATA	No address associated with nodename.
EAI_NONAME	WSAHOST_NOT_FOUND	Neither nodename nor servname provided, or not known.
EAI_SERVICE	WSATYPE_NOT_FOUND	The servname parameter is not supported for ai_socktype.

Remarks

One or both of the nodename or servname parameters must point to a NULL-terminated string; generally both are provided.

The maximum number of addresses returned when trying to resolve a name is 15.

Upon success, a linked list of addrinfo structures is returned in the res parameter; the list can be processed by following the pointer provided in the ai_next member of each returned addrinfo structure until a NULL pointer is encountered. In each returned addrinfo structure, the ai_family, ai_socktype, and ai_protocol members correspond to respective arguments in a socket (Windows Sockets) function call. Also, the ai_addr member in each returned addrinfo structure points to a filled-in socket address structure, the length of which is specified in its ai_addrlen member.

Callers of the getaddrinfo function can provide hints about the type of socket supported through an addrinfo structure pointed to by the hints parameter. When the hints parameter is used, rules apply to its associated addrinfo structure. The following list shows the rules that apply:

A value of PF_UNSPEC for ai_family indicates the caller will accept any protocol family.
A value of zero for ai_socktype indicates the caller will accept any socket type.
A value of zero for ai_protocol indicates the caller will accept any protocol.
ai_addrlen must be zero or a NULL pointer
ai_canonname must be zero or a NULL pointer
ai_addr must be zero or a NULL pointer
ai_next must be zero or a NULL pointer

Other values in the addrinfo structure provided in the hints parameter indicate specific requirements. For example, if the caller handles only TCP and does not handle UDP, the ai_socktype member should be set to SOCK_STREAM. For another example, If the caller handles only IPv4 and does not handle IPv6, the ai_family member should be set to PF_INET.

If the hints parameter is a NULL pointer, the getaddrinfo function treats it as if the addrinfo structure in hints were initialized with its ai_family member set to PF_UNSPEC and all other members set to zero.

Use of ai_flags in the hints parameter

The following table shows flags in the ai_flags member of the optional addrinfo structure provided in the hints parameter.

Flag	Description
AI_PASSIVE	If set, this flag indicates the caller intends to use the returned socket address structure in a call to the bind (Windows Sockets) function. If this flag is set and nodename is a NULL pointer, the IP address portion of the of the socket address structure is set to INADDR_ANY for IPv4 addresses and IN6ADDR_ANY_INIT for IPv6 addresses. If this flag is not set, the returned socket address structure is ready for a call to the connect (Windows Sockets) function for a connection-oriented protocol, or ready for a call to either the connect (Windows Sockets), sendto, or send functions for a connectionless protocol. If the nodename parameter is a NULL pointer in this case, the IP address portion of the socket address structure is set to the loopback address.
AI_CANONNAME	If this flag is set and the getaddrinfo function returns success, the ai_canonname member in the hints parameter points to a NULL-terminated string that contains the canonical name of the specified node. > [!NOTE] > The gettaddrinfo function can return success when the AI_CANNONNAME flag is set, yet the ai_canonname member in the associated addrinfo structure is NULL. Therefore, the recommended use of the AI_CANONNAME flag includes testing whether the ai_canonname member in the associated addrinfo structure is NULL.
AI_NUMERICHOST	If this flag is set, the nodename parameter must contain a non-NULL numeric host address string, otherwise the EAI_NONAME error is returned. This prevents a name resolution service from being called; all information returned by the getaddrinfo function is dynamically allocated.

AI_PASSIVE

If set, this flag indicates the caller intends to use the returned socket address structure in a call to the bind (Windows Sockets) function. If this flag is set and nodename is a NULL pointer, the IP address portion of the of the socket address structure is set to INADDR_ANY for IPv4 addresses and IN6ADDR_ANY_INIT for IPv6 addresses.

If this flag is not set, the returned socket address structure is ready for a call to the connect (Windows Sockets) function for a connection-oriented protocol, or ready for a call to either the connect (Windows Sockets), sendto, or send functions for a connectionless protocol. If the nodename parameter is a NULL pointer in this case, the IP address portion of the socket address structure is set to the loopback address.

AI_CANONNAME

If this flag is set and the getaddrinfo function returns success, the ai_canonname member in the hints parameter points to a NULL-terminated string that contains the canonical name of the specified node.

> [!NOTE] > The gettaddrinfo function can return success when the AI_CANNONNAME flag is set, yet the ai_canonname member in the associated addrinfo structure is NULL. Therefore, the recommended use of the AI_CANONNAME flag includes testing whether the ai_canonname member in the associated addrinfo structure is NULL.

AI_NUMERICHOST

If this flag is set, the nodename parameter must contain a non-NULL numeric host address string, otherwise the EAI_NONAME error is returned. This prevents a name resolution service from being called; all information returned by the getaddrinfo function is dynamically allocated.

If neither AI_CANONNAME nor AI_NUMERICHOST is used, the getaddrinfo function attempts resolution. If a literal string is passed getaddrinfo attempts to convert the string, and if a host name is passed the getaddrinfo function attempts to resolve it.

Freeing Address Information from Dynamic Allocation

All information returned by the getaddrinfo function is dynamically allocated, including all addrinfo structures, socket address structures, and canonical host name strings pointed to by addrinfo structures. To return that information to the system, call the freeaddrinfo function.

Requirements

Header	ws2tcpip.h
Library	Ws2.lib
Windows Embedded CE	Windows CE .NET 4.1 and later
Windows Mobile	Windows Mobile Version 5.0 and later

Share via