lib/libc/sys/caps_sys_get.2

   1 .\"
   2 .\" Copyright (c) 2006 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $DragonFly: src/lib/libc/sys/caps_sys_get.2,v 1.2 2006/03/02 19:27:35 swildner Exp $
  32 .\"
  33 .Dd February 28, 2006
  34 .Dt CAPS_SYS_GET 2
  35 .Os
  36 .Sh NAME
  37 .Nm caps_sys_get ,
  38 .Nm caps_sys_wait
  39 .Nd retrieve a message from a CAPS IPC port
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/caps.h
  44 .Ft int
  45 .Fo caps_sys_get
  46 .Fa "int portid"
  47 .Fa "void *msg"
  48 .Fa "int maxsize"
  49 .Fa "struct caps_msgid *msgid"
  50 .Fa "struct caps_cred *ccr"
  51 .Fc
  52 .Ft int
  53 .Fo caps_sys_wait
  54 .Fa "int portid"
  55 .Fa "void *msg"
  56 .Fa "int maxsize"
  57 .Fa "struct caps_msgid *msgid"
  58 .Fa "struct caps_cred *ccr"
  59 .Fc
  60 .Sh DESCRIPTION
  61 The
  62 .Fn caps_sys_get
  63 function retrieves the next ready message from a port specified by
  64 .Fa portid .
  65 The identifier and creds of the message are stored in
  66 .Fa msgid
  67 and
  68 .Fa ccr
  69 (which may be NULL).
  70 .Pp
  71 The message is only stored in the
  72 .Fa msg
  73 buffer if its length is less or equal than the size specified by
  74 .Fa maxsize .
  75 If the message is too large its identifier and creds are still
  76 returned but the message is not dequeued.
  77 In this case, the caller is expected to call
  78 .Fn caps_sys_get
  79 again with a larger buffer or to call
  80 .Fn caps_sys_reply
  81 on the
  82 .Fa msgid
  83 without retrieving it (if it does not want to handle the message).
  84 .Pp
  85 The returned
  86 .Fa msg
  87 can either be a new message from a client, a reply from the service,
  88 or (on the service side only)
  89 an acknowledgement that a reply made earlier has been processed by
  90 the client.
  91 This state information is stored in
  92 .Va msgid->c_state
  93 and can be:
  94 .Bl -tag -width ".Dv CAPMS_REQUEST_RETRY"
  95 .It Dv CAPMS_REQUEST
  96 The server side received a new request.
  97 .It Dv CAPMS_REQUEST_RETRY
  98 Reserved for future use.
  99 .It Dv CAPMS_REPLY
 100 The client side received a reply.
 101 .It Dv CAPMS_REPLY_RETRY
 102 Reserved for future use.
 103 .It Dv CAPMS_DISPOSE
 104 The server side reply has been disposed of by the client.
 105 .El
 106 .Pp
 107 If you are a CAPS client the only message type you will get is
 108 .Dv CAPMS_REPLY .
 109 If you are a CAPS server you can get
 110 .Dv CAPMS_REQUEST
 111 or
 112 .Dv CAPMS_DISPOSE
 113 message types.
 114 .Pp
 115 The
 116 .Fn caps_sys_get
 117 function does not block.
 118 If a blocking function is needed
 119 .Fn caps_sys_wait
 120 can be used which blocks until it is interrupted or a message is
 121 received.
 122 .Sh RETURN VALUES
 123 If successful, the
 124 .Fn caps_sys_get
 125 and
 126 .Fn caps_sys_wait
 127 functions return the length of the message received.
 128 Note that zero message lengths are perfectly acceptable so 0 can be
 129 legitimately returned.
 130 On failure, -1 is returned and
 131 .Va errno
 132 is set to indicate the error.
 133 .Sh ERRORS
 134 This function will fail if:
 135 .Bl -tag -width ".Bq Er EWOULDBLOCK"
 136 .It Bq Er EINVAL
 137 An invalid argument was specified.
 138 .It Bq Er ENOTCONN
 139 The process originally creating the port forked and the child
 140 process attempts to access the port.
 141 The child process is expected to create its own port.
 142 This error is also returned if the remote end closed its connection
 143 and is no longer available.
 144 .It Bq Er EWOULDBLOCK
 145 No messages are ready (this applies only to
 146 .Fn caps_sys_get ) .
 147 .It Bq Er EINTR
 148 The system call was interrupted (this applies only to
 149 .Fn caps_sys_wait ) .
 150 .El
 151 .Sh SEE ALSO
 152 .Xr caps_sys_client 2 ,
 153 .Xr caps_sys_put 2 ,
 154 .Xr caps_sys_reply 2 ,
 155 .Xr caps_sys_service 2
 156 .Sh HISTORY
 157 The
 158 .Fn caps_sys_get
 159 and
 160 .Fn caps_sys_wait
 161 function calls first appeared in
 162 .Dx 1.0 .
 163 .Sh AUTHORS
 164 .An -nosplit
 165 CAPS IPC was written by
 166 .An Matthew Dillon .
 167 This man page was written by
 168 .An Sascha Wildner .