ARES_SET_S...E_CALLBACK(3)

💅 ares_set_server_state_callback — the "tell me everything about my DNS servers" callback 💅

okay so bestie, this one's from the Library Functions Manual, and it's genuinely one of those lowkey iconic little hooks that lets you spy on what your DNS servers are doing. no cap, it's giving observability queen 👑

---

✨ NAME ✨

ares_set_server_state_callback — the function for setting a server state callback. yes that's literally it, that's the whole vibe 🎀

---

✨ SYNOPSIS ✨

#include <ares.h>

typedef void (*ares_server_state_callback)(const char *server_string,
                                           ares_bool_t success,
                                           int flags,
                                           void *data);

void ares_set_server_state_callback(ares_channel_t *channel,
                                    ares_server_state_callback callback,
                                    void *user_data);

---

✨ DESCRIPTION ✨

so ares_set_server_state_callback(3) sets a callback function callback in the given ares channel handle channel, and that callback gets invoked whenever a query on the channel completes. and when we say completes we mean both successful and unsuccessful queries — including hard errors and timeouts. no cherry-picking, every single one gets reported 🫶

the callback is invoked with a bunch of parameters describing the query, like the following:

the server_string parameter tells you which DNS server was used for the query, given as a string with the same format returned by ares_get_servers_csv(3). iykyk 📋

the success parameter tells you whether the query succeeded or not — it's set to ARES_TRUE on success and ARES_FALSE on failure. simple as that 💖

the flags parameter is a bitmask of flags describing various aspects of the query (for example whether the query used UDP or TCP). these are described below, don't worry ✨

the data parameter is a reference to the custom user data user_data that was passed to ares_set_server_state_callback(3) when setting the server state callback. it's your little goodie bag, come back to it whenever 🎁

so what's the point? the server state callback can be used by applications to monitor the state of the DNS servers used by an ares channel. for example, it can be used to track metrics about the numbers and types of queries sent to each server — or to detect when a server is uncontactable or unhealthy. literally your own personal server health tracker, main character energy 🔥

---

✨ REENTRANCY ✨

the server state callback may call c-ares functions on the same channel, including ares_cancel(3) and the server configuration functions. the channel lock is recursive and the library holds no query, connection or server state across the callback. so like, you're safe to do your thing in there, no deadlock drama 💅

notifications are queued and delivered once the library has finished the work that produced them, rather than part-way through it. a notification is therefore observed after the processing pass that generated it, not during. it's giving "we'll tell you when we're done, not while we're mid-task" ⏳

the callback and its user_data are read when the notification is delivered, not when it is queued. so an application that replaces its callback between those two points will see the notification delivered to the new one; unregistering by passing a NULL callback discards any notification still queued. heads up on that one 🙈

this applies to a replacement made from within a c-ares callback, where the channel lock is held. ares_set_server_state_callback(3) does not take the channel lock, so replacing the callback from another thread while the channel is processing is not synchronized against delivery. fr fr, don't do the multi-thread swap without thinking about it 💀

---

✨ FLAGS ✨

• ARES_SERV_STATE_UDP — indicates that the query was tried over UDP. the classic, the default vibe 🦋
• ARES_SERV_STATE_TCP — indicates that the query was tried over TCP. when UDP wasn't it and we had to go the reliable route 🌸

---

✨ AVAILABILITY ✨

• this function was first introduced in c-ares version 1.29.0. so it's been around a minute ⭐
• the reentrancy guarantee described above applies as of c-ares version 1.35.0, and c-ares version 1.34.9 on the 1.34 branch. so if you're on an older one, check your version before you trust the reentrancy tea 👑

---

✨ SEE ALSO ✨

• ares_get_servers_csv(3)
• ares_cancel(3)

go read those too bestie, they're literally connected 🧚

---

and that's the whole page! 💜 this glorious little number was dated 26 Apr 2024 and comes from the Library Functions Manual — mwah, sending you off with a kiss and a working ares channel 😭🎀