From 95c6d70a6ec6f5d22157cc1afd642f831595a607 Mon Sep 17 00:00:00 2001 From: Brad House Date: Tue, 16 Jan 2024 10:09:04 -0500 Subject: [PATCH] man ares_fds(3): mark as deprecated and add explanation (#691) ares_fds(3) is not safe to use, mark as deprecated. Fixes Issue: #687 Fix By: Brad House (@bradh352) --- docs/ares_fds.3 | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/ares_fds.3 b/docs/ares_fds.3 index bbb6b2e8..8e22aa04 100644 --- a/docs/ares_fds.3 +++ b/docs/ares_fds.3 @@ -1,34 +1,23 @@ .\" .\" Copyright 1998 by the Massachusetts Institute of Technology. -.\" -.\" Permission to use, copy, modify, and distribute this -.\" software and its documentation for any purpose and without -.\" fee is hereby granted, provided that the above copyright -.\" notice appear in all copies and that both that copyright -.\" notice and this permission notice appear in supporting -.\" documentation, and that the name of M.I.T. not be used in -.\" advertising or publicity pertaining to distribution of the -.\" software without specific, written prior permission. -.\" M.I.T. makes no representations about the suitability of -.\" this software for any purpose. It is provided "as is" -.\" without express or implied warranty. -.\" .\" SPDX-License-Identifier: MIT .\" .TH ARES_FDS 3 "23 July 1998" .SH NAME -ares_fds \- return file descriptors to select on +ares_fds \- return file descriptors to select on. Deprecated. .SH SYNOPSIS .nf #include int ares_fds(ares_channel_t *\fIchannel\fP, fd_set *\fIread_fds\fP, - fd_set *\fIwrite_fds\fP) + fd_set *\fIwrite_fds\fP) .fi .SH DESCRIPTION +See the \fBNOTES\fP section on issues with this function and alternatives. + The \fBares_fds(3)\fP function retrieves the set of file descriptors which the -calling application should select on for reading and writing for the +calling application should \fBselect(2)\fP on for reading and writing for the processing of name service queries pending on the name service channel identified by \fIchannel\fP. @@ -41,6 +30,25 @@ caller. \fBares_fds(3)\fP returns a value that is one greater than the number of the highest socket set in either \fIread_fds\fP or \fIwrite_fds\fP. If no queries are active, \fBares_fds(3)\fP returns 0. + +.SH NOTES +The \fBselect(2)\fP call which takes the \fIfd_set\fP parameter has significant +limitations which can impact modern systems. The limitations can vary from +system to system, but in general if the file descriptor value itself is greater +than 1024 (not the count but the actual value), this can lead to +\fBares_fds(3)\fP writing out of bounds which will cause a system crash. In +modern networking clients, it is not unusual to have file descriptor values +above 1024, especially when a library is pulled in as a dependency into a larger +project. + +c-ares does not attempt to detect this condition to prevent crashes due to both +implementation-defined behavior in the OS as well as integrator-controllable +tunables which may impact the limits. + +It is recommended to use socket state callbacks (\fBARES_OPT_SOCK_STATE_CB\fP) +registered via \fBares_init_options(3)\fP, and use more modern methods to +check for socket readable/writable state such as \fBpoll(2)\fP, \fBepoll(2)\fP, +or \fBkqueue(2)\fP. .SH SEE ALSO .BR ares_timeout (3), .BR ares_process (3)