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

@@ -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 <ares.h>
 
 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)