mirror of https://github.com/c-ares/c-ares.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
103 lines
3.8 KiB
103 lines
3.8 KiB
.\" Copyright (C) Daniel Stenberg |
|
.\" SPDX-License-Identifier: MIT |
|
.TH ARES_SET_SOCKET_FUNCTIONS 3 "13 Dec 2016" |
|
.SH NAME |
|
ares_set_socket_functions \- Set socket io callbacks |
|
.SH SYNOPSIS |
|
.nf |
|
#include <ares.h> |
|
|
|
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 *, ares_socklen_t, void *); |
|
ares_ssize_t (*\fIarecvfrom\fP)(ares_socket_t, void *, size_t, int, |
|
struct sockaddr *, ares_socklen_t *, void *); |
|
ares_ssize_t (*\fIasendv\fP)(ares_socket_t, const struct iovec *, int, void *); |
|
}; |
|
|
|
void ares_set_socket_functions(ares_channel_t *\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. |
|
Cannot be used when \fBARES_OPT_EVENT_THREAD\fP is passed to \fIares_init_options(3)\fP. |
|
|
|
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. You |
|
can choose to only implement some of the socket functions, and provide NULL to any |
|
others and c-ares will use its built-in system functions in that case. |
|
.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, ares_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 ares_ssize_t(*)(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) |
|
.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 ares_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 AVAILABILITY |
|
Added in c-ares 1.13.0 |
|
.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
|
|
|