getnameinfo(3)

💖 getnameinfo(3) 💖

okay bestie, gather round, because we're about to talk about the Library Functions Manual entry for getnameinfo and honestly? it's giving iconic. 🦋

---

✨ NAME ✨

getnameinfo — address-to-name translation, but make it protocol-independent. no cap. 💅

---

🌸 LIBRARY 🌸

Standard C library (that's libc, linked with -lc) 🎀

---

🦋 SYNOPSIS 🦋

#include <sys/socket.h>
#include <netdb.h>

int getnameinfo(socklen_t hostlen, socklen_t servlen;
                const struct sockaddr *restrict addr, socklen_t addrlen,
                char host[_Nullable restrict hostlen],
                socklen_t hostlen,
                char serv[_Nullable restrict servlen],
                socklen_t servlen,
                int flags);

Feature Test Macro Requirements for glibc (peep feature_test_macros(7) for the full tea):

getnameinfo():

• Since glibc 2.22:
  • _POSIX_C_SOURCE >= 200112L
• glibc 2.21 and earlier:
  • _POSIX_C_SOURCE

yes bestie, that synopsis really does look like that. copy it exactly, don't get cute with it. 🙈

---

💜 DESCRIPTION 💜

So getnameinfo() is literally the inverse of getaddrinfo(3) — it takes a socket address and turns it back into a matching host and service, all protocol-independent style. It's basically gethostbyaddr(3) and getservbyport(3) fused together into one queen 👑 — except unlike those two, getnameinfo() is reentrant and lets your program fully eliminate its IPv4-versus-IPv6 dependency drama.

The addr argument is a pointer to a generic socket address structure (type sockaddr_in or sockaddr_in6) of size addrlen, and it's holding your input IP address plus port number. The host and serv arguments are pointers to buffers you allocated (sizes hostlen and servlen respectively), and getnameinfo() drops null-terminated strings containing the host name and service name into them. 🫶

And here's the slay: if you don't need a hostname (or don't need a service name), you can just say so — pass a NULL host (or serv) argument, or a zero hostlen (or servlen). But at least one of hostname or service name must be requested. you can't opt out of both, bestie, pick a lane. 😭

The flags argument changes how getnameinfo() behaves, like this:

• NI_NAMEREQD — if set, you get an error back when the hostname just cannot be determined. no vibes, no name, error. 💀
• NI_DGRAM — if set, the service is treated as datagram (UDP) based instead of stream (TCP) based. You need this for the few ports (512–514) that have different services for UDP and TCP. iykyk.
• NI_NOFQDN — if set, you only get the hostname part of the fully qualified domain name, and only for local hosts. ✂️
• NI_NUMERICHOST — if set, you get the numeric form of the hostname returned. (Even when it's not set, this still happens if the node's name can't be determined — so it's the fallback bestie either way.)
• NI_NUMERICSERV — if set, you get the numeric form of the service address returned. (Same deal: even when not set, it still happens if the service's name can't be determined.)

---

🌈 Extensions to getnameinfo() for Internationalized Domain Names 🌈

Starting with glibc 2.3.4, getnameinfo() got extended so hostnames can be transparently converted to and from the Internationalized Domain Name (IDN) format — selectively, of course, she's not doing anything without consent. See RFC 3490, Internationalizing Domain Names in Applications (IDNA). Three new flags got defined:

• NI_IDN — if you use this flag, then the name found in the lookup process gets converted from IDN format to the locale's encoding, if that conversion is necessary. ASCII-only names are not affected by the conversion, which is exactly what makes this flag usable in existing programs and environments. 🧚
• NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES — setting these flags enables the IDNA_ALLOW_UNASSIGNED flag (allow unassigned Unicode code points) and the IDNA_USE_STD3_ASCII_RULES flag (check the output to make sure it's a STD3 conforming hostname) respectively, to be used in the IDNA handling. two-for-one deal, obsessed. 💖

---

🔥 RETURN VALUE 🔥

On success, 0 comes back, and the node and service names (if you requested them) are filled with null-terminated strings — possibly truncated so they fit the buffer lengths you specified. bestie said "make it fit" and she meant it.

On error, you get one of these nonzero error codes instead:

• EAI_AGAIN — the name could not be resolved at this time. Try again later. ⏳
• EAI_BADFLAGS — the flags argument has an invalid value. 🙅
• EAI_FAIL — a nonrecoverable error occurred. 😭
• EAI_FAMILY — the address family was not recognized, or the address length was invalid for the specified family.
• EAI_MEMORY — out of memory. 💀
• EAI_NONAME — the name does not resolve for the supplied arguments. That means either NI_NAMEREQD is set and the host's name cannot be located, or neither hostname nor service name were requested.
• EAI_OVERFLOW — the buffer pointed to by host or serv was too small. 😬
• EAI_SYSTEM — a system error occurred. The error code can be found in errno.

And for turning those codes into something human-readable and suitable for error reporting? That's gai_strerror(3), your translator bestie. 🎀

---

🍓 FILES 🍓

• /etc/hosts
• /etc/nsswitch.conf
• /etc/resolv.conf

---

⭐ ATTRIBUTES ⭐

For an explanation of the terms used in this section, peep attributes(7).

• Interface: getnameinfo()
• Attribute: Thread safety
• Value: MT-Safe env locale

so yeah, she's MT-Safe, with the note that it's env locale — translation: environment and locale sensitivities are in play. 💅

---

👑 STANDARDS 👑

POSIX.1-2008. RFC 2553. certified classic, no notes. ✨

---

🌸 HISTORY 🌸

• glibc 2.1.
• POSIX.1-2001.

And before glibc 2.2, the hostlen and servlen arguments were typed as size_t. glow-up era. 💅

---

🦋 NOTES 🦋

To help you (the programmer, the main character) pick reasonable sizes for the buffers you're handing over, <netdb.h> defines these constants:

#define NI_MAXHOST      1025
#define NI_MAXSERV      32

Since glibc 2.8, these definitions are only exposed if suitable feature test macros are defined, namely: _GNU_SOURCE, _DEFAULT_SOURCE (since glibc 2.19), or — in glibc versions up to and including 2.19 — _BSD_SOURCE or _SVID_SOURCE.

The former (NI_MAXHOST) is the constant MAXDNAME in recent versions of BIND's <arpa/nameser.h> header file. The latter (NI_MAXSERV) is a guess based on the services listed in the current Assigned Numbers RFC. she's estimating, and she's honest about it. 🙈

---

💖 EXAMPLES 💖

Okay so this first snippet tries to get the numeric hostname and service name for a given socket address. Notice there is no hardcoded reference to a particular address family — that's the whole point, bestie:

struct sockaddr *addr;     /* input */
socklen_t addrlen;         /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
            sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
    printf("host=%s, serv=%s\n", hbuf, sbuf);

And this next version checks whether the socket address has a reverse address mapping:

struct sockaddr *addr;     /* input */
socklen_t addrlen;         /* input */
char hbuf[NI_MAXHOST];

if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
            NULL, 0, NI_NAMEREQD))
    printf("could not resolve hostname");
else
    printf("host=%s\n", hbuf);

Also — an example program using getnameinfo() can be found over in getaddrinfo(3). go peek, she ate. 🔥

---

🌈 SEE ALSO 🌈

accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2), getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), hosts(5), services(5), hostname(7), named(8)

R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 2553, March 1999.

Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, internet draft, work in progress ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt.

Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html.

---

and that's the whole page, bestie!! 🎀 this was the Linux man-pages 6.20 version, dated 2025-12-25 — a lil christmas gift of socket knowledge, fr fr. go forth and translate those addresses. mwah. 💅💖🦋✨