ares_set_socket_functions.3 (13268B)
1 .\" Copyright (C) Daniel Stenberg 2 .\" SPDX-License-Identifier: MIT 3 .TH ARES_SET_SOCKET_FUNCTIONS 3 "8 Oct 2024" 4 .SH NAME 5 ares_set_socket_functions, ares_set_socket_functions_ex \- Set socket io callbacks 6 .SH SYNOPSIS 7 .nf 8 #include <ares.h> 9 10 typedef enum { 11 ARES_SOCKFUNC_FLAG_NONBLOCKING = 1 << 0 12 } ares_sockfunc_flags_t; 13 14 typedef enum { 15 ARES_SOCKET_OPT_SENDBUF_SIZE, 16 ARES_SOCKET_OPT_RECVBUF_SIZE, 17 ARES_SOCKET_OPT_BIND_DEVICE, 18 ARES_SOCKET_OPT_TCP_FASTOPEN 19 } ares_socket_opt_t; 20 21 typedef enum { 22 ARES_SOCKET_CONN_TCP_FASTOPEN = 1 << 0 23 } ares_socket_connect_flags_t; 24 25 typedef enum { 26 ARES_SOCKET_BIND_TCP = 1 << 0, 27 ARES_SOCKET_BIND_CLIENT = 1 << 1 28 } ares_socket_bind_flags_t; 29 30 struct ares_socket_functions_ex { 31 unsigned int version; /* ABI Version: must be "1" */ 32 unsigned int flags; 33 34 ares_socket_t (*asocket)(int domain, int type, int protocol, void *user_data); 35 int (*aclose)(ares_socket_t sock, void *user_data); 36 int (*asetsockopt)(ares_socket_t sock, ares_socket_opt_t opt, const void *val, 37 ares_socklen_t val_size, void *user_data); 38 int (*aconnect)(ares_socket_t sock, const struct sockaddr *address, 39 ares_socklen_t address_len, unsigned int flags, 40 void *user_data); 41 ares_ssize_t (*arecvfrom)(ares_socket_t sock, void *buffer, size_t length, 42 int flags, struct sockaddr *address, 43 ares_socklen_t *address_len, void *user_data); 44 ares_ssize_t (*asendto)(ares_socket_t sock, const void *buffer, size_t length, 45 int flags, const struct sockaddr *address, 46 ares_socklen_t address_len, void *user_data); 47 int (*agetsockname)(ares_socket_t sock, struct sockaddr *address, 48 ares_socklen_t *address_len, void *user_data); 49 int (*abind)(ares_socket_t sock, unsigned int flags, 50 const struct sockaddr *address, socklen_t address_len, 51 void *user_data); 52 unsigned int (*aif_nametoindex)(const char *ifname, void *user_data); 53 const char *(*aif_indextoname)(unsigned int ifindex, char *ifname_buf, 54 size_t ifname_buf_len, void *user_data); 55 }; 56 57 ares_status_t ares_set_socket_functions_ex(ares_channel_t *channel, 58 const struct ares_socket_functions_ex *funcs, void *user_data); 59 60 61 struct ares_socket_functions { 62 ares_socket_t (*\fIasocket\fP)(int, int, int, void *); 63 int (*\fIaclose\fP)(ares_socket_t, void *); 64 int (*\fIaconnect\fP)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *); 65 ares_ssize_t (*\fIarecvfrom\fP)(ares_socket_t, void *, size_t, int, 66 struct sockaddr *, ares_socklen_t *, void *); 67 ares_ssize_t (*\fIasendv\fP)(ares_socket_t, const struct iovec *, int, void *); 68 }; 69 70 void ares_set_socket_functions(ares_channel_t *\fIchannel\fP, 71 const struct ares_socket_functions * \fIfunctions\fP, 72 void *\fIuser_data\fP); 73 .fi 74 .SH DESCRIPTION 75 .PP 76 77 \fBares_set_socket_functions_ex(3)\fP sets a set of callback \fIfunctions\fP in 78 the given ares channel handle. Cannot be used when \fBARES_OPT_EVENT_THREAD\fP 79 is passed to \fIares_init_options(3)\fP. This function replaces the now 80 deprecated \fBares_set_socket_functions(3)\fP call. 81 82 These callback functions will be invoked to create/destroy socket objects and 83 perform io, instead of the normal system calls. A client application can 84 override normal network operation fully through this functionality, and provide 85 its own transport layer. 86 87 Some callbacks may be optional and are documented as such below, but failing 88 to implement such callbacks will disable certain features within c-ares. It 89 is strongly recommended to implement all callbacks. 90 91 All callback functions are expected to operate like their system equivalents, 92 and to set \fBerrno(2)\fP or \fBWSASetLastError(2)\fP to an appropriate error 93 code on failure. It is strongly recommended that io callbacks are implemented 94 to be asynchronous and indicated as such in the \fIflags\fP member. The io 95 callbacks can return error codes of \fBEAGAIN\fP, \fBEWOULDBLOCK\fP, or 96 \fBWSAEWOULDBLOCK\fP when they would otherwise block. 97 98 The \fIuser_data\fP value is provided to each callback function invocation to 99 serve as context. 100 101 The \fBares_set_socket_functions_ex(3)\fP must provide the following structure 102 members and callbacks (which are different from the 103 \fBares_set_socket_functions(3)\fP members and callbacks): 104 105 .RS 4 106 .TP 8 107 .B unsigned int \fIversion\fP 108 .br 109 ABI Version of structure. Must be set to a value of "1". 110 111 .TP 8 112 .B unsigned int \fIflags\fP 113 .br 114 Flags available are specified in \fIares_sockfunc_flags_t\fP. 115 116 .TP 8 117 .B ares_socket_t (*\fIasocket\fP)(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, void * \fIuser_data\fP) 118 .br 119 \fIREQUIRED\fP. Creates an endpoint for communication and returns a descriptor. \fIdomain\fP, 120 \fItype\fP, and \fIprotocol\fP each correspond to the parameters of 121 \fBsocket(2)\fP. Returns a handle to the newly created socket, or 122 \fBARES_SOCKET_BAD\fP on error. 123 124 .TP 8 125 .B int (*\fIaclose\fP)(ares_socket_t \fIfd\fP, void * \fIuser_data\fP) 126 .br 127 \fIREQUIRED\fP. Closes the socket endpoint indicated by \fIfd\fP. See \fBclose(2)\fP. 128 129 .TP 8 130 .B int (*\fIasetsockopt\fP)(ares_socket_t \fIfd\fP, ares_socket_opt_t \fIopt\fP, const void * \fIval\fP, ares_socklen_t \fIval_size\fP, void * \fIuser_data\fP) 131 .br 132 \fIREQUIRED\fP. Set socket option. This shares a similar syntax to the BSD \fIsetsockopt(2)\fP 133 call, however c-ares uses different options for portability. The value is 134 a pointer to the desired value, and each option has its own data type listed 135 in the options below defined in \fIares_socket_opt_t\fP. 136 137 .TP 8 138 .B int (*\fIaconnect\fP)(ares_socket_t \fIfd\fP, const struct sockaddr * \fIaddr\fP, ares_socklen_t \fIaddr_len\fP, unsigned int \fIflags\fP, void * \fIuser_data\fP) 139 .br 140 \fIREQUIRED\fP. Initiate a connection to the address indicated by \fIaddr\fP on 141 a socket. Additional flags controlling behavior are in 142 \fIares_socket_connect_flags_t\fP. See \fBconnect(2)\fP. 143 144 .TP 8 145 .B ares_ssize_t (*\fIarecvfrom\fP)(ares_socket_t \fIfd\fP, void * \fIbuffer\fP, size_t \fIbuf_size\fP, int \fIflags\fP, struct sockaddr * \fIaddr\fP, ares_socklen_t * \fIaddr_len\fP, void * \fIuser_data\fP) 146 .br 147 \fIREQUIRED\fP. Receives data from remote socket endpoint, if available. If the 148 \fIaddr\fP parameter is not NULL and the connection protocol provides the source 149 address, the callback should fill this in. The \fIflags\fP parameter is 150 currently unused. See \fBrecvfrom(2)\fP. 151 152 .TP 8 153 .B ares_ssize_t (*\fIasendto\fP)(ares_socket_t \fIfd\fP, const void * \fIbuffer\fP, size_t \fIlength\fP, int \fIflags\fP, const struct sockaddr * \fIaddress\fP, ares_socklen_t \fIaddress_len\fP, void * \fIuser_data\fP) 154 .br 155 \fIREQUIRED\fP. Send data, as provided by the \fIbuffer\fP, to the socket 156 endpoint. The \fIflags\fP member may be used on systems that have 157 \fBMSG_NOSIGNAL\fP defined but is otherwise unused. An \fIaddress\fP is 158 provided primarily to support TCP FastOpen scenarios, which will be NULL in 159 other circumstances. See \fBsendto(2)\fP. 160 161 .TP 8 162 .B int (*\fIagetsockname\fP)(ares_socket_t \fIfd\fP, struct sockaddr * \fIaddress\fP, ares_socklen_t * \fIaddress_len\fP, void * \fIuser_data\fP) 163 .br 164 \fIOptional\fP. Retrieve the local address of a socket and store it into the provided 165 \fIaddress\fP buffer. May impact DNS Cookies if not provided. See 166 \fBgetsockname(2)\fP. 167 168 .TP 8 169 .B int (*\fIabind\fP)(ares_socket_t \fIfd\fP, unsigned int \fIflags\fP, const struct sockaddr * \fIaddress\fP, ares_socklen_t \fIaddress_len\fP, void * \fIuser_data\fP) 170 .br 171 \fIOptional\fP. Bind the socket to an address. This can be used for client 172 connections to bind the source address for packets before connect, or 173 for server connections to bind to an address and port before listening. 174 Currently c-ares only supports client connections. \fIflags\fP from 175 \fIares_socket_bind_flags_t\fP can be specified. See \fBbind(2)\fP. 176 177 .TP 8 178 .B unsigned int (*\fIaif_nametoindex\fP)(const char * \fIifname\fP, void * \fIuser_data\fP) 179 .br 180 \fIOptional\fP. Convert an interface name into the interface index. If this 181 callback is not specified, then IPv6 Link-Local DNS servers cannot be used. 182 See \fBif_nametoindex(2)\fP. 183 184 .TP 8 185 .B const char * (*\fIaif_indextoname\fP)(unsigned int \fIifindex\fP, char * \fIifname_buf\fP, size_t \fIifname_buf_len\fP, void * \fIuser_data\fP) 186 .br 187 \fIOptional\fP. Convert an interface index into the interface name. If this 188 callback is not specified, then IPv6 Link-Local DNS servers cannot be used. 189 \fIifname_buf\fP must be at least \fBIF_NAMESIZE\fP or \fBIFNAMSIZ\fP in size. 190 See \fBif_indextoname(2)\fP. 191 .RE 192 193 .PP 194 \fBares_sockfunc_flags_t\fP values: 195 196 .RS 4 197 .TP 8 198 .B \fIARES_SOCKFUNC_FLAG_NONBLOCKING\fP 199 .br 200 Used to indicate the implementation of the io functions are asynchronous. 201 .RE 202 203 .PP 204 \fBares_socket_opt_t\fP values: 205 206 .RS 4 207 .TP 8 208 .B \fIARES_SOCKET_OPT_SENDBUF_SIZE\fP 209 .br 210 Set the Send Buffer size. Value is a pointer to an int. (SO_SNDBUF). 211 212 .TP 8 213 .B \fIARES_SOCKET_OPT_RECVBUF_SIZE\fP 214 .br 215 Set the Receive Buffer size. Value is a pointer to an int. (SO_RCVBUF). 216 217 .TP 8 218 .B \fIARES_SOCKET_OPT_BIND_DEVICE\fP 219 .br 220 Set the network interface to use as the source for communication. Value is a C 221 string. (SO_BINDTODEVICE) 222 223 .TP 8 224 .B \fIARES_SOCKET_OPT_TCP_FASTOPEN\fP 225 .br 226 Enable TCP Fast Open. Value is a pointer to an \fIares_bool_t\fP. On some 227 systems this could be a no-op if it is known it is on by default and 228 return success. Other systems may be a no-op if known the system does 229 not support the feature and returns failure with errno set to \fBENOSYS\fP or 230 \fBWSASetLastError(WSAEOPNOTSUPP);\fP. 231 .RE 232 233 .PP 234 \fBares_socket_connect_flags_t\fP values: 235 .RS 4 236 .TP 8 237 .B \fIARES_SOCKET_CONN_TCP_FASTOPEN\fP 238 .br 239 Connect using TCP Fast Open. 240 .RE 241 242 .PP 243 \fBares_socket_bind_flags_t\fP values: 244 245 .RS 4 246 .TP 8 247 .B \fIARES_SOCKET_BIND_TCP\fP 248 .br 249 Bind is for a TCP connection. 250 251 .TP 19 252 .B \fIARES_SOCKET_BIND_CLIENT\fP 253 .br 254 Bind is for a client connection, not server. 255 .RE 256 257 .PP 258 259 \fBares_set_socket_functions(3)\fP sets a set of callback \fIfunctions\fP in the 260 given ares channel handle. Cannot be used when \fBARES_OPT_EVENT_THREAD\fP is 261 passed to \fIares_init_options(3)\fP. This function is deprecated as of 262 c-ares 1.34.0 in favor of \fIares_set_socket_functions_ex(3)\fP. 263 264 \fBares_set_socket_functions(3)\fP allows you to choose to only implement 265 some of the socket functions, and provide NULL to any others and c-ares will use 266 its built-in system functions in that case. 267 268 .PP 269 All callback functions are expected to operate like their system equivalents, 270 and to set \fBerrno(2)\fP or \fBWSASetLastError(2)\fP to an appropriate error 271 code on failure. It is strongly recommended all io functions behave 272 asynchronously and return error codes of \fBEAGAIN\fP, \fBEWOULDBLOCK\fP, or 273 \fBWSAEWOULDBLOCK\fP when they would otherwise block. 274 275 .PP 276 The \fIuser_data\fP value is provided to each callback function invocation to 277 serve as context. 278 .PP 279 The \fBares_set_socket_functions(3)\fP must provide the following callbacks (which 280 are different from the \fBares_set_socket_functions_ex(3)\fP callbacks): 281 282 .RS 4 283 .TP 8 284 .B ares_socket_t (*\fIasocket\fP)(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, void * \fIuser_data\fP) 285 .br 286 Creates an endpoint for communication and returns a descriptor. \fIdomain\fP, \fItype\fP, and \fIprotocol\fP 287 each correspond to the parameters of \fBsocket(2)\fP. Returns ahandle to the 288 newly created socket, or ARES_SOCKET_BAD on error. 289 290 .TP 8 291 .B int (*\fIaclose\fP)(ares_socket_t \fIfd\fP, void * \fIuser_data\fP) 292 .br 293 Closes the socket endpoint indicated by \fIfd\fP. See \fBclose(2)\fP. 294 295 .TP 8 296 .B int (*\fIaconnect\fP)(ares_socket_t \fIfd\fP, const struct sockaddr * \fIaddr\fP, ares_socklen_t \fIaddr_len\fP, void * \fIuser_data\fP) 297 .br 298 Initiate a connection to the address indicated by \fIaddr\fP on a socket. See 299 \fBconnect(2)\fP 300 301 .TP 8 302 .B ares_ssize_t (*\fIarecvfrom\fP)(ares_socket_t \fIfd\fP, void * \fIbuffer\fP, size_t \fIbuf_size\fP, int \fIflags\fP, struct sockaddr * \fIaddr\fP, ares_socklen_t * \fIaddr_len\fP, void * \fIuser_data\fP) 303 .br 304 Receives data from remote socket endpoint, if available. If the \fIaddr\fP 305 parameter is not NULL and the connection protocol provides the source address, 306 the callback should fill this in. See \fBrecvfrom(2)\fP 307 308 .TP 8 309 .B ares_ssize_t (*\fIasendv\fP)(ares_socket_t \fIfd\fP, const struct iovec * \fIdata\fP, int \fIlen\fP, void * \fIuser_data\fP) 310 .br 311 Send data, as provided by the iovec array \fIdata\fP, to the socket endpoint. 312 See \fBwritev(2)\fP 313 .RE 314 315 .PP 316 The \fBares_set_socket_functions(3)\fP struct provided is not copied but directly 317 referenced, and must thus remain valid through out the channels and any created 318 socket's lifetime. However, the \fBares_set_socket_functions_ex(3)\fP struct is 319 duplicated and does not need to survive past the call to the function. 320 321 .SH AVAILABILITY 322 ares_socket_functions added in c-ares 1.13.0, ares_socket_functions_ex added in 323 c-ares 1.34.0 324 .SH SEE ALSO 325 .BR ares_init_options (3), 326 .BR socket (2), 327 .BR close (2), 328 .BR connect (2), 329 .BR recvfrom (2), 330 .BR sendto (2), 331 .BR bind (2), 332 .BR getsockname (2), 333 .BR setsockopt (2), 334 .BR writev (2)