ARES_PROCESS(3)

✨ ARES_PROCESS(3) ✨

okay bestie, so this is a page from the Library Functions Manual, all about processing events for name resolution 🦋 and honestly it's giving "you're building your own event loop and you need c-ares to play nice with it."

---

💖 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)

---

🎀 DESCRIPTION 🎀

so here's the tea ☕ these functions are for you if you are an integrator who has chosen not to use the EventThread that you'd normally get by passing ARES_OPT_EVENT_THREAD to ares_init_options. Basically the vibe is: you already have your own event loop doing event notifications for a whole bunch of file descriptors, and you wanna do the exact same thing when you hook up with c-ares. iconic, honestly 🫶

---

💅 ares_process_fds — the main character

The ares_process_fds(3) function handles input/output events on file descriptors and the timeouts associated with 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 in the fd member, and the events are a bitwise mask of ares_fd_eventflag_t in the event member. ✨

You can also use this function to process timeouts — just pass NULL to the events member with an nevents value of 0. 🕐 Flags can be specified in the flags field too, and those are defined in ares_process_flag_t.

• ARES_PROCESS_FLAG_SKIP_NON_FD — specify this and you specifically skip any processing that isn't related to the file descriptor events you passed in. Examples of what gets skipped include timeout processing and cleanup handling. This is lowkey perfect if you know you're gonna be sending multiple ares_process_fds(3) requests and you wanna skip all that extra processing. BUT ⚠️ — the integrator must send the final request with the flag so that timeout and other processing gets performed before their event loop waits on additional events. do not skip this step bestie.

It is allowable to use an ares_fd_events_t with an events member of value ARES_FD_EVENT_NONE (0) when there are no events for a given file descriptor — for instance if an integrator just wants to maintain one big array with all possible file descriptors and update readiness via the event member. 🗂️

This function will return ARES_ENOMEM in out of memory conditions, otherwise it will return ARES_SUCCESS. 🫡

This function is recommended over ares_process_fd(3) because it can handle processing of multiple file descriptors at once — which means you skip repeating additional logic like timeout processing, which you'd have to do if you called ares_process_fd(3) for multiple file descriptors that got notified at the same time. efficiency slay 💅

This function is typically used with the ARES_OPT_SOCK_STATE_CB option.

ares_timeout(3) should be used to retrieve the desired timeout, and when the 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). 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). 🧚

---

🌈 ares_process_fd — the smaller one

The ares_process_fd(3) function is 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. 👑

---

💀 ares_process — the deprecated one, tread carefully

The ares_process(3) function works in the same manner, except it works on fd_sets as is 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 in the select(3) implementation. like, fr fr, leave it in the past bestie 🙈

---

⭐ AVAILABILITY ⭐

ares_process_fds(3) was introduced in c-ares 1.34.0. 🎉

---

🦋 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, no cap 💖 this one's dated 25 July 1998 and it comes to you from the c-ares crew — go forth and process those events, you absolute legend 👑✨