This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for

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


int getaddrinfo(
  const char FAR* 
  const char FAR* 
  const struct addrinfo FAR* 
  struct addrinfo FAR* FAR* 



[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.


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


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


[out] Pointer to a linked list of one or more addrinfostructures 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



Temporary failure in name resolution.



Invalid value for ai_flags.



Nonrecoverable failure in name resolution.



The ai_familymember is not supported.



Memory allocation failure.



No address associated with nodename.



Neither nodenamenor servnameprovided, or not known.



The servnameparameter is not supported for ai_socktype.


One or both of the nodenameor servnameparameters 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 addrinfostructures is returned in the resparameter; the list can be processed by following the pointer provided in the ai_nextmember of each returned addrinfostructure until a NULL pointer is encountered. In each returned addrinfostructure, the ai_family, ai_socktype, and ai_protocolmembers correspond to respective arguments in a socket (Windows Sockets)function call. Also, the ai_addrmember in each returned addrinfostructure points to a filled-in socket address structure, the length of which is specified in its ai_addrlenmember.

Callers of the getaddrinfofunction can provide hints about the type of socket supported through an addrinfostructure pointed to by the hintsparameter. When the hintsparameter is used, rules apply to its associated addrinfostructure. The following list shows the rules that apply:

  • A value of PF_UNSPEC for ai_familyindicates the caller will accept any protocol family.

  • A value of zero for ai_socktypeindicates the caller will accept any socket type.

  • A value of zero for ai_protocolindicates the caller will accept any protocol.

  • ai_addrlenmust be zero or a NULL pointer

  • ai_canonnamemust be zero or a NULL pointer

  • ai_addrmust be zero or a NULL pointer

  • ai_nextmust be zero or a NULL pointer

Other values in the addrinfostructure provided in the hintsparameter indicate specific requirements. For example, if the caller handles only TCP and does not handle UDP, the ai_socktypemember should be set to SOCK_STREAM. For another example, If the caller handles only IPv4 and does not handle IPv6, the ai_familymember should be set to PF_INET.

If the hintsparameter is a NULL pointer, the getaddrinfofunction treats it as if the addrinfostructure in hintswere initialized with its ai_familymember 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_flagsmember of the optional addrinfostructure provided in the hintsparameter.

Flag Description


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 nodenameis 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 sendfunctions for a connectionless protocol. If the nodenameparameter is a NULL pointer in this case, the IP address portion of the socket address structure is set to the loopback address.


If this flag is set and the getaddrinfofunction returns success, the ai_canonnamemember in the hintsparameter points to a NULL-terminated string that contains the canonical name of the specified node.

The gettaddrinfofunction can return success when the AI_CANNONNAME flag is set, yet the ai_canonnamemember in the associated addrinfostructure is NULL. Therefore, the recommended use of the AI_CANONNAME flag includes testing whether the ai_canonnamemember in the associated addrinfostructure is NULL.


If this flag is set, the nodenameparameter 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 getaddrinfofunction is dynamically allocated.

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

Freeing Address Information from Dynamic Allocation

All information returned by the getaddrinfofunction is dynamically allocated, including all addrinfostructures, socket address structures, and canonical host name strings pointed to by addrinfostructures. To return that information to the system, call the freeaddrinfofunction.


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

See Also