Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ARES_PROCESS(3)		   Library Functions Manual	       ARES_PROCESS(3)

NAME
       ares_process_fds,  ares_process_fd,  ares_process  - Process events for
       name resolution

SYNOPSIS
       #include	<ares.h>

       /*! Events used by ares_fd_events_t */
       typedef enum {
	 ARES_FD_EVENT_NONE  = 0,      /*!< No events */
	 ARES_FD_EVENT_READ  = 1 << 0, /*!< Read event (including disconnect/error) */
	 ARES_FD_EVENT_WRITE = 1 << 1  /*!< Write event	*/
       } ares_fd_eventflag_t;

       /*! Type	holding	a file descriptor and mask of events, used by
	*  ares_process_fds() */
       typedef struct {
	 ares_socket_t fd;     /*!< File descriptor */
	 unsigned int  events; /*!< Mask of ares_fd_event_t */
       } ares_fd_events_t;

       typedef enum {
	 ARES_PROCESS_FLAG_NONE	       = 0,
	 ARES_PROCESS_FLAG_SKIP_NON_FD = 1 << 0
       } ares_process_flag_t;

       ares_status_t ares_process_fds(ares_channel_t	     *channel,
				      const ares_fd_events_t *events,
				      size_t		      nevents,
				      unsigned int	      flags)

       void ares_process_fd(ares_channel_t *channel,
			    ares_socket_t read_fd,
			    ares_socket_t write_fd)

       void ares_process(ares_channel_t	*channel,
			 fd_set	*read_fds,
			 fd_set	*write_fds)

DESCRIPTION
       These functions must be used by integrators choosing  not  to  use  the
       EventThread  enabled  via ARES_OPT_EVENT_THREAD passed to ares_init_op-
       tions.  This assumes integrators	already	have their own event loop han-
       dling event notifications for various file descriptors and wish	to  do
       the same	with their integration with c-ares.

       The  ares_process_fds(3)	 function  handles input/output	events on file
       descriptors and timeouts	associated with	queries	pending	on the channel
       identified by channel.  The file	descriptors to be processed are	passed
       in an array of ares_fd_events_t data structures in the fd  member,  and
       events  are  a bitwise mask of ares_fd_eventflag_t in the event member.
       This function can also be used to process timeouts by passing  NULL  to
       the events member with nevents value of 0.  Flags may also be specified
       in the flags field and are defined in ares_process_flag_t.

       ARES_PROCESS_FLAG_SKIP_NON_FD can be specified to specifically skip any
       processing  unrelated to	the file descriptor events passed in, examples
       include timeout processing and cleanup handling.	 This is useful	if  an
       integrator  knows they will be sending multiple ares_process_fds(3) re-
       quests and wants	to skip	that extra processing.	However, the  integra-
       tor must	send the final request with the	flag so	that timeout and other
       processing  gets	 performed before their	event loop waits on additional
       events.

       It is allowable to use an ares_fd_events_t with events member of	 value
       ARES_FD_EVENT_NONE (0) if there are no events for a given file descrip-
       tor if an integrator wishes to simply maintain an array with all	possi-
       ble file	descriptors and	update readiness via the event member.

       This function will return ARES_ENOMEM in	out of memory conditions, oth-
       erwise will return ARES_SUCCESS.

       This  function is recommended over ares_process_fd(3) since it can han-
       dle processing of multiple file descriptors at once, thus skipping  re-
       peating	additional logic such as timeout processing which would	be re-
       quired if calling ares_process_fd(3) for	multiple file descriptors  no-
       tified at the same time.

       This function is	typically used with the	ARES_OPT_SOCK_STATE_CB option.

       ares_timeout(3)	should	be  used  to retrieve the desired timeout, and
       when the	timeout	expires, the integrator	must call  ares_process_fds(3)
       with  a NULL events array. (or ares_process_fd(3) with both sockets set
       to ARES_SOCKET_BAD). There is no	need to	do this	if events are also de-
       livered for any file descriptors	as timeout processing  will  automati-
       cally	be   handled   by   any	  call	 to   ares_process_fds(3)   or
       ares_process_fd(3).

       The ares_process_fd(3) function is the same as ares_process_fds(3)  ex-
       cept  can  only	process	 a  single read	and write file descriptor at a
       time.  New integrators should use ares_process_fds(3) if	possible.

       The ares_process(3) function works in the same manner, except it	 works
       on  fd_sets as is used by select(3) and retrieved by ares_fds(3).  This
       method is deprecated and	should not be used in modern applications  due
       to known	limitations to the select(3) implementation.

AVAILABILITY
       ares_process_fds(3) was introduced in c-ares 1.34.0.

SEE ALSO
       ares_fds(3),	  ares_timeout(3),	ares_init_options(3)	  with
       ARES_OPT_EVENT_THREAD or	ARES_OPT_SOCK_STATE_CB

				 25 July 1998		       ARES_PROCESS(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ares_process_fds&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help