getaddrinfo

The getaddrinfo function retrieves address information that is ready to use for connecting to a service or for creating a socket that will accept connections.

Syntax


INT WSAAPI getaddrinfo(

  PCSTR pServiceName,

  PCSTR pHostName,

  CONST ADDRINFOA *pHints,

  PADDRINFOA *ppResult

);

For Unicode versions, use:


INT WSAAPI getaddrinfo(

  PCWSTR pServiceName,

  PCWSTR pHostName,

  CONST ADDRINFOW *pHints,

  PTRANS ADDRINFOW *ppResult

);

Parameters

Parameter	Description
pServiceName	A pointer to a null-terminated string that contains the name of the service. This parameter can be a service name or a port number.
pHostName	A pointer to a null-terminated string that contains the hostname or network address. If this parameter is NULL, the function returns address information for all interfaces on the local computer.
pHints	A pointer to an ADDRINFO structure that specifies constraints on the type of socket address to return. If this parameter is NULL, the function uses default values.
ppResult	A pointer to a pointer to an ADDRINFO structure that receives a linked list of ADDRINFO structures that contains address information for the specified host and service.

Return Value

On success, getaddrinfo returns zero. On failure, it returns a non-zero Winsock error code, such as WSASYSNOTREADY, WSAEINVAL, or WSAEFAULT.

Possible return values include:

0: Success.
WSASYSNOTREADY: The underlying network system is not ready to function.
WSAEINVAL: An invalid argument was passed to the function.
WSAEFAULT: The lpAddrInfoEx parameter is not a valid address.
EAI_NONAME: The name does not resolve.
EAI_SERVICE: The service is not known.

Remarks

The getaddrinfo function is the modern, recommended function for resolving hostnames and service names into socket address structures. It replaces older functions like gethostbyname and getservbyname.

This function supports both IPv4 and IPv6 addresses.

The pHints parameter can be used to specify preferences for the type of address to be returned, such as preferred address family (AF_INET or AF_INET6) or socket type (SOCK_STREAM or SOCK_DGRAM).

The result is returned as a linked list of ADDRINFO structures, allowing for multiple possible addresses or protocols to be returned.

Example


#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

#pragma comment(lib, "Ws2_32.lib")

int main() {
    WSADATA wsaData;
    ADDRINFOA hints, *result, *ptr;
    int iResult;

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("WSAStartup failed: %d\n", iResult);
        return 1;
    }

    ZeroMemory(&hints, sizeof(hints));
    hints.ai_family = AF_UNSPEC;     // Allow IPv4 or IPv6
    hints.ai_socktype = SOCK_STREAM; // TCP stream sockets
    hints.ai_protocol = IPPROTO_TCP; // TCP protocol

    // Resolve the server address and port
    iResult = getaddrinfo("www.example.com", "80", &hints, &result);
    if (iResult != 0) {
        printf("getaddrinfo failed: %d\n", iResult);
        WSACleanup();
        return 1;
    }

    printf("Successfully resolved www.example.com:80\n");

    // Iterate through the results and print address information
    for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {
        if (ptr->ai_family == AF_INET) {
            struct sockaddr_in *sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
            char ipstr[INET_ADDRSTRLEN];
            inet_ntop(AF_INET, &sockaddr_ipv4->sin_addr, ipstr, sizeof(ipstr));
            printf("  IPv4 Address: %s\n", ipstr);
        } else if (ptr->ai_family == AF_INET6) {
            struct sockaddr_in6 *sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
            char ipstr[INET6_ADDRSTRLEN];
            inet_ntop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstr, sizeof(ipstr));
            printf("  IPv6 Address: %s\n", ipstr);
        }
    }

    // Free the address information
    freeaddrinfo(result);
    WSACleanup();

    return 0;
}