Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/ares_process.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
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