|
jpayne@68
|
1 .\"
|
|
jpayne@68
|
2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
|
|
jpayne@68
|
3 .\" SPDX-License-Identifier: MIT
|
|
jpayne@68
|
4 .\"
|
|
jpayne@68
|
5 .TH ARES_FDS 3 "23 July 1998"
|
|
jpayne@68
|
6 .SH NAME
|
|
jpayne@68
|
7 ares_fds \- return file descriptors to select on (deprecated)
|
|
jpayne@68
|
8 .SH SYNOPSIS
|
|
jpayne@68
|
9 .nf
|
|
jpayne@68
|
10 #include <ares.h>
|
|
jpayne@68
|
11
|
|
jpayne@68
|
12 int ares_fds(const ares_channel_t *\fIchannel\fP,
|
|
jpayne@68
|
13 fd_set *\fIread_fds\fP,
|
|
jpayne@68
|
14 fd_set *\fIwrite_fds\fP)
|
|
jpayne@68
|
15 .fi
|
|
jpayne@68
|
16 .SH DESCRIPTION
|
|
jpayne@68
|
17 See the \fBNOTES\fP section on issues with this function and alternatives.
|
|
jpayne@68
|
18
|
|
jpayne@68
|
19 The \fBares_fds(3)\fP function retrieves the set of file descriptors which the
|
|
jpayne@68
|
20 calling application should \fBselect(2)\fP on for reading and writing for the
|
|
jpayne@68
|
21 processing of name service queries pending on the name service channel
|
|
jpayne@68
|
22 identified by \fIchannel\fP. Should not be used with \fBARES_OPT_EVENT_THREAD\fP
|
|
jpayne@68
|
23 is passed to \fIares_init_options(3)\fP.
|
|
jpayne@68
|
24
|
|
jpayne@68
|
25 File descriptors will be set in the file descriptor sets pointed to by
|
|
jpayne@68
|
26 \fIread_fds\fP and \fIwrite_fds\fP as appropriate. File descriptors already
|
|
jpayne@68
|
27 set in \fIread_fds\fP and \fIwrite_fds\fP will remain set; initialization of
|
|
jpayne@68
|
28 the file descriptor sets (using \fBFD_ZERO\fP) is the responsibility of the
|
|
jpayne@68
|
29 caller.
|
|
jpayne@68
|
30 .SH RETURN VALUES
|
|
jpayne@68
|
31 \fBares_fds(3)\fP returns a value that is one greater than the number of the
|
|
jpayne@68
|
32 highest socket set in either \fIread_fds\fP or \fIwrite_fds\fP. If no queries
|
|
jpayne@68
|
33 are active, \fBares_fds(3)\fP returns 0.
|
|
jpayne@68
|
34
|
|
jpayne@68
|
35 .SH NOTES
|
|
jpayne@68
|
36 The \fBselect(2)\fP call which takes the \fIfd_set\fP parameter has significant
|
|
jpayne@68
|
37 limitations which can impact modern systems. The limitations can vary from
|
|
jpayne@68
|
38 system to system, but in general if the file descriptor value itself is greater
|
|
jpayne@68
|
39 than 1024 (not the count but the actual value), this can lead to
|
|
jpayne@68
|
40 \fBares_fds(3)\fP writing out of bounds which will cause a system crash. In
|
|
jpayne@68
|
41 modern networking clients, it is not unusual to have file descriptor values
|
|
jpayne@68
|
42 above 1024, especially when a library is pulled in as a dependency into a larger
|
|
jpayne@68
|
43 project.
|
|
jpayne@68
|
44
|
|
jpayne@68
|
45 c-ares does not attempt to detect this condition to prevent crashes due to both
|
|
jpayne@68
|
46 implementation-defined behavior in the OS as well as integrator-controllable
|
|
jpayne@68
|
47 tunables which may impact the limits.
|
|
jpayne@68
|
48
|
|
jpayne@68
|
49 It is recommended to use \fBARES_OPT_EVENT_THREAD\fP passed to
|
|
jpayne@68
|
50 \fIares_init_options(3)\fP, or socket state callbacks
|
|
jpayne@68
|
51 (\fBARES_OPT_SOCK_STATE_CB\fP) registered via \fIares_init_options(3)\fP and use
|
|
jpayne@68
|
52 more modern methods to check for socket readable/writable state such as
|
|
jpayne@68
|
53 \fIpoll(2)\fP, \fIepoll(2)\fP, or \fIkqueue(2)\fP.
|
|
jpayne@68
|
54 .SH SEE ALSO
|
|
jpayne@68
|
55 .BR ares_init_options (3),
|
|
jpayne@68
|
56 .BR ares_timeout (3),
|
|
jpayne@68
|
57 .BR ares_process (3)
|
