Connection-oriented associations over UNIX sockets.
More...
|
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...
|
|
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.
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
-
type | the containing type |
field | the field of the containing type |
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
|
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] | context | an optional context |
[in] | prot | the protocol supported by the new connection |
[out] | out_assoc | the created connection |
- Return values
-
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] | assoc | the connection |
[in] | size | the desired packet size |
- Return values
-
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] | assoc | the connection |
[in] | mode | the connection mode |
[in] | fd | the file descriptor |
- Return values
-
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] | assoc | the connection |
[in] | mode | the connection mode |
[in] | endpoint | the named endpoint |
- Return values
-
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] | token | the local security token |
[out] | out_euid | the effective user id |
[out] | out_egid | the effective group id |
- Return values
-
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] | token | the local security token |
[out] | out_pid | the 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
-