Connections

Connection-oriented associations over UNIX sockets. More...

Macros

#define LWMSG_FD
 Define a file descriptor. More...
 
#define LWMSG_MEMBER_FD(type, field)
 Define a file descriptor as a member. More...
 

Enumerations

enum  LWMsgConnectionMode {
  LWMSG_CONNECTION_MODE_NONE,
  LWMSG_CONNECTION_MODE_LOCAL,
  LWMSG_CONNECTION_MODE_PAIR
}
 Connection mode. More...
 

Functions

LWMsgStatus lwmsg_connection_new (const LWMsgContext *context, LWMsgProtocol *prot, LWMsgAssoc **out_assoc)
 Create a new connection. More...
 
LWMsgStatus lwmsg_connection_set_packet_size (LWMsgAssoc *assoc, size_t size)
 Set maximum packet size. More...
 
LWMsgStatus lwmsg_connection_set_fd (LWMsgAssoc *assoc, LWMsgConnectionMode mode, int fd)
 Attach connection to existing socket. More...
 
LWMsgStatus lwmsg_connection_set_endpoint (LWMsgAssoc *assoc, LWMsgConnectionMode mode, const char *endpoint)
 Attach connection to named endpoint. More...
 
LWMsgStatus lwmsg_local_token_get_eid (LWMsgSecurityToken *token, uid_t *out_euid, gid_t *out_egid)
 Retrieve information from a "local" security token. More...
 
LWMsgStatus lwmsg_local_token_get_pid (LWMsgSecurityToken *token, pid_t *out_pid)
 Retrieve client pid from a "local" security token. More...
 

Detailed Description

Connections provide a concrete implementation of the association abstraction based on the BSD socket layer, allowing messages to be exchanged over UNIX domain sockets.

Connections over UNIX domain sockets support special features. Access to the identity of the connected peer is available through lwmsg_session_get_peer_security_token(), which returns a security token of type "local". Use lwmsg_local_token_get_eid() on the token to query the effective uid and gid of the peer.

Additionally, messages sent over a UNIX domain socket connection may contain embedded file descriptors which will be mirrored into the peer process through an underlying mechanism such as SCM_RIGHTS. This has applications ranging from implementing priveledge separation to exchanging shared memory segments or establishing side channels for efficient bulk data transfer.

To use embedded file descriptors, use the LWMSG_FD or LWMSG_MEMBER_FD() macros in your type specification.

Macro Definition Documentation

#define LWMSG_FD

Defines a file descriptor type within a type specification. The corresponding C type should be int. The value must either be a valid file descriptor greater than 0, or a value less than or equal to 0 (indicating that no descriptor should be transmitted).

The reason that 0 is not considered a valid file descriptor is so that allocating zeroed memory is sufficient to initialize any file descriptors contained in the block.

If you must transmit file descriptor 0, first use dup() to acquire a new descriptor with a non-zero value and transmit that.

#define LWMSG_MEMBER_FD (   type,
  field 
)

Defines a file descriptor as a member of a containing type. The corresponding C type should be int.

Parameters
typethe containing type
fieldthe field of the containing type

Enumeration Type Documentation

Describes the mode of a connection (local versus remote)

Enumerator
LWMSG_CONNECTION_MODE_NONE 

No connection mode set

LWMSG_CONNECTION_MODE_LOCAL 

Local connection

LWMSG_CONNECTION_MODE_PAIR 

Anonymous socket pair connection

Function Documentation

LWMsgStatus lwmsg_connection_new ( const LWMsgContext context,
LWMsgProtocol prot,
LWMsgAssoc **  out_assoc 
)

Creates a new connection which speaks the specified protocol. A new connection begins in an unconnected state and must be bound to a socket or endpoint before it can continue.

Parameters
[in]contextan optional context
[in]protthe protocol supported by the new connection
[out]out_assocthe created connection
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_connection_set_packet_size ( LWMsgAssoc assoc,
size_t  size 
)

Sets the maximum packet size supported by the connection. Larger packets sizes use more memory but make sending large messsages more efficient. The choice of packet size might also affect fragmentation behavior or efficiency of the underlying transport mechanism.

The actual packet size used will be the smaller of the specified size and the preferred packet size of the peer. The packet size cannot be changed after the connection is bound.

Parameters
[in,out]assocthe connection
[in]sizethe desired packet size
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe packet size cannot be changed in the connection's current state
LWMsgStatus lwmsg_connection_set_fd ( LWMsgAssoc assoc,
LWMsgConnectionMode  mode,
int  fd 
)

Attaches the specified connection to an existing file descriptor, which must be a valid socket which matches the specified mode.

This function does not by itself cause connection activity and thus is guaranteed not to block.

Parameters
[in,out]assocthe connection
[in]modethe connection mode
[in]fdthe file descriptor
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_PARAMETERthe file descriptor is invalid
LWMSG_STATUS_INVALID_STATEa file descriptor or endpoint is already set
LWMsgStatus lwmsg_connection_set_endpoint ( LWMsgAssoc assoc,
LWMsgConnectionMode  mode,
const char *  endpoint 
)

Attaches the specified connection to a named endpoint. For a LWMSG_CONNECTION_MODE_LOCAL connection, this is the path of the domain socket file. For a #LWMSG_CONNECTION_MODE_REMOTE connection, this is the address/hostname and port of the remote host.

This function does not by itself cause a connection to be establish and thus is guaranteed not to block.

Parameters
[in,out]assocthe connection
[in]modethe connection mode
[in]endpointthe named endpoint
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_PARAMETERthe endpoint is invalid
LWMSG_STATUS_INVALID_STATEa file descriptor or endpoint is already set
LWMsgStatus lwmsg_local_token_get_eid ( LWMsgSecurityToken token,
uid_t *  out_euid,
gid_t *  out_egid 
)

Retrives the effective user ID and effective group ID from a local access token (that is, a token for which lwmsg_security_token_get_type() returns "local")

Parameters
[in]tokenthe local security token
[out]out_euidthe effective user id
[out]out_egidthe effective group id
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_PARAMETERthe provided token was not of the correct type
LWMsgStatus lwmsg_local_token_get_pid ( LWMsgSecurityToken token,
pid_t *  out_pid 
)

Retrives the pid of the program connecting to the server based off a local access token (that is, a token for which lwmsg_security_token_get_type() returns "local")

Parameters
[in]tokenthe local security token
[out]out_pidthe client pid. If the platform does not support querying the pid of processes connecting over a UNIX domain socket, this will be -1.
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_PARAMETERthe provided token was not of the correct type