ares_process.3 (4947B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_PROCESS 3 "25 July 1998" 6 .SH NAME 7 ares_process_fds, ares_process_fd, ares_process \- Process events for name resolution 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 /*! Events used by ares_fd_events_t */ 13 typedef enum { 14 ARES_FD_EVENT_NONE = 0, /*!< No events */ 15 ARES_FD_EVENT_READ = 1 << 0, /*!< Read event (including disconnect/error) */ 16 ARES_FD_EVENT_WRITE = 1 << 1 /*!< Write event */ 17 } ares_fd_eventflag_t; 18 19 /*! Type holding a file descriptor and mask of events, used by 20 * ares_process_fds() */ 21 typedef struct { 22 ares_socket_t fd; /*!< File descriptor */ 23 unsigned int events; /*!< Mask of ares_fd_event_t */ 24 } ares_fd_events_t; 25 26 typedef enum { 27 ARES_PROCESS_FLAG_NONE = 0, 28 ARES_PROCESS_FLAG_SKIP_NON_FD = 1 << 0 29 } ares_process_flag_t; 30 31 32 ares_status_t ares_process_fds(ares_channel_t *\fIchannel\fP, 33 const ares_fd_events_t *\fIevents\fP, 34 size_t \fInevents\fP, 35 unsigned int \fIflags\fP) 36 37 void ares_process_fd(ares_channel_t *\fIchannel\fP, 38 ares_socket_t \fIread_fd\fP, 39 ares_socket_t \fIwrite_fd\fP) 40 41 void ares_process(ares_channel_t *\fIchannel\fP, 42 fd_set *\fIread_fds\fP, 43 fd_set *\fIwrite_fds\fP) 44 45 .fi 46 .SH DESCRIPTION 47 These functions must be used by integrators choosing not to use the 48 EventThread enabled via \fBARES_OPT_EVENT_THREAD\fP passed to 49 \fBares_init_options\fP. This assumes integrators already have their own 50 event loop handling event notifications for various file descriptors and 51 wish to do the same with their integration with c-ares. 52 53 The \fBares_process_fds(3)\fP function handles input/output events on file 54 descriptors and timeouts associated with queries pending on the channel 55 identified by \fIchannel\fP. The file descriptors to be processed are passed 56 in an array of \fIares_fd_events_t\fP data structures in the \fIfd\fP member, 57 and events are a bitwise mask of \fIares_fd_eventflag_t\fP in the \fIevent\fP 58 member. This function can also be used to process timeouts by passing NULL 59 to the \fIevents\fP member with \fInevents\fP value of 0. Flags may also be 60 specified in the \fIflags\fP field and are defined in \fBares_process_flag_t\fP. 61 62 \fBARES_PROCESS_FLAG_SKIP_NON_FD\fP can be specified to specifically skip any 63 processing unrelated to the file descriptor events passed in, examples include 64 timeout processing and cleanup handling. This is useful if an integrator 65 knows they will be sending multiple \fIares_process_fds(3)\fP requests and 66 wants to skip that extra processing. However, the integrator must send the 67 final request with the flag so that timeout and other processing gets performed 68 before their event loop waits on additional events. 69 70 It is allowable to use an \fIares_fd_events_t\fP with \fIevents\fP member of 71 value \fIARES_FD_EVENT_NONE\fP (0) if there are no events for a given file 72 descriptor if an integrator wishes to simply maintain an array with all 73 possible file descriptors and update readiness via the \fIevent\fP member. 74 75 This function will return \fIARES_ENOMEM\fP in out of memory conditions, 76 otherwise will return \fIARES_SUCCESS\fP. 77 78 This function is recommended over \fBares_process_fd(3)\fP since it can 79 handle processing of multiple file descriptors at once, thus skipping repeating 80 additional logic such as timeout processing which would be required if calling 81 \fBares_process_fd(3)\fP for multiple file descriptors notified at the same 82 time. 83 84 This function is typically used with the \fIARES_OPT_SOCK_STATE_CB\fP option. 85 86 \fBares_timeout(3)\fP should be used to retrieve the desired timeout, and when 87 the timeout expires, the integrator must call \fBares_process_fds(3)\fP with 88 a NULL \fIevents\fP array. (or \fBares_process_fd(3)\fP with both sockets set 89 to \fIARES_SOCKET_BAD\fP). There is no need to do this if events are also 90 delivered for any file descriptors as timeout processing will automatically be 91 handled by any call to \fBares_process_fds(3)\fP or \fBares_process_fd(3)\fP. 92 93 The \fBares_process_fd(3)\fP function is the same as \fBares_process_fds(3)\fP 94 except can only process a single read and write file descriptor at a time. 95 New integrators should use \fBares_process_fds(3)\fP if possible. 96 97 The \fBares_process(3)\fP function works in the same manner, except it works 98 on \fIfd_sets\fP as is used by \fBselect(3)\fP and retrieved by 99 \fBares_fds(3)\fP. This method is deprecated and should not be used in modern 100 applications due to known limitations to the \fBselect(3)\fP implementation. 101 102 .SH AVAILABILITY 103 \fBares_process_fds(3)\fP was introduced in c-ares 1.34.0. 104 105 .SH SEE ALSO 106 .BR ares_fds (3), 107 .BR ares_timeout (3), 108 .BR ares_init_options (3) 109 with \fIARES_OPT_EVENT_THREAD\fP or \fIARES_OPT_SOCK_STATE_CB\fP