ares_getsock.3 (1913B)
1 .\" 2 .\" Copyright 1998 by Daniel Stenberg 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_GETSOCK 3 "11 March 2010" 6 .SH NAME 7 ares_getsock \- get socket descriptors to wait on (deprecated) 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 int ares_getsock(const ares_channel_t *\fIchannel\fP, ares_socket_t *\fIsocks\fP, 13 int \fInumsocks\fP); 14 .fi 15 .SH DESCRIPTION 16 The 17 .B ares_getsock 18 function retrieves the set of socket descriptors which the calling 19 application should wait on for reading and/or writing for the 20 processing of name service queries pending on the name service channel 21 identified by 22 .IR channel . 23 Socket descriptors will be set in the socket descriptor array pointed to by 24 \fIsocks\fP. 25 \fInumsocks\fP is the size of the given array in number of ints. 26 27 This function can only return information up to 16 sockets. If more are 28 in use, they are simply not reported back. 29 .SH RETURN VALUES 30 \fBares_getsock\fP returns a bitmask for what actions to wait for on the 31 different sockets. The ares.h header file provides these convenience macros to 32 extract the information appropriately: 33 34 .nf 35 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about 36 this many sockets */ 37 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num))) 38 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \ 39 ARES_GETSOCK_MAXNUM))) 40 .fi 41 .SH NOTES 42 This function was added in c-ares 1.3.1 and deprecated in c-ares 1.20.0 due to 43 the implementation of \fBARES_OPT_MAX_UDP_QUERIES\fP which makes it likely to 44 exceed 16 open file descriptors. 45 46 It is recommended to use \fBARES_OPT_EVENT_THREAD\fP passed to 47 \fIares_init_options(3)\fP or to use socket state callbacks 48 (\fBARES_OPT_SOCK_STATE_CB\fP) registered via \fBares_init_options(3)\fP. 49 .SH SEE ALSO 50 .BR ares_init_options (3), 51 .BR ares_timeout (3), 52 .BR ares_fds (3), 53 .BR ares_process (3)