1ARES_SET_SOCKET_FUNCTIONS(3)Library Functions ManualARES_SET_SOCKET_FUNCTIONS(3)
2
3
4

NAME

6       ares_set_socket_functions - Set socket io callbacks
7

SYNOPSIS

9       #include <ares.h>
10
11       struct ares_socket_functions {
12            ares_socket_t(*asocket)(int, int, int, void *);
13            int(*aclose)(ares_socket_t, void *);
14            int(*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *);
15            ares_ssize_t(*arecvfrom)(ares_socket_t, void *, size_t, int, struct sockaddr *, ares_socklen_t *, void *);
16            ares_ssize_t(*asendv)(ares_socket_t, const struct iovec *, int, void *);
17          };
18
19
20       void ares_set_socket_functions(ares_channel channel,
21                             const struct ares_socket_functions * functions,
22                             void *user_data);
23
24

DESCRIPTION

26       This  function sets a set of callback functions in the given ares chan‐
27       nel handle.  These callback functions will be invoked to create/destroy
28       socket  objects  and  perform io, instead of the normal system calls. A
29       client application can override normal network operation fully  through
30       this functionality, and provide its own transport layer.
31
32       All callback functions are expected to operate like their system equiv‐
33       alents, and to set errno(3) to an appropriate error code on failure. C-
34       ares also expects all io functions to behave asynchronously, i.e. as if
35       the socket object has been set to non-blocking  mode.  Thus  read/write
36       calls  (for  TCP  connections) are expected to often generate EAGAIN or
37       EWOULDBLOCK.
38
39
40       The user_data value is provided to each callback function invocation to
41       serve as context.
42
43       The ares_socket_functions must provide the following callbacks:
44
45       asocket           ares_socket_t(*)(int  domain, int type, int protocol,
46                         void * user_data)
47                         Creates an endpoint for communication and  returns  a
48                         descriptor.  domain,  type,  and protocol each corre‐
49                         spond to the parameters of socket(2).  Returns  ahan‐
50                         dle to the newly created socket, or -1 on error.
51
52       aclose            int(*)(ares_socket_t fd, void * user_data)
53                         Closes  the  socket  endpoint  indicated  by  fd. See
54                         close(2)
55
56       aconnect          int(*)(ares_socket_t  fd,  const  struct  sockaddr  *
57                         addr, ares_socklen_t addr_len, void * user_data)
58                         Initiate  a  connection  to  the address indicated by
59                         addr on a socket. See connect(2)
60
61
62       arecvfrom         ares_ssize_t(*)(ares_socket_t  fd,  void  *   buffer,
63                         size_t  buf_size,  int flags, struct sockaddr * addr,
64                         ares_socklen_t * addr_len, void * user_data)
65                         Receives data from remote socket endpoint, if  avail‐
66                         able.  If the addr parameter is not NULL and the con‐
67                         nection protocol provides  the  source  address,  the
68                         callback should fill this in. See recvfrom(2)
69
70
71       asendv            ares_ssize_t(*)(ares_socket_t  fd, const struct iovec
72                         * data, int len, void * user_data)
73                         Send data, as provided by the iovec  array  data,  to
74                         the socket endpoint. See writev(2),
75
76
77       The  ares_socket_functions  struct  provided is not copied but directly
78       referenced, and must thus remain valid through out the channels and any
79       created socket's lifetime.
80

AVAILABILITY

82       Added in c-ares 1.13.0
83

SEE ALSO

85       ares_init_options(3),   socket(2),   close(2),   connect(2),   recv(2),
86       recvfrom(2), send(2), writev(2)
87

AUTHOR

89       Carl Wilund
90
91
92
93                                  13 Dec 2016     ARES_SET_SOCKET_FUNCTIONS(3)
Impressum