ares_set_socket_functions - Set socket io callbacks
#include <ares.h>
struct ares_socket_functions {
ares_socket_t(*asocket)(int, int, int, void *);
int(*aclose)(ares_socket_t, void *);
int(*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *);
ares_ssize_t(*arecvfrom)(ares_socket_t, void *, size_t, int, struct sockaddr *, ares_socklen_t *, void *);
ares_ssize_t(*asendv)(ares_socket_t, const struct iovec *, int, void *);
};
void ares_set_socket_functions(ares_channel channel,
const struct ares_socket_functions * functions,
void *user_data);
Library Functions Manual ARES_SET_SOCKET_FUNCTIONS(3)
NAME
ares_set_socket_functions - Set socket io callbacks
SYNOPSIS
#include <ares.h>
struct ares_socket_functions {
ares_socket_t(*asocket)(int, int, int, void *);
int(*aclose)(ares_socket_t, void *);
int(*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *);
ares_ssize_t(*arecvfrom)(ares_socket_t, void *, size_t, int, struct sockaddr *, ares_socklen_t *, void *);
ares_ssize_t(*asendv)(ares_socket_t, const struct iovec *, int, void *);
};
void ares_set_socket_functions(ares_channel channel,
const struct ares_socket_functions * functions,
void *user_data);
DESCRIPTION
This function sets a set of callback functions in the given ares chan-
nel handle. These callback functions will be invoked to create/destroy
socket objects and perform io, instead of the normal system calls. A
client application can override normal network operation fully through
this functionality, and provide its own transport layer.
All callback functions are expected to operate like their system equiv-
alents, and to set errno(3) to an appropriate error code on failure. C-
ares also expects all io functions to behave asynchronously, i.e. as if
the socket object has been set to non-blocking mode. Thus read/write
calls (for TCP connections) are expected to often generate EAGAIN or
EWOULDBLOCK.
The user_data value is provided to each callback function invocation to
serve as context.
The ares_socket_functions must provide the following callbacks:
asocket ares_socket_t(*)(int domain, int type, int protocol,
void * user_data)
Creates an endpoint for communication and returns a
descriptor. domain, type, and protocol each corre-
spond to the parameters of socket(2). Returns ahan-
dle to the newly created socket, or -1 on error.
aclose int(*)(ares_socket_t fd, void * user_data)
Closes the socket endpoint indicated by fd. See
close(2)
aconnect int(*)(ares_socket_t fd, const struct sockaddr *
addr, ares_socklen_t addr_len, void * user_data)
Initiate a connection to the address indicated by
addr on a socket. See connect(2)
arecvfrom ares_ssize_t(*)(ares_socket_t fd, void * buffer,
size_t buf_size, int flags, struct sockaddr * addr,
ares_socklen_t * addr_len, void * user_data)
Receives data from remote socket endpoint, if avail-
able. If the addr parameter is not NULL and the con-
nection protocol provides the source address, the
callback should fill this in. See recvfrom(2)
asendv ares_ssize_t(*)(ares_socket_t fd, const struct iovec
* data, int len, void * user_data)
Send data, as provided by the iovec array data, to
the socket endpoint. See writev(2),
The ares_socket_functions struct provided is not copied but directly
referenced, and must thus remain valid through out the channels and any
created socket's lifetime.
AVAILABILITY
Added in c-ares 1.13.0
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/libcares |
+---------------+------------------+
|Stability | Volatile |
+---------------+------------------+
SEE ALSO
ares_init_options(3), socket(2), close(2), connect(2), recv(2),
recvfrom(2), send(2), writev(2)
AUTHOR
Carl Wilund
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://c-ares.haxx.se/download/c-
ares-1.17.2.tar.gz.
Further information about this software can be found on the open source
community website at https://c-ares.haxx.se/.
13 Dec 2016
ARES_SET_SOCKET_FUNCTIONS(3)