When using an addrinfo structure as the hints argument (input), only four fields are meaningful. All other fields must be set to 0 or NULL.

Basic hints Setup Pattern

struct addrinfo hints;

memset(&hints, 0, sizeof(hints));  /* Zero EVERYTHING first */
hints.ai_family   = AF_UNSPEC;     /* Accept IPv4 or IPv6 */
hints.ai_socktype = SOCK_STREAM;   /* TCP only */
/* hints.ai_protocol = 0; already zero from memset */
/* hints.ai_flags   = 0; already zero — no special flags */

This field tells getaddrinfo() which IP version’s addresses you want in the results.

/* Example: Get only IPv6 addresses */
memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_INET6;
hints.ai_socktype = SOCK_STREAM;

err = getaddrinfo("www.example.com", "https", &hints, &result);
/* result will only contain AF_INET6 entries */

This field filters results by socket type. If you don’t set it (leave as 0), you may get both SOCK_STREAM and SOCK_DGRAM entries for the same address.

The ai_flags field is formed by ORing together one or more of these constants. Each flag modifies the behaviour of getaddrinfo() in a specific way.

/* Server setup with AI_PASSIVE */
struct addrinfo hints, *result;

memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags    = AI_PASSIVE;    /* We are a server */

/* Pass NULL for host — AI_PASSIVE fills in wildcard address */
err = getaddrinfo(NULL, "8080", &hints, &result);
if (err != 0) { /* handle error */ }

/* result->ai_addr will contain INADDR_ANY:8080 (0.0.0.0:8080) */
/* Ready to use with bind() */
int sfd = socket(result->ai_family, result->ai_socktype, result->ai_protocol);
bind(sfd, result->ai_addr, result->ai_addrlen);
listen(sfd, 10);

struct addrinfo hints, *result;

memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags    = AI_CANONNAME;   /* Request canonical name */

err = getaddrinfo("www.example.com", "http", &hints, &result);

/* Canonical name is in the FIRST node only */
if (result != NULL && result->ai_canonname != NULL) {
    printf("Canonical name: %s\n", result->ai_canonname);
}
/* All subsequent nodes (result->ai_next etc.) have ai_canonname = NULL */

memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags    = AI_NUMERICHOST;  /* No DNS lookup — host must be numeric */

/* This works: "192.168.1.1" is a valid numeric IPv4 address */
err = getaddrinfo("192.168.1.1", "80", &hints, &result);

/* This FAILS (returns EAI_NONAME): "www.example.com" is not numeric */
err = getaddrinfo("www.example.com", "80", &hints, &result);
/* err == EAI_NONAME */

memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags    = AI_NUMERICSERV;  /* service must be numeric port string */

/* Works: "443" is a valid port number */
err = getaddrinfo("www.example.com", "443", &hints, &result);

/* Fails: "https" is a service name, not a number */
err = getaddrinfo("www.example.com", "https", &hints, &result);

hints.ai_flags = AI_ADDRCONFIG;
/* On a machine with only IPv4: result will NOT include IPv6 entries */
/* On a dual-stack machine: result includes both IPv4 and IPv6 entries */

/* Request IPv6 results, fall back to IPv4-mapped if no IPv6 found */
memset(&hints, 0, sizeof(hints));
hints.ai_family   = AF_INET6;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags    = AI_V4MAPPED;

err = getaddrinfo("ipv4only.example.com", "http", &hints, &result);
/* Even if the host has no IPv6, result will contain ::ffff:x.x.x.x */

You can pass NULL for either host or service, but not both.

Complete Server Example Using AI_PASSIVE

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/socket.h>
#include <netdb.h>

#define PORT "9000"
#define BACKLOG 10

int main() {
    struct addrinfo hints, *result, *rp;
    int listenfd, err;
    int optval = 1;

    memset(&hints, 0, sizeof(hints));
    hints.ai_family   = AF_UNSPEC;   /* Support IPv4 and IPv6 */
    hints.ai_socktype = SOCK_STREAM; /* TCP */
    hints.ai_flags    = AI_PASSIVE;  /* We are a server — wildcard bind */

    err = getaddrinfo(NULL, PORT, &hints, &result);
    if (err != 0) {
        fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(err));
        exit(EXIT_FAILURE);
    }

    /* Try each result — bind to the first one that works */
    for (rp = result; rp != NULL; rp = rp->ai_next) {
        listenfd = socket(rp->ai_family, rp->ai_socktype, rp->ai_protocol);
        if (listenfd == -1) continue;

        /* Allow reuse of port (avoids "address already in use" after restart) */
        setsockopt(listenfd, SOL_SOCKET, SO_REUSEADDR, &optval, sizeof(optval));

        if (bind(listenfd, rp->ai_addr, rp->ai_addrlen) == 0)
            break;  /* bind succeeded */

        close(listenfd);
    }

    freeaddrinfo(result);

    if (rp == NULL) {
        fprintf(stderr, "Could not bind to port %s\n", PORT);
        exit(EXIT_FAILURE);
    }

    listen(listenfd, BACKLOG);
    printf("Server listening on port %s...\n", PORT);

    /* Accept loop would go here */
    close(listenfd);
    return 0;
}

Multiple AI_* flags are combined using bitwise OR (|).

/* Dual-stack client: configured types + V4MAPPED fallback */
hints.ai_family = AF_INET6;
hints.ai_flags  = AI_ADDRCONFIG | AI_V4MAPPED;
/* On IPv6-capable system: get native IPv6 + IPv4-mapped addresses */
/* On IPv4-only system: get IPv4-mapped addresses */

Q1. What is the purpose of the AI_PASSIVE flag?

Answer: AI_PASSIVE tells getaddrinfo() to return socket address structures suitable for a server (passive) socket — one that will call bind() and listen(). When this flag is set and host is NULL, the IP address in the returned structures is the wildcard address (0.0.0.0 for IPv4 or :: for IPv6), which means the socket will accept connections on all network interfaces. Without AI_PASSIVE, NULL host returns the loopback address instead.

Q2. What is the difference between AI_NUMERICHOST and AI_NUMERICSERV?

Answer: AI_NUMERICHOST forces the host argument to be interpreted as a numeric IP address string (IPv4 dotted decimal or IPv6 hex notation) — no DNS lookup is performed. AI_NUMERICSERV forces the service argument to be interpreted as a decimal port number string — no /etc/services lookup is performed. Both flags skip name resolution, which is faster and avoids potential DNS timeouts.

Q3. What does AI_ADDRCONFIG do and when would you use it?

Answer: AI_ADDRCONFIG filters the returned addresses so that only address types that the local system has configured (excluding loopback) are included. If the machine has no IPv6 address, IPv6 results are filtered out even if the server has an IPv6 address. This is useful in client programs on machines with limited connectivity — it prevents getting back IPv6 addresses that cannot actually be reached.

Q4. What is an IPv4-mapped IPv6 address and how does AI_V4MAPPED use it?

Answer: An IPv4-mapped IPv6 address encodes an IPv4 address inside an IPv6 address structure, using the format ::ffff:x.x.x.x (80 zeros, then 16 ones, then the 32-bit IPv4 address). AI_V4MAPPED is used when hints.ai_family = AF_INET6 and the host has no IPv6 address — it tells getaddrinfo() to return the host’s IPv4 address converted to mapped format instead of failing. This allows IPv6-only code to communicate with IPv4-only hosts.

Q5. What happens if hints.ai_socktype is set to 0?

Answer: When ai_socktype is 0 in hints, getaddrinfo() returns entries for any socket type — typically both SOCK_STREAM (TCP) and SOCK_DGRAM (UDP). If the service is available on both protocols, you get two entries per IP address: one for TCP and one for UDP. This doubles the size of the result list and usually requires extra filtering. Best practice is to always set ai_socktype explicitly.

Q6. What is the difference between AI_ALL and AI_V4MAPPED alone?

Answer: AI_V4MAPPED alone: returns IPv4-mapped IPv6 entries only if no native IPv6 addresses were found (as a fallback). AI_V4MAPPED combined with AI_ALL: returns both native IPv6 entries AND IPv4-mapped entries — regardless of whether native IPv6 was found. AI_ALL has no effect without AI_V4MAPPED.

Q7. How do you make getaddrinfo() return an address for binding to all interfaces on a specific port?

Answer: Pass NULL for host and set AI_PASSIVE in hints.ai_flags:

hints.ai_flags = AI_PASSIVE;
getaddrinfo(NULL, "8080", &hints, &result);
/* result->ai_addr contains the wildcard address (0.0.0.0:8080 or :::8080) */

Q8. Can you combine AI_PASSIVE with a non-NULL host argument?

Answer: Technically the call may succeed, but it is semantically wrong. AI_PASSIVE is designed to be used with host = NULL to get a wildcard address. If you specify a hostname with AI_PASSIVE, the returned address will be the specific host address rather than a wildcard, which defeats the purpose. The standard practice is always to pass host = NULL when AI_PASSIVE is set.