ARES_PROCESS(3)

💖 ARES_PROCESS(3) 💖

okay bestie, so this is a page from the Library Functions Manual and it's all about ares_process_fds, ares_process_fd, and ares_process — the trio that handles process events for name resolution. yes ma'am, the whole squad 💅

---

✨ NAME ✨

ares_process_fds, ares_process_fd, ares_process — process events for name resolution 🦋

---

🌸 SYNOPSIS 🌸

#include <ares.h>

/*! Events used by ares_fd_events_t */
typedef enum {
  ARES_FD_EVENT_NONE  = 0,      /*!< No events */
  ARES_FD_EVENT_READ  = 1 << 0, /*!< Read event (including disconnect/error) */
  ARES_FD_EVENT_WRITE = 1 << 1  /*!< Write event */
} ares_fd_eventflag_t;

/*! Type holding a file descriptor and mask of events, used by
 *  ares_process_fds() */
typedef struct {
  ares_socket_t fd;     /*!< File descriptor */
  unsigned int  events; /*!< Mask of ares_fd_event_t */
} ares_fd_events_t;

typedef enum {
  ARES_PROCESS_FLAG_NONE        = 0,
  ARES_PROCESS_FLAG_SKIP_NON_FD = 1 << 0
} ares_process_flag_t;

ares_status_t ares_process_fds(ares_channel_t         *channel,
                               const ares_fd_events_t *events,
                               size_t                  nevents,
                               unsigned int            flags)

void ares_process_fd(ares_channel_t *channel,
                     ares_socket_t read_fd,
                     ares_socket_t write_fd)

void ares_process(ares_channel_t *channel,
                  fd_set *read_fds,
                  fd_set *write_fds)

like look at those signatures, they ate and left absolutely no crumbs 👑

---

💜 DESCRIPTION 💜

so here's the vibe: these functions are required if you're an integrator who chose not to use the EventThread that you'd normally enable via ARES_OPT_EVENT_THREAD passed to ares_init_options. it's giving "I already have my own event loop and I'm not about to give it up." basically the assumption here is that you, the integrator, are already handling event notifications for a bunch of file descriptors yourself, and now you want your c-ares integration to do the same thing. respect. 🫶

🌈 ares_process_fds(3)

this one is the main character fr fr. it handles input/output events on file descriptors and timeouts tied to queries that are pending on the channel identified by channel.

• the file descriptors you want processed get passed in as an array of ares_fd_events_t data structures — that's the fd member, bestie.
• the events are a bitwise mask of ares_fd_eventflag_t, and they live in the event member.

and here's a little trick that's lowkey iconic: you can also use this function to process timeouts by passing NULL to the events member with a nevents value of 0. ✨

flags can also be specified in the flags field, and those are defined in ares_process_flag_t.

🎀 ARES_PROCESS_FLAG_SKIP_NON_FD

you can pass this flag to specifically skip any processing unrelated to the file descriptor events you passed in — think timeout processing, cleanup handling, all that side-quest stuff.

why would you want that? because if you know you're about to fire off multiple ares_process_fds(3) requests, you can skip that extra processing and save yourself the work. efficient queen behavior. 💅

⚠️ BUT — and this is important, no cap — the integrator must send the final request with the flag so that timeout and other processing actually gets performed before their event loop waits on additional events. do not skip that last one. that's the rule.

🦋 the ARES_FD_EVENT_NONE moment

it is totally allowable to use an ares_fd_events_t with an events member of value ARES_FD_EVENT_NONE (that's 0) when there are no events for a given file descriptor. this is for when an integrator just wants to keep one single array holding all possible file descriptors and update readiness through the event member. tidy. organized. we love a system. 💖

🍓 return values

this function returns ARES_ENOMEM in out-of-memory conditions — otherwise it returns ARES_SUCCESS. simple as that, periodt.

👑 why it's the favorite

this function is recommended over ares_process_fd(3) because it can handle processing of multiple file descriptors at once. that means it skips repeating extra logic — like timeout processing — which you'd otherwise be stuck doing if you called ares_process_fd(3) separately for a bunch of file descriptors that all got notified at the same time. one call, many fds, no repeats. it's giving efficiency. it's giving taste. 😌

this function is typically used with the ARES_OPT_SOCK_STATE_CB option, iykyk.

🧚 the timeout situation (pay attention bestie)

you should use ares_timeout(3) to retrieve the desired timeout. then, when that timeout expires, the integrator must call ares_process_fds(3) with a NULL events array — or ares_process_fd(3) with both sockets set to ARES_SOCKET_BAD.

🌸 however — there is no need to do this if events are also delivered for any file descriptors, because timeout processing will automatically be handled by any call to ares_process_fds(3) or ares_process_fd(3). auto-magic, no extra steps. ✨

💫 ares_process_fd(3)

the same as ares_process_fds(3)... except it can only process a single read and write file descriptor at a time. 🙈

new integrators should use ares_process_fds(3) if possible. fr fr.

🌟 ares_process(3)

works in the same manner, except it works on fd_sets as used by select(3) and retrieved by ares_fds(3).

💀 this method is DEPRECATED and should NOT be used in modern applications due to known limitations to the select(3) implementation. do not. I'm begging. use the other ones. 😭

---

⭐ AVAILABILITY ⭐

ares_process_fds(3) was introduced in c-ares 1.34.0. brand new-ish, slay.

---

🌈 SEE ALSO 🌈

• ares_fds(3)
• ares_timeout(3)
• ares_init_options(3) with ARES_OPT_EVENT_THREAD or ARES_OPT_SOCK_STATE_CB

---

and that's the whole page, bestie!! 🎀 go forth and process your events, you've got this, main character energy only 💖

signing off from the Library Functions Manual — dated 25 July 1998, filed under ARES_PROCESS(3)** 🦋✨