CAPS_SYS_GET(2) BSD System Calls Manual CAPS_SYS_GET(2)NAME
caps_sys_get, caps_sys_wait — retrieve a message from a CAPS IPC port
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/caps.h>
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);
DESCRIPTION
The caps_sys_get() function retrieves the next ready message from a port
specified by portid. The identifier and creds of the message are stored
in msgid and ccr (which may be NULL).
The message is only stored in the msg buffer if its length is less or
equal than the size specified by maxsize. If the message is too large
its identifier and creds are still returned but the message is not
dequeued. In this case, the caller is expected to call caps_sys_get()
again with a larger buffer or to call caps_sys_reply() on the msgid with‐
out retrieving it (if it does not want to handle the message).
The returned msg can either be a new message from a client, a reply from
the service, or (on the service side only) an acknowledgement that a
reply made earlier has been processed by the client. This state informa‐
tion is stored in msgid->c_state and can be:
CAPMS_REQUEST The server side received a new request.
CAPMS_REQUEST_RETRY Reserved for future use.
CAPMS_REPLY The client side received a reply.
CAPMS_REPLY_RETRY Reserved for future use.
CAPMS_DISPOSE The server side 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 CAPMS_REQUEST or
CAPMS_DISPOSE message types.
The caps_sys_get() function does not block. If a blocking function is
needed caps_sys_wait() can be used which blocks until it is interrupted
or a message is received.
RETURN VALUES
If successful, the caps_sys_get() and caps_sys_wait() functions return
the length of the message received. Note that zero message lengths are
perfectly acceptable so 0 can be legitimately returned. On failure, -1
is returned and errno is set to indicate the error.
ERRORS
This function will fail if:
[EINVAL] An invalid argument was specified.
[ENOTCONN] The process originally creating the port forked and 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()).
SEE ALSOcaps_sys_client(2), caps_sys_put(2), caps_sys_reply(2),
caps_sys_service(2)HISTORY
The caps_sys_get() and caps_sys_wait() function calls first appeared in
DragonFly 1.0.
AUTHORS
CAPS IPC was written by Matthew Dillon. This man page was written by
Sascha Wildner.
BSD February 28, 2006 BSD
