140 lines
5.4 KiB
Plaintext
140 lines
5.4 KiB
Plaintext
This library provide an easy interface to the black magic that can be done
|
|
on Unix domain sockets, like passing file descriptors from one process to
|
|
another.
|
|
|
|
Programs that uses this library should include the ancillary.h header file.
|
|
Nothing else is required.
|
|
|
|
All functions of this library require the following header:
|
|
|
|
#include <ancillary.h>
|
|
|
|
At this time, the only ancillary data defined by the Single Unix
|
|
Specification (v3) is file descriptors.
|
|
|
|
Passing file descriptors
|
|
|
|
int ancil_send_fd(socket, file_descriptor)
|
|
int socket: the Unix socket
|
|
int file_descriptor: the file descriptor
|
|
Return value: 0 for success, -1 for failure.
|
|
|
|
Sends one file descriptor on a socket.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
sendmsg(2) system call.
|
|
|
|
|
|
int ancil_recv_fd(socket, file_descriptor)
|
|
int socket: the Unix socket
|
|
int *file_descriptor: pointer to the returned file descriptor
|
|
Return value: 0 for success, -1 for failure
|
|
|
|
Receives one file descriptor from a socket.
|
|
In case of success, the file descriptor is stored in the integer pointed
|
|
to by file_descriptor.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
recvmsg(2) system call.
|
|
The behavior is undefined if the recv_fd does not match a send_fd* on the
|
|
other side.
|
|
|
|
|
|
int ancil_send_fds(socket, file_descriptors, num_file_descriptors)
|
|
int socket: the Unix socket
|
|
const int *file_descriptors: array of file descriptors
|
|
unsigned num_file_descriptors: number of file descriptors
|
|
Return value: 0 for success, -1 for failure
|
|
|
|
Sends several file descriptors on a socket.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
sendmsg(2) system call.
|
|
The maximum number of file descriptors that can be sent using this
|
|
function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
|
|
overflow, probably a stack corruption.
|
|
|
|
|
|
int ancil_recv_fds(socket, file_descriptors, num_file_descriptors)
|
|
int socket: the Unix socket
|
|
int *file_descriptors: return array of file descriptors
|
|
unsigned num_file_descriptors: number of file descriptors
|
|
Return value: number of received fd for success, -1 for failure
|
|
|
|
Receives several file descriptors from a socket, no more than
|
|
num_file_descriptors.
|
|
In case of success, the received file descriptors are stored in the array
|
|
pointed to by file_descriptors.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
recvmsg(2) system call.
|
|
The maximum number of file descriptors that can be received using this
|
|
function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
|
|
overflow, probably a stack corruption.
|
|
The behavior is undefined if the recv_fds does not match a send_fd* on
|
|
the other side, or if the number of received file descriptors is more than
|
|
num_file_descriptors.
|
|
|
|
|
|
int ancil_send_fds_with_buffer(socket, fds, num, buffer)
|
|
int socket: the Unix socket
|
|
const int *fds: array of file descriptors
|
|
unsigned num: number of file descriptors
|
|
void *buffer: buffer to hold the system data structures
|
|
Return value: 0 for success, -1 for failure
|
|
|
|
Sends several file descriptors on a socket.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
sendmsg(2) system call.
|
|
The buffer argument must point to a memory area large enough to hold the
|
|
system data structures, see ANCIL_FD_BUFFER.
|
|
|
|
|
|
int ancil_send_fds_with_buffer(socket, fds, num, buffer)
|
|
int socket: the Unix socket
|
|
int *fds: return array of file descriptors
|
|
unsigned num: number of file descriptors
|
|
void *buffer: buffer to hold the system data structures
|
|
Return value: number of received fd for success, -1 for failure
|
|
|
|
Receives several file descriptors from a socket, no more than
|
|
num_file_descriptors.
|
|
In case of success, the received file descriptors are stored in the array
|
|
pointed to by file_descriptors.
|
|
In case of failure, errno is set; the possible values are the ones of the
|
|
recvmsg(2) system call.
|
|
The behavior is undefined if the recv_fds does not match a send_fd* on
|
|
the other side, or if the number of received file descriptors is more than
|
|
num_file_descriptors.
|
|
The buffer argument must point to a memory area large enough to hold the
|
|
system data structures, see ANCIL_FD_BUFFER.
|
|
|
|
|
|
ANCIL_MAX_N_FDS
|
|
|
|
Maximum number of file descriptors that can be sent with the sent_fds and
|
|
recv_fds functions. If you have to send more at once, use the
|
|
*_with_buffer versions. The value is enough to send "quite a few" file
|
|
descriptors.
|
|
|
|
|
|
ANCIL_FD_BUFFER(n)
|
|
int n: number of file descriptors
|
|
|
|
Expands to a structure data type large enough to hold the system data
|
|
structures for n file descriptors. So the address of a variable declared
|
|
of type ANCIL_FD_BUFFER(n) is suitable as the buffer argument for
|
|
*_with_buffer on n file descriptors.
|
|
To use this macro, you need <sys/types.h> and <sys/socket.h>. Bevare: with
|
|
Solaris, the _XPG4_2 macro must be defined before sys/socket is included.
|
|
|
|
|
|
Tuning the compilation
|
|
|
|
This library is designed to be included in projects, not installed in
|
|
/usr/lib. If your project does not use some of the functions, the
|
|
TUNE_OPTS variable in the Makefile allows not to build them. It is a list
|
|
of proprocessor options:
|
|
|
|
-DNDEBUG: turn assertions off (see assert(3))
|
|
-DSPARE_SEND_FDS: do not build ancil_send_fds
|
|
-DSPARE_SEND_FD: do not build ancil_send_fd
|
|
-DSPARE_RECV_FDS: do not build ancil_recv_fds
|
|
-DSPARE_RECV_FD: do not build ancil_recv_fd
|