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

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DOOR_CREATE 3C "Jan 22, 2008"
   7 .SH NAME
   8 door_create \- create a door descriptor
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  13 #include <door.h>
  14
  15 \fBint\fR \fBdoor_create\fR(\fBvoid (*\fR\fIserver_procedure\fR) (void *\fIcookie\fR, \fBchar *\fR\fIargp\fR,
  16      \fBsize_t\fR \fIarg_size\fR, \fBdoor_desc_t *\fR\fIdp\fR, \fBuint_t\fR \fIn_desc\fR), \fBvoid *\fR\fIcookie\fR,
  17      \fBuint_t\fR \fIattributes\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .LP
  22 The \fBdoor_create()\fR function creates a door descriptor that describes the
  23 procedure specified by the function \fIserver_procedure\fR. The data item,
  24 \fIcookie\fR, is associated with the door descriptor, and is passed as an
  25 argument to the invoked function \fIserver_procedure\fR during
  26 \fBdoor_call\fR(3C) invocations. Other arguments passed to
  27 \fIserver_procedure\fR from an associated \fBdoor_call()\fR are placed on the
  28 stack and include \fIargp\fR and \fIdp\fR. The \fIargp\fR argument points to
  29 \fIarg_size\fR bytes of data and the \fIdp\fR argument points to \fIn_desc\fR
  30 \fBdoor_desc_t\fR structures. The \fIattributes\fR argument specifies
  31 attributes associated with the newly created door. Valid values for
  32 \fIattributes\fR are constructed by OR-ing one or more of the following values:
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fBDOOR_UNREF\fR\fR
  37 .ad
  38 .sp .6
  39 .RS 4n
  40 Delivers a special invocation on the door when the number of descriptors that
  41 refer to this door drops to one. In order to trigger this condition, more
  42 than one descriptor must have referred to this door at some time.
  43 \fBDOOR_UNREF_DATA\fR designates an unreferenced invocation, as the \fIargp\fR
  44 argument passed to \fIserver_procedure\fR. In the case of an unreferenced
  45 invocation, the values for \fIarg_size\fR, \fIdp\fR and \fIn_did\fR are
  46 \fB0\fR. Only one unreferenced invocation is delivered on behalf of a door.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBDOOR_UNREF_MULTI\fR\fR
  53 .ad
  54 .sp .6
  55 .RS 4n
  56 Similar to \fBDOOR_UNREF\fR, except multiple unreferenced invocations can be
  57 delivered on the same door if the number of descriptors referring to the door
  58 drops to one more than once. Since an additional reference may have been
  59 passed by the time an unreferenced invocation arrives, the \fBDOOR_IS_UNREF\fR
  60 attribute returned by the \fBdoor_info\fR(3C) call can be used to determine if
  61 the door is still unreferenced.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBDOOR_PRIVATE\fR\fR
  68 .ad
  69 .sp .6
  70 .RS 4n
  71 Maintains a separate pool of server threads on behalf of the door. Server
  72 threads are associated with a door's private server pool using
  73 \fBdoor_bind\fR(3C).
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBDOOR_REFUSE_DESC\fR\fR
  80 .ad
  81 .sp .6
  82 .RS 4n
  83 Any attempt to call \fBdoor_call\fR(3C) on this door with argument descriptors
  84 will fail with \fBENOTSUP\fR. When this flag is set, the door's server
  85 procedure will always be invoked with an \fIn_desc\fR argument of 0.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBDOOR_NO_CANCEL\fR\fR
  92 .ad
  93 .sp .6
  94 .RS 4n
  95 Clients which abort calls to \fBdoor_call()\fR on this door will not cause the
  96 cancellation of the server thread handling the request. See
  97 \fBcancellation\fR(5).
  98 .RE
  99
 100 .sp
 101 .LP
 102 The descriptor returned from \fBdoor_create()\fR will be marked as close on
 103 exec (\fBFD_CLOEXEC\fR). Information about a door is available for all clients
 104 of a door using \fBdoor_info()\fR. Applications concerned with security should
 105 not place secure information in door data that is accessible by
 106 \fBdoor_info()\fR. In particular, secure data should not be stored in the data
 107 item \fIcookie\fR.
 108 .sp
 109 .LP
 110 By default, additional threads are created as needed to handle concurrent
 111 \fBdoor_call()\fR invocations.  See \fBdoor_server_create\fR(3C) for
 112 information on how to change this behavior.
 113 .sp
 114 .LP
 115 A process can advertise a door in the file system name space using
 116 \fBfattach\fR(3C).
 117 .sp
 118 .LP
 119 After creation, \fBdoor_setparam\fR(3C) can be used to set limits on the amount
 120 of data and descriptors clients can send over the door.
 121 .SH RETURN VALUES
 122 .LP
 123 Upon successful completion, \fBdoor_create()\fR returns a non-negative value.
 124 Otherwise, \fBdoor_create\fR returns \fB\(mi1\fR and sets \fBerrno\fR to
 125 indicate the error.
 126 .SH ERRORS
 127 .LP
 128 The \fBdoor_create()\fR function will fail if:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBEINVAL\fR\fR
 133 .ad
 134 .RS 10n
 135 Invalid attributes are passed.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBEMFILE\fR\fR
 142 .ad
 143 .RS 10n
 144 The process has too many open descriptors.
 145 .RE
 146
 147 .SH EXAMPLES
 148 .LP
 149 \fBExample 1 \fRCreate a door and use \fBfattach()\fR to advertise the door in
 150 the file system namespace.
 151 .sp
 152 .LP
 153 The following example creates a door and uses \fBfattach()\fR to advertise the
 154 door in the file system namespace.
 155
 156 .sp
 157 .in +2
 158 .nf
 159 void
 160 server(void *cookie, char *argp, size_t arg_size, door_desc_t *dp,
 161     uint_t n_desc)
 162 {
 163     door_return(NULL, 0, NULL, 0);
 164     /* NOTREACHED */
 165 }
 166
 167 int
 168 main(int argc, char *argv[])
 169 {
 170     int did;
 171     struct stat buf;
 172
 173     if ((did = door_create(server, 0, 0)) < 0) {
 174         perror("door_create");
 175         exit(1);
 176     }
 177
 178     /* make sure file system location exists */
 179     if (stat("/tmp/door", &buf) < 0) {
 180         int newfd;
 181         if ((newfd = creat("/tmp/door", 0444)) < 0) {
 182             perror("creat");
 183             exit(1);
 184         }
 185         (void) close(newfd);
 186     }
 187
 188     /* make sure nothing else is attached */
 189     (void) fdetach("/tmp/door");
 190
 191     /* attach to file system */
 192     if (fattach(did, "/tmp/door") < 0) {
 193         perror("fattach");
 194         exit(2);
 195     }
 196     [...]
 197 }
 198 .fi
 199 .in -2
 200
 201 .SH ATTRIBUTES
 202 .LP
 203 See \fBattributes\fR(5) for descriptions of the following attributes:
 204 .sp
 205
 206 .sp
 207 .TS
 208 box;
 209 c | c
 210 l | l .
 211 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 212 _
 213 Architecture    all
 214 _
 215 Interface Stability     Committed
 216 _
 217 MT-Level        Safe
 218 .TE
 219
 220 .SH SEE ALSO
 221 .LP
 222 \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_info\fR(3C),
 223 \fBdoor_revoke\fR(3C), \fBdoor_setparam\fR(3C), \fBdoor_server_create\fR(3C),
 224 \fBfattach\fR(3C), \fBlibdoor\fR(3LIB), \fBattributes\fR(5),
 225 \fBcancellation\fR(5)