.\"
.\" Copyright (c) 2006 The DragonFly Project.  All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/lib/libc/sys/caps_sys_get.2,v 1.2 2006/03/02 19:27:35 swildner Exp $
.\"
.Dd February 28, 2006
.Dt CAPS_SYS_GET 2
.Os
.Sh NAME
.Nm caps_sys_get ,
.Nm caps_sys_wait
.Nd retrieve a message from a CAPS IPC port
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/caps.h
.Ft int
.Fo caps_sys_get
.Fa "int portid"
.Fa "void *msg"
.Fa "int maxsize"
.Fa "struct caps_msgid *msgid"
.Fa "struct caps_cred *ccr"
.Fc
.Ft int
.Fo caps_sys_wait
.Fa "int portid"
.Fa "void *msg"
.Fa "int maxsize"
.Fa "struct caps_msgid *msgid"
.Fa "struct caps_cred *ccr"
.Fc
.Sh DESCRIPTION
The
.Fn caps_sys_get
function retrieves the next ready message from a port specified by
.Fa portid .
The identifier and creds of the message are stored in
.Fa msgid
and
.Fa ccr
(which may be NULL).
.Pp
The message is only stored in the
.Fa msg
buffer if its length is less or equal than the size specified by
.Fa 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
.Fn caps_sys_get
again with a larger buffer or to call
.Fn caps_sys_reply
on the
.Fa msgid
without retrieving it (if it does not want to handle the message).
.Pp
The returned
.Fa 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 information is stored in
.Va msgid->c_state
and can be:
.Bl -tag -width ".Dv CAPMS_REQUEST_RETRY"
.It Dv CAPMS_REQUEST
The server side received a new request.
.It Dv CAPMS_REQUEST_RETRY
Reserved for future use.
.It Dv CAPMS_REPLY
The client side received a reply.
.It Dv CAPMS_REPLY_RETRY
Reserved for future use.
.It Dv CAPMS_DISPOSE
The server side reply has been disposed of by the client.
.El
.Pp
If you are a CAPS client the only message type you will get is
.Dv CAPMS_REPLY .
If you are a CAPS server you can get
.Dv CAPMS_REQUEST
or
.Dv CAPMS_DISPOSE
message types.
.Pp
The
.Fn caps_sys_get
function does not block.
If a blocking function is needed
.Fn caps_sys_wait
can be used which blocks until it is interrupted or a message is
received.
.Sh RETURN VALUES
If successful, the
.Fn caps_sys_get
and
.Fn 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
.Va errno
is set to indicate the error.
.Sh ERRORS
This function will fail if:
.Bl -tag -width ".Bq Er EWOULDBLOCK"
.It Bq Er EINVAL
An invalid argument was specified.
.It Bq Er 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.
.It Bq Er EWOULDBLOCK
No messages are ready (this applies only to
.Fn caps_sys_get ) .
.It Bq Er EINTR
The system call was interrupted (this applies only to
.Fn caps_sys_wait ) .
.El
.Sh SEE ALSO
.Xr caps_sys_client 2 ,
.Xr caps_sys_put 2 ,
.Xr caps_sys_reply 2 ,
.Xr caps_sys_service 2
.Sh HISTORY
The
.Fn caps_sys_get
and
.Fn caps_sys_wait
function calls first appeared in
.Dx 1.0 .
.Sh AUTHORS
.An -nosplit
CAPS IPC was written by
.An Matthew Dillon .
This man page was written by
.An Sascha Wildner .