ares_fds.3 (2496B)
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)