ares_getsock.3

   1 .\"
   2 .\" Copyright 1998 by Daniel Stenberg
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this
   5 .\" software and its documentation for any purpose and without
   6 .\" fee is hereby granted, provided that the above copyright
   7 .\" notice appear in all copies and that both that copyright
   8 .\" notice and this permission notice appear in supporting
   9 .\" documentation, and that the name of M.I.T. not be used in
  10 .\" advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.
  12 .\" M.I.T. makes no representations about the suitability of
  13 .\" this software for any purpose.  It is provided "as is"
  14 .\" without express or implied warranty.
  15 .\"
  16 .TH ARES_GETSOCK 3 "11 March 2010"
  17 .SH NAME
  18 ares_getsock \- get socket descriptors to wait on
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B int ares_getsock(ares_channel \fIchannel\fP, ares_socket_t *\fIsocks\fP,
  24 .B int \fInumsocks\fP);
  25 .fi
  26 .SH DESCRIPTION
  27 The
  28 .B ares_getsock
  29 function retrieves the set of socket descriptors which the calling
  30 application should wait on for reading and/or writing for the
  31 processing of name service queries pending on the name service channel
  32 identified by
  33 .IR channel .
  34 Socket descriptors will be set in the socket descriptor array pointed to by
  35 \fIsocks\fP.
  36 \fInumsocks\fP is the size of the given array in number of ints.
  37
  38 This function can only return information about up to 16 sockets. If more are
  39 in use (however unlikely that is), they are simply not reported back.
  40 .SH RETURN VALUES
  41 \fBares_getsock\fP returns a bitmask for what actions to wait for on the
  42 different sockets. The ares.h header file provides these convenience macros to
  43 extract the information appropriately:
  44
  45 .nf
  46 #define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about
  47                                   this many sockets */
  48 #define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num)))
  49 #define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \
  50                                          ARES_GETSOCK_MAXNUM)))
  51 .fi
  52 .SH NOTES
  53 This function was added in c-ares 1.3.1
  54 .SH SEE ALSO
  55 .BR ares_timeout (3),
  56 .BR ares_fds (3),
  57 .BR ares_process (3)