Home / Windows / Win32 API / Winsock2 / getaddrinfo

getaddrinfo function

This topic describes the getaddrinfo function, which is part of the Windows Sockets API.

The getaddrinfo function is the modern, protocol-independent way to translate a host name and a service name into a dynamically allocated list of SOCKADDR structures that contain Internet Protocol (IP) addresses and port numbers for the specified host and service.

INT getaddrinfo( PCSTR pNodeName, PCSTR pServiceName, const ADDRINFOA *pHints, PADDRINFOA *ppResult );

Syntax

INT getaddrinfo(
  PCSTR  pNodeName,
  PCSTR  pServiceName,
  const ADDRINFOA *pHints,
  PADDRINFOA *ppResult
);

Parameters

Parameter Description
pNodeName A pointer to a null-terminated string that contains a host name or an IP address string. If NULL, then address information is returned for all interfaces on the local computer.
pServiceName A pointer to a null-terminated string that contains a port number or a service name. If NULL, then port information is not added to the address lookup.
pHints A pointer to an ADDRINFOA structure that specifies criteria for the returned address structures. If NULL, then no hints are provided.
ppResult A pointer to a pointer that receives a pointer to a linked list of ADDRINFOA structures that contain information about the host.

Return value

If the function succeeds, the return value is 0. If the function fails, the return value is a non-zero error code as defined in Winsock2.h.

Remarks

The getaddrinfo function is a powerful and flexible way to resolve network addresses. It supports both IPv4 and IPv6, and can resolve host names to IP addresses or IP addresses to host names.

The pHints parameter allows you to specify various options for the address lookup, such as the address family (IPv4 or IPv6), socket type, and protocol. For example, you can use hints.ai_family = AF_INET; to specifically request IPv4 addresses.

The returned ADDRINFOA structures are dynamically allocated and must be freed by calling the freeaddrinfo function when they are no longer needed.

Note

It is recommended to use the getaddrinfo function instead of the older gethostbyname function, as getaddrinfo is more versatile and supports IPv6.

Important

Ensure that the pNodeName and pServiceName parameters are valid and properly formatted. Incorrect input can lead to unexpected results or errors.

Example

// Include necessary headers
#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;
    }

    // Prepare hints structure
    ZeroMemory(&hints, sizeof(hints));
    hints.ai_family = AF_UNSPEC;     // Allow IPv4 or IPv6
    hints.ai_socktype = SOCK_STREAM; // TCP socket
    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;
    }

    // Iterate through the results and print addresses
    printf("Successfully resolved address(es) for www.example.com:\n");
    ptr = result;
    while(ptr != NULL) {
        char ipstr[INET6_ADDRSTRLEN];
        if (ptr->ai_family == AF_INET) {
            struct sockaddr_in *ipv4 = (struct sockaddr_in *)ptr->ai_addr;
            inet_ntop(AF_INET, &ipv4->sin_addr, ipstr, sizeof(ipstr));
        } else {
            struct sockaddr_in6 *ipv6 = (struct sockaddr_in6 *)ptr->ai_addr;
            inet_ntop(AF_INET6, &ipv6->sin6_addr, ipstr, sizeof(ipstr));
        }
        printf("  Address: %s\n", ipstr);
        ptr = ptr->ai_next;
    }

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

    // Clean up Winsock
    WSACleanup();

    return 0;
}

See also