Low-level Interface

Functions
int	afdt_listen (const char *fname, struct afdt_error_t *err)
	Create a socket that listens for connections. More...
int	afdt_connect (const char *fname, struct afdt_error_t *err)
	Create a socket and connect to a listening socket. More...
int	afdt_send_fd_msg (int connfd, const uint8_t *content, uint32_t content_len, int fd_to_send, struct afdt_error_t *err)
	Send a message with an optional file descriptor. More...
int	afdt_send_plain_msg (int connfd, const uint8_t *content, uint32_t content_len, struct afdt_error_t *err)
	Send a message with no file descriptor. More...
int	afdt_recv_fd_msg (int connfd, uint8_t *content, uint32_t *content_len, int *received_fd, struct afdt_error_t *err)
	Receive a message with an optional file descriptor. More...
int	afdt_recv_plain_msg (int connfd, uint8_t *content, uint32_t *content_len, struct afdt_error_t *err)
	Receive a message with no file descriptor. More...

Detailed Description

The low-level interface provides a thin abstraction over the primitives used for transferring file descriptors over Unix domain sockets. The higher-level interfaces are implemented in terms of these functions, which can also be used to implement a high-level interface on top of a different event loop API or a high-level interface obeying a different protocol (for example: the client sending the file descriptor to the server).

This layer imposes very few restrictions on usage. Messages must be at most AFDT_MSGLEN bytes, and are automatically prefixed with a 32-bit host-byte-order header equal to the message length. At most one one file descriptor can be passed per message.

The most interesting operation provided by this interface is send/recv fd_msg, which is a short message and an optional file descriptor. Functions are also provided for sending and receiving "plain" messages, which do not include file descriptors.

All functions in this interface report errors by returning a negative value and populating detailed information into their err parameter. (err should be initialized to AFDT_ERROR_T_INIT.) errno will be set to an appropriate code, or 0 if no error code is applicable.

Function Documentation

int afdt_connect	(	const char *	fname,
		struct afdt_error_t *	err
	)

Create a socket and connect to a listening socket.

Parameters

fname	File to connect PF_LOCAL socket to.
err	Structure to populate with error information.

Returns

socket fd (>=0) if successful, <0 on failure.

int afdt_listen	(	const char *	fname,
		struct afdt_error_t *	err
	)

Create a socket that listens for connections.

Higher level code should call accept(2) on the returned socket to accept a connection from a client.

Parameters

fname	File to bind PF_LOCAL socket to.
err	Structure to populate with error information.

Returns

socket fd (>=0) if successful, <0 on failure.

int afdt_recv_fd_msg	(	int	connfd,
		uint8_t *	content,
		uint32_t *	content_len,
		int *	received_fd,
		struct afdt_error_t *	err
	)

Receive a message with an optional file descriptor.

Parameters

connfd	Descriptor from accept or afdt_connect.
content	Buffer for message content.
content_len	Pointer to buffer length, returns with actual length.
received_fd	Returns with received fd, or <0 if none.
err	Structure to populate with error information.

Returns

>=0 if successful, <0 on failure.

int afdt_recv_plain_msg	(	int	connfd,
		uint8_t *	content,
		uint32_t *	content_len,
		struct afdt_error_t *	err
	)

Receive a message with no file descriptor.

See Also

afdt_recv_fd_msg

int afdt_send_fd_msg	(	int	connfd,
		const uint8_t *	content,
		uint32_t	content_len,
		int	fd_to_send,
		struct afdt_error_t *	err
	)

Send a message with an optional file descriptor.

Parameters

connfd	Descriptor from accept or afdt_connect.
content	Message content.
content_len	Message length.
fd_to_send	File descriptor to send, or <0 for none.
err	Structure to populate with error information.

Returns

>=0 if successful, <0 on failure.

int afdt_send_plain_msg	(	int	connfd,
		const uint8_t *	content,
		uint32_t	content_len,
		struct afdt_error_t *	err
	)

Send a message with no file descriptor.

See Also

afdt_send_fd_msg