Yah, libcaps is indeed stable, though not enabled by default. A
sysctl kern.caps_enabled=1 will enable it. The only issue with it
is probably one with unbounded internal kernel memory allocation.
libcaps is designed to create a messaging abstraction within a machine.
The way you access a remote service is by building a local CAPS service
that then communicates with the remote machine(s).
I have copied the code documentation below and added to it. No manual
pages have been written for it.
I would really appreciate it if someone could create manual pages
for these functions!
int caps_sys_service(const char *name, uid_t uid, gid_t gid,
int upcid, int flags)
Create an IPC service using the specified name, uid, gid, and flags.
Either uid or gid can be -1, but not both. The port identifier is
returned.
upcid can either be an upcall or a kqueue identifier (XXX) UPCID
is not currently implemented.
If an error is occurs, -1 is returned and errno is set to:
EOPNOTSUPP The CAPS system has not been enabled with
kern.caps_enabled
EINVAL An invalid argument was specified.
int caps_sys_client(const char *name, uid_t uid, gid_t gid,
int upcid, int flags);
Create an IPC client connected to the specified service. Either
uid or gid may be -1, indicating a wildcard, but not both. The
port identifier is returned. Programs connecting to a 'generic'
service typically first try (getuid(), -1), then try (getgid(), -1),
then try (0, 0).
upcid can either be an upcall or a kqueue identifier (XXX) UPCID
is not currently implemented.
If an error is occurs, -1 is returned and errno is set to:
EOPNOTSUPP The CAPS system has not been enabled with
kern.caps_enabled
EINVAL An invalid argument was specified.
int caps_sys_close(int portid)
Terminate an IPC link previously created with caps_sys_service() or
caps_sys_client(). Any unreplied messages will be automatically
replied by the kernel.
If an error is occurs, -1 is returned and errno is set to:
EINVAL The portid could not be found.
int caps_sys_setgen(int portid, off_t gen)
Set the 64 bit generation number for a CAPS link. A service
typically changes the generation number to indicate that it has
been restarted.
If an error is occurs, -1 is returned and errno is set to:
EINVAL The portid could not be found.
ENOTCONN If the process originally creating the port forked,
this error will be returned when the child process
attempts to access the port. The child process is
expected to create its own port.
off_t caps_sys_getgen(int portid)
Get the 64 bit generation number for a CAPS link. The generation
number is typically used to allow a client to detect when a service
has been restarted.
If an error is occurs, -1 is returned and errno is set to:
EINVAL The portid could not be found.
ENOTCONN If the process originally creating the port forked,
this error will be returned when the child process
attempts to access the port. The child process is
expected to create its own port.
off_t caps_sys_put(int portid, const void *msg, int msgsize)
Send an opaque message of the specified size to the specified
port. This function is only used on the client-side.
The memory associated with the message must be left intact until
the message is returned. The kernel does not make a copy of the
message. The message may not exceed 128KB.
A 64 bit message identifier is returned.
If an error is occurs, -1 is returned and errno is set to:
EINVAL An invalid argument was specified.
ENOTCONN If the process originally creating the port forked,
this error will be returned when the child process
attempts to access the port. The child process is
expected to create its own port.
This error is also returned if the remote end
closed its connection and is no longer available.
ENOBUFS The maximum number of in-transmit messages has
been reached. No more messages can be sent
until some of them are replied.
int caps_sys_reply(int portid, const void *msg, int msgsize, off_t msgid)
Reply to the received CAPS message identified by msgid. The reply
may contain opaque data. This function is only used on the
server-side.
The server may reply a message without retrieving its data.
The memory associated with the message must be left intact until
an acknowledgement is returned at a later time (see caps_sys_get()).
The kernel does not make a copy of the message. The message may
not exceed 128KB.
If an error is occurs, -1 is returned and errno is set to:
EINVAL An invalid argument was specified.
ENOTCONN If the process originally creating the port forked,
this error will be returned when the child process
attempts to access the port. The child process is
expected to create its own port.
This error is also returned if the remote end
closed its connection and is no longer available.
NOTE: a child process may not reply to a message
received by its parent.
int caps_sys_get(int portid, void *msg, int maxsize,
struct caps_msgid *msgid, struct caps_cred *ccr)
int caps_sys_wait(int portid, void *msg, int maxsize,
struct caps_msgid *msgid, struct caps_cred *ccr)
Retrieve the next ready message on the port, store its message id
and other information in *msgid and its creds in *ccr. ccr may
be NULL. The message is only stored in the msg buffer if it
fits.
If the message is too large to fit the message id, length, and
creds are still returned, but the message is not dequeued. The
caller is expected to call again with a larger buffer or to
call caps_sys_reply() on the message id without retrieving it
if it does not want to handle the message.
The returned message can either by a new message from a client,
a reply from the service, or (on the sevice side only) an
acknowledgement that a reply we made has been processed by the
client. This state information is stored in msgid->c_state and
may be:
CAPMS_REQUEST Service side received a new request
CAPMS_REQUEST_RETRY Reserved for future use
CAPMS_REPLY Client side received a reply
CAPMS_REPLY_RETRY Reserved for future use
CAPMS_DISPOSE Service side's reply has been disposed
of by the client.
If you are a CAPS client the only message type you will get is
CAPMS_REPLY. If you are a CAPS server you can get CAPS_REQUEST
or CAPS_DISPOSE.
This function does not block.
EINVAL An invalid argument was specified.
ENOTCONN If the process originally creating the port forked,
this error will be returned when the child process
attempts to access the port. The child process is
expected to create its own port.
This error is also returned if the remote end
closed its connection and is no longer available.
EWOULDBLOCK No messages are ready. This applies only to
caps_sys_get().
EINTR The system call was interrupted. This applies only
to caps_sys_wait().
int caps_sys_abort(int portid, off_t msgid, int flags)
Abort a previously sent message. You must still wait for the
message to be returned after sending the abort request. This
function will return the appropriate CAPS_ABORT_* code depending
on whether the abort succeeded or not.
This function is currently not implemented and CAPS_ABORT_NOTIMPL
is returned.
-Matt
