Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
ares_set_socket_functions: Add man page
Providing some rudimentary documentation for the added functionality Closes #72
- Loading branch information
Showing
1 changed file
with
98 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
.\" | ||
.TH ARES_SET_SOCKET_FUNCTIONS 3 "13 Dec 2016" | ||
.SH NAME | ||
ares_set_socket_functions \- Set socket io callbacks | ||
.SH SYNOPSIS | ||
.nf | ||
.B #include <ares.h> | ||
.PP | ||
.B struct ares_socket_functions { | ||
ares_socket_t(*\fIasocket\fP)(int, int, int, void *); | ||
int(*\fIaclose\fP)(ares_socket_t, void *); | ||
int(*\fIaconnect\fP)(ares_socket_t, const struct sockaddr *, socklen_t, void *); | ||
ssize_t(*\fIarecvfrom\fP)(ares_socket_t, void *, size_t, int, struct sockaddr *, socklen_t *, void *); | ||
ssize_t(*\fIasendv\fP)(ares_socket_t, const struct iovec *, int, void *); | ||
}; | ||
|
||
.PP | ||
.B void ares_set_socket_functions(ares_channel \fIchannel\fP, | ||
const struct ares_socket_functions * \fIfunctions\fP, | ||
void *\fIuser_data\fP); | ||
|
||
.fi | ||
.SH DESCRIPTION | ||
.PP | ||
This function sets a set of callback \fIfunctions\fP in the given ares channel 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. | ||
.PP | ||
All callback functions are expected to operate like their system equivalents, and to | ||
set | ||
.BR 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 | ||
.BR EAGAIN | ||
or | ||
.BR EWOULDBLOCK. | ||
|
||
.PP | ||
The \fIuser_data\fP value is provided to each callback function invocation to serve as | ||
context. | ||
.PP | ||
The | ||
.B ares_socket_functions | ||
must provide the following callbacks: | ||
.TP 18 | ||
.B \fIasocket\fP | ||
.B ares_socket_t(*)(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, void * \fIuser_data\fP) | ||
.br | ||
Creates an endpoint for communication and returns a descriptor. \fIdomain\fP, \fItype\fP, and \fIprotocol\fP | ||
each correspond to the parameters of | ||
.BR socket(2). | ||
Returns ahandle to the newly created socket, or -1 on error. | ||
.TP 18 | ||
.B \fIaclose\fP | ||
.B int(*)(ares_socket_t \fIfd\fP, void * \fIuser_data\fP) | ||
.br | ||
Closes the socket endpoint indicated by \fIfd\fP. See | ||
.BR close(2) | ||
.TP 18 | ||
.B \fIaconnect\fP | ||
.B int(*)(ares_socket_t \fIfd\fP, const struct sockaddr * \fIaddr\fP, socklen_t \fIaddr_len\fP, void * \fIuser_data\fP) | ||
.br | ||
Initiate a connection to the address indicated by \fIaddr\fP on a socket. See | ||
.BR connect(2) | ||
|
||
.TP 18 | ||
.B \fIarecvfrom\fP | ||
.B ssize_t(*)(ares_socket_t \fIfd\fP, void * \fIbuffer\fP, size_t \fIbuf_size\fP, int \fIflags\fP, struct sockaddr * \fIaddr\fP, socklen_t * \fIaddr_len\fP, void * \fIuser_data\fP) | ||
.br | ||
Receives data from remote socket endpoint, if available. If the \fIaddr\fP parameter is not NULL and the connection protocol provides the source address, the callback should fill this in. See | ||
.BR recvfrom(2) | ||
|
||
.TP 18 | ||
.B \fIasendv\fP | ||
.B ssize_t(*)(ares_socket_t \fIfd\fP, const struct iovec * \fIdata\fP, int \fIlen\fP, void * \fIuser_data\fP) | ||
.br | ||
Send data, as provided by the iovec array \fIdata\fP, to the socket endpoint. See | ||
.BR writev(2), | ||
|
||
.PP | ||
The | ||
.B 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. | ||
|
||
.SH SEE ALSO | ||
.BR ares_init_options (3), | ||
.BR socket(2), | ||
.BR close(2), | ||
.BR connect(2), | ||
.BR recv(2), | ||
.BR recvfrom(2), | ||
.BR send(2), | ||
.BR writev(2) | ||
.SH AUTHOR | ||
Carl Wilund |