Low-level Interface


Functions

int afdt_listen (const char *fname, struct afdt_error_t *err)
 Create a socket that listens for connections.
int afdt_connect (const char *fname, struct afdt_error_t *err)
 Create a socket and connect to a listening socket.
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.
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.
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.
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.

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


Generated on Sun May 16 15:27:28 2010 for libafdt by  doxygen 1.5.7.1