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