ARES_GETSOCK(3)

💖 ARES_GETSOCK(3) — Library Functions Manual 💖

okay bestie, gather round, because we're talking about ares_getsock — and the tea is that she's deprecated, so this is giving "beloved but retired icon" energy 👑

✨ NAME ✨

ares_getsock — get socket descriptors to wait on (deprecated) 🫶

🌸 SYNOPSIS 🌸

#include <ares.h>

int ares_getsock(const ares_channel_t *channel, ares_socket_t *socks,
                 int numsocks);

🦋 DESCRIPTION 🦋

so like. ares_getsock hands you the whole set of socket descriptors that your app should be waiting on — for reading and/or writing — so that the name service queries pending on the channel identified by channel can actually get processed. 💅

The socket descriptors get dropped into the socket descriptor array that socks points at. And numsocks? That's the size of the array you passed in, measured in number of ints. no cap.

⚠️ heads up bestie: this function can only ever report up to 16 sockets. if more than 16 are in use, they're just… not reported back. literally ghosted. 💀

🎀 RETURN VALUES 🎀

ares_getsock returns a bitmask telling you what actions to wait for on each of the different sockets. and the ares.h header file is your bestie here, because it ships these convenience macros so you can pull the info out properly:

#define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about
                                  this many sockets */
#define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
#define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) +                                          ARES_GETSOCK_MAXNUM)))

💅 NOTES 💅

okay so the lore: this function was added in c-ares 1.3.1 and then deprecated in c-ares 1.20.0 — because of the implementation of ARES_OPT_MAX_UDP_QUERIES, which makes it likely to exceed 16 open file descriptors. the limit said "not today" and honestly? she's right. 😭

so the recommendation is: use ARES_OPT_EVENT_THREAD passed to ares_init_options(3), or use socket state callbacks (ARES_OPT_SOCK_STATE_CB) registered via ares_init_options(3). that's the move, periodt. ✨

🌈 SEE ALSO 🌈

• ares_init_options(3)
• ares_timeout(3)
• ares_fds(3)
• ares_process(3)

and that's the whole page, bestie! this little relic was dated 11 March 2010, and it lives in the Library Functions Manual — so if you're out here reading it in the present day, know that you're reading a certified classic. stay hydrated, go use ARES_OPT_EVENT_THREAD, mwah 💖🧚🌸