jpayne@68: .\"
jpayne@68: .\" Copyright 1998 by the Massachusetts Institute of Technology.
jpayne@68: .\" SPDX-License-Identifier: MIT
jpayne@68: .\"
jpayne@68: .TH ARES_FDS 3 "23 July 1998"
jpayne@68: .SH NAME
jpayne@68: ares_fds \- return file descriptors to select on (deprecated)
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: #include <ares.h>
jpayne@68: 
jpayne@68: int ares_fds(const ares_channel_t *\fIchannel\fP,
jpayne@68:              fd_set *\fIread_fds\fP,
jpayne@68:              fd_set *\fIwrite_fds\fP)
jpayne@68: .fi
jpayne@68: .SH DESCRIPTION
jpayne@68: See the \fBNOTES\fP section on issues with this function and alternatives.
jpayne@68: 
jpayne@68: The \fBares_fds(3)\fP function retrieves the set of file descriptors which the
jpayne@68: calling application should \fBselect(2)\fP on for reading and writing for the
jpayne@68: processing of name service queries pending on the name service channel
jpayne@68: identified by \fIchannel\fP.  Should not be used with \fBARES_OPT_EVENT_THREAD\fP
jpayne@68: is passed to \fIares_init_options(3)\fP.
jpayne@68: 
jpayne@68: File descriptors will be set in the file descriptor sets pointed to by
jpayne@68: \fIread_fds\fP and \fIwrite_fds\fP as appropriate.  File descriptors already
jpayne@68: set in \fIread_fds\fP and \fIwrite_fds\fP will remain set; initialization of
jpayne@68: the file descriptor sets (using \fBFD_ZERO\fP) is the responsibility of the
jpayne@68: caller.
jpayne@68: .SH RETURN VALUES
jpayne@68: \fBares_fds(3)\fP returns a value that is one greater than the number of the
jpayne@68: highest socket set in either \fIread_fds\fP or \fIwrite_fds\fP.  If no queries
jpayne@68: are active, \fBares_fds(3)\fP returns 0.
jpayne@68: 
jpayne@68: .SH NOTES
jpayne@68: The \fBselect(2)\fP call which takes the \fIfd_set\fP parameter has significant
jpayne@68: limitations which can impact modern systems.  The limitations can vary from
jpayne@68: system to system, but in general if the file descriptor value itself is greater
jpayne@68: than 1024 (not the count but the actual value), this can lead to
jpayne@68: \fBares_fds(3)\fP writing out of bounds which will cause a system crash.  In
jpayne@68: modern networking clients, it is not unusual to have file descriptor values
jpayne@68: above 1024, especially when a library is pulled in as a dependency into a larger
jpayne@68: project.
jpayne@68: 
jpayne@68: c-ares does not attempt to detect this condition to prevent crashes due to both
jpayne@68: implementation-defined behavior in the OS as well as integrator-controllable
jpayne@68: tunables which may impact the limits.
jpayne@68: 
jpayne@68: It is recommended to use \fBARES_OPT_EVENT_THREAD\fP passed to
jpayne@68: \fIares_init_options(3)\fP, or socket state callbacks
jpayne@68: (\fBARES_OPT_SOCK_STATE_CB\fP) registered via \fIares_init_options(3)\fP and use
jpayne@68: more modern methods to check for socket readable/writable state such as
jpayne@68: \fIpoll(2)\fP, \fIepoll(2)\fP, or \fIkqueue(2)\fP.
jpayne@68: .SH SEE ALSO
jpayne@68: .BR ares_init_options (3),
jpayne@68: .BR ares_timeout (3),
jpayne@68: .BR ares_process (3)