ARES_GETHOSTBYADDR(3)

💖 ARES_GETHOSTBYADDR(3) 💖

okay bestie, gather round, because we're diving into ares_gethostbyaddr from the Library Functions Manual — it's a c-ares thing, it's a libc-adjacent thing, and it's about to be your whole personality. no cap. 🌸

---

✨ NAME ✨

ares_gethostbyaddr — bestie, this is how you start a host query by address. like, you got the address, now you want the name. reverse-engineer the vibe. 🔍

---

🦋 SYNOPSIS 🦋

#include <ares.h>

typedef void (*ares_host_callback)(void *arg, int status,
                                   int timeouts,
                                   struct hostent *hostent)

void ares_gethostbyaddr(ares_channel_t *channel, const void *addr,
                        int addrlen, int family,
                        ares_host_callback callback, void *arg)

like look at that signature. she's giving structured. she's giving typed. we love her. 💅

---

🌈 DESCRIPTION 🌈

so ares_gethostbyaddr kicks off a host query by address on the name service channel that you hand it in channel. iconique behaviour, honestly.

the parameters addr and addrlen are the address, but as a series of bytes — yes bestie, bytes, we're in the trenches — and family tells it what type of address we're dealing with. then when the query either wraps up or flops, the ares library is gonna invoke your callback. and listen: completion or failure can happen immediately, or it can happen later during a call to ares_process(3), ares_destroy(3) or ares_cancel(3). so don't be out here assuming timing. ⏳

the callback argument arg gets copied straight over from the arg you passed into ares_gethostbyaddr. and the callback argument status is the vibe check — did the query succeed, and if not, how did it go wrong. it can be any one of these bad boys:

• ARES_SUCCESS — slay. the host lookup completed successfully. 🎉
• ARES_ENOTIMP — the ares library literally does not know how to look up addresses of type family. it's not mad, it's just not implemented. 🙈
• ARES_ENOTFOUND — the address addr was not found. she's not here, bestie. 😭
• ARES_ENOMEM — memory was exhausted. we ran out. tragic. 💀
• ARES_ECANCELLED — the query was cancelled.
• ARES_EDESTRUCTION — the name service channel channel is being destroyed, so the query will not be completed. rip.

the callback argument timeouts tells you how many times a query timed out while this particular request was executing. keeping receipts. 🧾

on a successful completion of the query, the callback argument hostent points to a struct hostent holding the name of the host that the query returned. and now for the rules, bestie, because this part is important:

the callback need not — and honestly should not — try to free the memory that hostent points to. the ares library handles that when the callback returns. 🙅‍♀️

the callback must not modify the struct hostent or hold onto a reference to it after returning. it is owned by c-ares and is only valid for the duration of the callback. periodt. 👑

and like, the parameter is intentionally not declared const, but only to preserve API/ABI compatibility with existing applications — it's not an invitation, bestie. if the query did not complete successfully, hostent will be NULL. 🫠

when the associated callback gets called, it's called with a channel lock, so you gotta be careful and keep any processing minimal to prevent DNS channel stalls. minimal effort, maximum outcome, that's the energy. ⚡

also, the callback may be triggered from a different thread than the one that called ares_gethostbyaddr(3). so if you were assuming same-thread, nope, check yourself. 🧵

and for the integrators out there running their own event loops and not using ARES_OPT_EVENT_THREAD — care needs to be taken to make sure any file descriptor lists are updated immediately within the eventloop when notified. iykyk. 🌟

---

👑 SEE ALSO 👑

• ares_process(3)
• ares_gethostbyname(3)

---

that's the whole page, bestie. you ate. 💅✨

24 July 1998 — yeah, she's been iconic since the nineties, and this is the ARES_GETHOSTBYADDR(3) page from the Library Functions Manual, signing off. 🎀🦋💖