noble (3) ares_fds.3.gz

NAME

       ares_fds - return file descriptors to select on (deprecated)

SYNOPSIS

       #include <ares.h>

       int ares_fds(ares_channel_t *channel,
                    fd_set *read_fds,
                    fd_set *write_fds)

DESCRIPTION

       See the NOTES section on issues with this function and alternatives.

       The  ares_fds(3)  function  retrieves  the  set  of file descriptors which the calling application should
       select(2) on for reading and writing for the processing of name  service  queries  pending  on  the  name
       service  channel  identified  by  channel.   Should  not  be used with ARES_OPT_EVENT_THREAD is passed to
       ares_init_options(3).

       File descriptors will be set in the file  descriptor  sets  pointed  to  by  read_fds  and  write_fds  as
       appropriate.   File  descriptors already set in read_fds and write_fds will remain set; initialization of
       the file descriptor sets (using FD_ZERO) is the responsibility of the caller.

RETURN VALUES

       ares_fds(3) returns a value that is one greater than the number of  the  highest  socket  set  in  either
       read_fds or write_fds.  If no queries are active, ares_fds(3) returns 0.

NOTES

       The  select(2)  call which takes the fd_set 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 ares_fds(3) 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 ARES_OPT_EVENT_THREAD passed to ares_init_options(3), or socket state callbacks
       (ARES_OPT_SOCK_STATE_CB) registered via ares_init_options(3) and use more modern  methods  to  check  for
       socket readable/writable state such as poll(2), epoll(2), or kqueue(2).

SEE ALSO

       ares_init_options(3), ares_timeout(3), ares_process(3)

AUTHOR

       Greg Hudson, MIT Information Systems
       Copyright 1998 by the Massachusetts Institute of Technology.

                                                  23 July 1998                                       ARES_FDS(3)