gethostbyname(3)

💫 gethostbyname(3) — Library Functions Manual 💫

okay bestie sit DOWN because we're doing a whole legendary one today 🎀 this is the gethostbyname family from the Standard C library (libc, -lc) — the friend group that finds network host entries for you. and yes, half of them are lowkey deprecated and we're gonna be honest about that the whole time, no cap 💀

---

✨ NAME ✨

so like, the whole squad: gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r — all here to get network host entry 🦋

---

📚 LIBRARY 📚

Standard C library (that's libc, link it with -lc) 💖

---

🌈 SYNOPSIS 🌈

the vibes begin with an include, always:

#include <netdb.h>

void sethostent(int stayopen);
void endhostent(void);

[[deprecated]] extern int h_errno;

[[deprecated]] struct hostent *gethostbyname(const char *name);
[[deprecated]] struct hostent *gethostbyaddr(socklen_t size;
                                             const void addr[size],
                                             socklen_t size, int type);

[[deprecated]] void herror(const char *s);
[[deprecated]] const char *hstrerror(int err);

/* System V/POSIX extension */
struct hostent *gethostent(void);

/* GNU extensions */
[[deprecated]]
struct hostent *gethostbyname2(const char *name, int af);

int gethostent_r(size_t bufsize;
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

[[deprecated]]
int gethostbyaddr_r(socklen_t size, size_t bufsize;
                 const void addr[restrict size], socklen_t size,
                 int type,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname_r(size_t bufsize;
                 const char *restrict name,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname2_r(size_t bufsize;
                 const char *restrict name, int af,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

see all those [[deprecated]] tags? yeah. the compiler is literally giving you the side-eye 🙈 those functions still work but they are NOT the moment anymore.

---

🌸 Feature Test Macro Requirements for glibc 🌸

(if you don't know what those are, go read feature_test_macros(7) — it's giving prerequisite 💅)

gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
gethostbyname2_r():
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc up to and including 2.19:
        _BSD_SOURCE || _SVID_SOURCE

herror(), hstrerror():
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.8 to glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE
    Before glibc 2.8:
        none

h_errno:
    Since glibc 2.19
        _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
    glibc 2.12 to glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
    Before glibc 2.12:
        none

---

💅 DESCRIPTION 💅

okay first thing, and I need you to hear me on this one:

red alert, bestie 🚨 the gethostbyname*(), gethostbyaddr*(), herror(), and hstrerror() functions are obsolete. like, retro. applications should be using getaddrinfo(3), getnameinfo(3), and gai_strerror(3) instead. periodt.

but we're still gonna learn them because you WILL run into them in the wild and you will be the only one in the group chat who knows what's going on 😌

---

<cyan>sethostent()</cyan> — if stayopen is true (aka 1), this says "hey, use a connected TCP socket for the name server queries, and keep that connection open across successive queries." otherwise the queries just use UDP datagrams. casual. UDP core 🦋

<cyan>endhostent()</cyan> — ends the whole TCP-connection-for-name-server-queries thing. wrap it up, we're done here 🎀

<cyan>gethostbyname()</cyan> — returns a hostent structure for the host name you pass in. now here's the tea: name can be either a hostname OR an IPv4 address in standard dot notation (the same kind inet_addr(3) deals with). and if name IS an IPv4 address? no lookup happens at all — it just copies name straight into the h_name field, and its struct in_addr equivalent straight into the h_addr_list[0] field of the returned hostent. instant. no network call. the way that's so efficient actually?? ✨

a couple more details bestie:

• if name doesn't end in a dot AND the environment variable HOSTALIASES is set, the alias file pointed to by HOSTALIASES gets searched for name first (check hostname(7) for the file format 📖)
• the current domain and its parents get searched, unless name ends in a dot

<cyan>gethostbyaddr()</cyan> — returns a hostent for the given host address addr, of size size, with address type type. valid address types are AF_INET and AF_INET6 (those live in <sys/socket.h>). the address argument is a pointer to a struct whose type depends on the address type — for example a struct in_addr * (probs obtained from a call to inet_addr(3)) for address type AF_INET 💜

<cyan>herror()</cyan> — (obsolete, we been knew) prints the error message associated with the current value of h_errno to stderr. loud and proud 📢

<cyan>hstrerror()</cyan> — (also obsolete) takes an error number (usually h_errno) and hands you back the corresponding message string 🫶

---

the domain name queries that gethostbyname() and gethostbyaddr() do rely on the Name Service Switch (nsswitch.conf(5)) configured sources, or a local name server (named(8)). the default move is: query the ones configured in nsswitch.conf(5), and if that fails, hit a local name server (named(8)) 🧚

---

🕰️ Historical 🕰️

nsswitch.conf(5) is the modern way of controlling the order of host lookups. iconic. forward-thinking. we love her 🌈

in glibc 2.4 and earlier, it was the order keyword that controlled host lookup order, as defined in /etc/host.conf (check host.conf(5)). throwback energy fr fr 💀

---

the hostent structure is defined in <netdb.h> like this, and I need you to memorize it because it will come up again:

struct hostent {
    char  *h_name;            /* official name of host */
    char **h_aliases;         /* alias list */
    int    h_addrtype;        /* host address type */
    int    h_length;          /* size of address */
    char **h_addr_list;       /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */

and now the members, one by one, because every single one matters bestie:

• h_name — the official name of the host 👑
• h_aliases — an array of alternative names for the host, terminated by a null pointer
• h_addrtype — the type of address; always AF_INET or AF_INET6 at present
• h_length — the size of the address, in bytes 📏
• h_addr_list — an array of pointers to network addresses for the host (in network byte order), terminated by a null pointer
• h_addr — the first address in h_addr_list, kept around for backward compatibility 💖

---

🎀 RETURN VALUE 🎀

gethostbyname() and gethostbyaddr() hand you back the hostent structure, or a null pointer if something goes wrong. and on error, the h_errno variable is holding an error number, keeping the receipts 📝

heads up tho: when the return value is non-NULL, it may point at static data — peep the notes below (that's in the next part bestie, don't go anywhere).

---

🚨 ERRORS 🚨

the variable h_errno can have these values, and each one is telling you a different story:

• HOST_NOT_FOUND — the specified host is unknown. they're not in the system, bestie, not even a little 💀
• NO_DATA — the requested name is valid but it doesn't have an IP address. a different type of request to the name server for this domain might still get you an answer. oh and btw, the constant NO_ADDRESS is a synonym for NO_DATA — same vibe, different name 🌸
• NO_RECOVERY — a nonrecoverable name server error happened. no coming back from this one 😭
• TRY_AGAIN — a temporary error occurred on an authoritative name server. just try again later, it's not you, it's them 🫶

---

📁 FILES 📁

• /etc/host.conf — resolver configuration file
• /etc/hosts — host database file
• /etc/nsswitch.conf — name service switch configuration

---

aand that's part 1 of the gethostbyname(3) saga, keep scrolling bestie there's more 💜✨

🫧 ATTRIBUTES 🫧

ok so before we go any further, bestie, if you wanna know what all these fancy words even mean, go peek at attributes(7). that's the lore. ✨

here's the whole thread-safety situation, laid out one by one:

• gethostbyname() — Thread safety: MT-Unsafe race:hostbyname env locale
• gethostbyaddr() — Thread safety: MT-Unsafe race:hostbyaddr env locale
• sethostent(), endhostent(), gethostent_r() — Thread safety: MT-Unsafe race:hostent env locale
• herror(), hstrerror() — Thread safety: MT-Safe 💚
• gethostent() — Thread safety: MT-Unsafe race:hostent race:hostentbuf env locale
• gethostbyname2() — Thread safety: MT-Unsafe race:hostbyname2 env locale
• gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r() — Thread safety: MT-Safe env locale 👑

and about that hostent word popping up inside race:hostent up there — lemme translate, bestie: it means that if any of sethostent(), gethostent(), gethostent_r(), or endhostent() get used in parallel across different threads of one program, then data races could occur. like, chaos. 💀 so don't do that.

---

📜 STANDARDS 📜

• sethostent()
• endhostent()
• gethostent()

all three of those? POSIX.1-2008. certified, canon, periodt. 💅

• gethostent_r()

that one's GNU. house-made. 🎀

• Others:

None. nope, not a single one. the rest are out here unstandardized fr fr. 😭

---

🕰️ HISTORY 🕰️

• sethostent()
• endhostent()
• gethostent()

these cuties go all the way back to POSIX.1-2001. vintage. ✨

• gethostbyname()
• gethostbyaddr()
• h_errno

okay so these three got marked obsolescent back in POSIX.1-2001, and then removed entirely in POSIX.1-2008 — and the standard was like "use getaddrinfo(3) and getnameinfo(3) instead bestie". so yeah. they're giving retirement era. 🙈

---

📝 NOTES 📝

gethostbyname() and gethostbyaddr() might hand you pointers to static data, and that data can get overwritten by later calls. so if you think "oh I'll just copy the struct hostent" — nope, that does not suffice, because it's full of pointers. you need a deep copy, okay? a shallow copy is a trap. 🪤

in the original BSD implementation, the size argument of gethostbyname() was an int. and then SUSv2 came along and, uh, the standard is buggy — it declares the size argument of gethostbyaddr() to be of type size_t. which is wrong, because it has to be int, and size_t is not. POSIX.1-2001 makes it socklen_t, which is OK. 💅 see also accept(2).

also: the BSD prototype for gethostbyaddr() uses const char * for the first argument. noted. 🫶

🧚 System V/POSIX extension 🧚

POSIX requires the gethostent() call, which should return the next entry in the host data base. now — when you're using DNS/BIND this does not make much sense, but it may be reasonable if the host data base is a file that can be read line by line. on many systems, a routine of this name reads from the file /etc/hosts. it may be available only when the library was built without DNS support. the glibc version will ignore ipv6 entries. and this function is not reentrant, so glibc went ahead and added a reentrant version: gethostent_r(). slay for safety. 🛟

🌈 GNU extensions 🌈

glibc2 also has a gethostbyname2() that works like gethostbyname(), but permits you to specify the address family to which the address must belong. picky in a cute way. 💅

glibc2 also has reentrant versions: gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), and gethostbyname2_r(). here's how they work, bestie: the caller supplies a hostent structure ret which will be filled in on success, and a temporary work buffer buf of size bufsize. after the call, result will point to the result on success. in case of an error or if no entry is found, result will be NULL. the functions return 0 on success and a nonzero error number on failure. and on top of the errors returned by the nonreentrant versions of these functions, if buf is too small, the functions will return ERANGE, and the call should be retried with a larger buffer. 🔁 the global variable h_errno is not modified, but the address of a variable in which to store error numbers is passed in h_errnop. so you hand it a place to put the oopsie. 🎀

---

🐛 BUGS 🐛

gethostbyname() does not recognize components of a dotted IPv4 address string that are expressed in hexadecimal. that's it. that's the bug. sorry hex girlies. 💀

---

👀 SEE ALSO 👀

getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3), resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

---

okay that's the whole page, bestie, you made it to the end 🎉 go forth and resolve those hostnames responsibly (or better yet, use getaddrinfo(3), the standards girlies are literally begging). this was brought to you by Linux man-pages 6.20, dated 2026-02-08, and this page is gethostbyname(3) — iconic, historic, and slightly obsolescent. mwah. 💖✨🦋