1ARES_SET_SOCKET_FUNCTIONS(3)Library Functions ManualARES_SET_SOCKET_FUNCTIONS(3)
2
6 ares_set_socket_functions - Set socket io callbacks
7
9 #include <ares.h>
10 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,
16 struct sockaddr *, ares_socklen_t *, void *);
17 ares_ssize_t (*asendv)(ares_socket_t, const struct iovec *, int, void *);
18 };
19 void ares_set_socket_functions(ares_channel channel,
21 const struct ares_socket_functions * functions,
22 void *user_data);
23
25 This function sets a set of callback functions in the given ares chan‐
26 nel handle. These callback functions will be invoked to create/destroy
27 socket objects and perform io, instead of the normal system calls. A
28 client application can override normal network operation fully through
29 this functionality, and provide its own transport layer. You can choose
30 to only implement some of the socket functions, and provide NULL to any
31 others and c-ares will use its built-in system functions in that case.
32 All callback functions are expected to operate like their system equiv‐
34 alents, and to set errno(3) to an appropriate error code on failure. C-
35 ares also expects all io functions to behave asynchronously, i.e. as if
36 the socket object has been set to non-blocking mode. Thus read/write
37 calls (for TCP connections) are expected to often generate EAGAIN or
38 EWOULDBLOCK.
39 The user_data value is provided to each callback function invocation to
42 serve as context.
43 The ares_socket_functions must provide the following callbacks:
45 asocket ares_socket_t(*)(int domain, int type, int protocol,
47 void * user_data)
48 Creates an endpoint for communication and returns a
49 descriptor. domain, type, and protocol each corre‐
50 spond to the parameters of socket(2). Returns ahan‐
51 dle to the newly created socket, or -1 on error.
52 aclose int(*)(ares_socket_t fd, void * user_data)
54 Closes the socket endpoint indicated by fd. See
55 close(2)
56 aconnect int(*)(ares_socket_t fd, const struct sockaddr *
58 addr, ares_socklen_t addr_len, void * user_data)
59 Initiate a connection to the address indicated by
60 addr on a socket. See connect(2)
61 arecvfrom ares_ssize_t(*)(ares_socket_t fd, void * buffer,
64 size_t buf_size, int flags, struct sockaddr * addr,
65 ares_socklen_t * addr_len, void * user_data)
66 Receives data from remote socket endpoint, if avail‐
67 able. If the addr parameter is not NULL and the con‐
68 nection protocol provides the source address, the
69 callback should fill this in. See recvfrom(2)
70 asendv ares_ssize_t(*)(ares_socket_t fd, const struct iovec
73 * data, int len, void * user_data)
74 Send data, as provided by the iovec array data, to
75 the socket endpoint. See writev(2),
76 The ares_socket_functions struct provided is not copied but directly
79 referenced, and must thus remain valid through out the channels and any
80 created socket's lifetime.
81
83 Added in c-ares 1.13.0
84
86 ares_init_options(3), socket(2), close(2), connect(2), recv(2),
87 recvfrom(2), send(2), writev(2)
88
90 Carl Wilund
91 13 Dec 2016 ARES_SET_SOCKET_FUNCTIONS(3)