ARES_PROCESS(3) Introduction to Library Functions ARES_PROCESS(3)

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

These functions must be used by integrators choosing not to use the
EventThread enabled via ARES_OPT_EVENT_THREAD passed to
ares_init_options. This assumes integrators already have their own
event loop handling event notifications for various file descriptors
and wish to do the same with their integration with c-ares.

The ares_process_fds(3) function handles input/output events on file
descriptors and timeouts associated with queries pending on the
channel identified by channel. The file descriptors to be processed
are passed in an array of ares_fd_events_t data structures in the fd
member, and events are a bitwise mask of ares_fd_eventflag_t in the
event member. This function can also be used to process timeouts by
passing NULL to the events member with nevents value of 0. Flags may
also be specified in the flags field and are defined in
ares_process_flag_t.

ARES_PROCESS_FLAG_SKIP_NON_FD can be specified to specifically skip
any processing unrelated to the file descriptor events passed in,
examples include timeout processing and cleanup handling. This is
useful if an integrator knows they will be sending multiple
ares_process_fds(3) requests and wants to skip that extra processing.
However, 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.

It is allowable to use an ares_fd_events_t with events member of
value ARES_FD_EVENT_NONE (0) if there are no events for a given file
descriptor if an integrator wishes to simply maintain an 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 will return ARES_SUCCESS.

This function is recommended over ares_process_fd(3) since it can
handle processing of multiple file descriptors at once, thus skipping
repeating additional logic such as timeout processing which would be
required if calling ares_process_fd(3) for multiple file descriptors
notified at the same time.

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 as timeout
processing will automatically be handled by any call to
ares_process_fds(3) or ares_process_fd(3).

The ares_process_fd(3) function is the same as ares_process_fds(3)
except can only process a single read and write file descriptor at a
time. New integrators should use ares_process_fds(3) if possible.

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 to the select(3)
implementation.

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

25 July 1998 ARES_PROCESS(3)