usr/src/man/man3c/door_call.3c

   1 '\" te
   2 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
   3 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DOOR_CALL 3C "Feb 7, 2015"
   8 .SH NAME
   9 door_call \- invoke the function associated with a door descriptor
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  14 #include <door.h>
  15
  16 \fBint\fR \fBdoor_call\fR(\fBint\fR \fId\fR, \fBdoor_arg_t *\fR\fIparams\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .LP
  21 The \fBdoor_call()\fR function invokes the function associated with the door
  22 descriptor \fId\fR, and passes the arguments (if any) specified in
  23 \fIparams\fR. All of the \fIparams\fR members are treated as in/out parameters
  24 during a door invocation and may be updated upon returning from a door call.
  25 Passing \fINULL\fR for \fIparams\fR indicates there are no arguments to be
  26 passed and no results expected.
  27 .sp
  28 .LP
  29 The \fBdoor_arg_t\fR structure includes the following members:
  30 .sp
  31 .in +2
  32 .nf
  33 typedef struct {
  34         char            *data_ptr;      /* Argument/result data */
  35         size_t          data_size;      /* Argument/result data size */
  36         door_desc_t     *desc_ptr;      /* Argument/result descriptors */
  37         uint_t          desc_num;       /* Argument/result num descriptors */
  38         char            *rbuf;          /* Result area */
  39         size_t          rsize;          /* Result size */
  40 } door_arg_t;
  41 .fi
  42 .in -2
  43
  44 .sp
  45 .LP
  46 The \fBdoor_desc_t\fR structure includes the following members:
  47 .sp
  48 .in +2
  49 .nf
  50 typedef struct {
  51         door_attr_t     d_attributes;           /* Describes the parameter */
  52         union {
  53                 struct {
  54                         int             d_descriptor;   /* Descriptor */
  55                         door_id_t       d_id;           /* Unique door id */
  56                 } d_desc;
  57         } d_data;
  58 } door_desc_t;
  59 .fi
  60 .in -2
  61
  62 .sp
  63 .LP
  64 Arguments are specified using the \fBdata_ptr\fR and \fBdesc_ptr\fR members of
  65 \fIparams\fR. The size of the argument data in bytes is passed in
  66 \fBdata_size\fR and the number of argument descriptors is passed in
  67 \fBdesc_num\fR.
  68 .sp
  69 .LP
  70 Results from the door invocation are placed in the buffer, \fBrbuf\fR. See
  71 \fBdoor_return\fR(3C). The \fBdata_ptr\fR and \fBdesc_ptr\fR members of
  72 \fIparams\fR are updated to reflect the location of the results within the
  73 \fBrbuf\fR buffer. The size of the data results and number of descriptors
  74 returned are updated in the \fBdata_size\fR and \fBdesc_num\fR members. It is
  75 acceptable to use the same buffer for input argument data and results, so
  76 \fBdoor_call()\fR may be called with \fBdata_ptr\fR and \fBdesc_ptr\fR pointing
  77 to the buffer \fBrbuf\fR.
  78 .sp
  79 .LP
  80 If the results of a door invocation exceed the size of the buffer specified by
  81 \fBrsize\fR, the system automatically allocates a new buffer in the caller's
  82 address space and updates the \fBrbuf\fR and \fBrsize\fR members to reflect
  83 this location. In this case, the caller is responsible for reclaiming this
  84 area using \fBmunmap(rbuf, rsize)\fR when the buffer is no longer required.
  85 See \fBmunmap\fR(2).
  86 .sp
  87 .LP
  88 Descriptors passed in a \fBdoor_desc_t\fR structure are identified by the
  89 \fBd_attributes\fR member. The client marks the \fBd_attributes\fR member with
  90 the type of object being passed by logically OR-ing the value of object type.
  91 Currently, the only object type that can be passed or returned is a file
  92 descriptor, denoted by the \fBDOOR_DESCRIPTOR\fR attribute. Additionally, the
  93 \fBDOOR_RELEASE\fR attribute can be set, causing the descriptor to be closed
  94 in the caller's address space after it is passed to the target. The descriptor
  95 will be closed even if \fBdoor_call()\fR returns an error, unless that error
  96 is \fBEFAULT\fR or \fBEBADF\fR.
  97 .sp
  98 .LP
  99 When file descriptors are passed or returned, a new descriptor is created in
 100 the target address space and the \fBd_descriptor\fR member in the target
 101 argument is updated to reflect the new descriptor. In addition, the system
 102 passes a system-wide unique number associated with each door in the
 103 \fBd_id\fR member and marks the \fBd_attributes\fR member with other
 104 attributes associated with a door including the following:
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBDOOR_LOCAL\fR\fR
 109 .ad
 110 .RS 20n
 111 The door received was created by this process using \fBdoor_create()\fR. See
 112 \fBdoor_create\fR(3C).
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBDOOR_PRIVATE\fR\fR
 119 .ad
 120 .RS 20n
 121 The door received has a private pool of server threads associated with the
 122 door.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBDOOR_UNREF\fR\fR
 129 .ad
 130 .RS 20n
 131 The door received is expecting an unreferenced notification.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBDOOR_UNREF_MULTI\fR\fR
 138 .ad
 139 .RS 20n
 140 Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be
 141 delivered for the same door.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBDOOR_REFUSE_DESC\fR\fR
 148 .ad
 149 .RS 20n
 150 This door does not accept argument descriptors.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBDOOR_NO_CANCEL\fR\fR
 157 .ad
 158 .RS 20n
 159 This door does not cancel the server thread upon client abort.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBDOOR_REVOKED\fR\fR
 166 .ad
 167 .RS 20n
 168 The door received has been revoked by the server.
 169 .RE
 170
 171 .sp
 172 .LP
 173 The \fBdoor_call()\fR function is not a restartable system call. It returns
 174 \fBEINTR\fR if a signal was caught and handled by this thread. If the door
 175 invocation is not idempotent the caller should mask any signals that may be
 176 generated during a \fBdoor_call()\fR operation. If the client aborts in the
 177 middle of a \fBdoor_call()\fR and the door was not created with the
 178 \fBDOOR_NO_CANCEL\fR flag, the server thread is notified using the POSIX (see
 179 \fBstandards\fR(5)) thread cancellation mechanism. See \fBcancellation\fR(5).
 180 .SH RETURN VALUES
 181 .LP
 182 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
 183 returned and \fBerrno\fR is set to indicate the error.
 184 .SH ERRORS
 185 .LP
 186 The \fBdoor_call()\fR function will fail if:
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBE2BIG\fR\fR
 191 .ad
 192 .RS 13n
 193 Arguments were too big for server thread stack.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBEAGAIN\fR\fR
 200 .ad
 201 .RS 13n
 202 Server was out of available resources.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBEBADF\fR\fR
 209 .ad
 210 .RS 13n
 211 Invalid door descriptor was passed.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBEFAULT\fR\fR
 218 .ad
 219 .RS 13n
 220 Argument pointers pointed outside the allocated address space.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBEINTR\fR\fR
 227 .ad
 228 .RS 13n
 229 A signal was caught in the client, the client called \fBfork\fR(2), or the
 230 server exited during invocation.
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBEINVAL\fR\fR
 237 .ad
 238 .RS 13n
 239 Bad arguments were passed.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBEMFILE\fR\fR
 246 .ad
 247 .RS 13n
 248 The client or server has too many open descriptors.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBENFILE\fR\fR
 255 .ad
 256 .RS 13n
 257 The \fIdesc_num\fR argument is larger than the door's \fBDOOR_PARAM_DESC_MAX\fR
 258 parameter (see \fBdoor_getparam\fR(3C)), and the door does not have the
 259 \fBDOOR_REFUSE_DESC\fR set.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBENOBUFS\fR\fR
 266 .ad
 267 .RS 13n
 268 The \fIdata_size\fR argument is larger than the door's
 269 \fBDOOR_PARAM_DATA_MAX\fR parameter, or smaller than the door's
 270 \fBDOOR_PARAM_DATA_MIN\fR parameter (see \fBdoor_getparam\fR(3C)).
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fBENOTSUP\fR\fR
 277 .ad
 278 .RS 13n
 279 The \fIdesc_num\fR argument is non-zero and the door has the
 280 \fBDOOR_REFUSE_DESC\fR flag set.
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBEOVERFLOW\fR\fR
 287 .ad
 288 .RS 13n
 289 System could not create overflow area in caller for results.
 290 .RE
 291
 292 .SH ATTRIBUTES
 293 .LP
 294 See \fBattributes\fR(5) for descriptions of the following attributes:
 295 .sp
 296
 297 .sp
 298 .TS
 299 box;
 300 c | c
 301 l | l .
 302 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 303 _
 304 Architecture    all
 305 _
 306 Interface Stability     Stable
 307 _
 308 MT-Level        Safe
 309 .TE
 310
 311 .SH SEE ALSO
 312 .LP
 313 \fBmunmap\fR(2), \fBdoor_create\fR(3C), \fBdoor_getparam\fR(3C),
 314 \fBdoor_info\fR(3C), \fBdoor_return\fR(3C), \fBlibdoor\fR(3LIB),
 315 \fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5)