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

   1 '\" te
   2 .\" Copyright (c) 2005, 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_GETPARAM 3C "April 9, 2016"
   7 .SH NAME
   8 door_getparam, door_setparam \- retrieve and set door parameters
   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_getparam\fR(\fBint\fR \fId\fR, \fBint\fR \fIparam\fR, \fBsize_t *\fR\fIout\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBdoor_setparam\fR(\fBint\fR \fId\fR, \fBint\fR \fIparam\fR, \fBsize_t\fR \fIval\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .LP
  25 The \fBdoor_getparam()\fR function retrieves the value of \fIparam\fR for the
  26 door descriptor \fId\fR and writes it through the pointer \fIout\fR. The
  27 \fBdoor_setparam()\fR function sets the value of \fIparam\fR for the door
  28 descriptor \fId\fR to \fIval\fR. The \fIparam\fR argument names the parameter
  29 to view or change and can be one of the following values:
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fBDOOR_PARAM_DATA_MAX\fR\fR
  34 .ad
  35 .RS 23n
  36 This parameter represents the maximum amount of data that can be passed to the
  37 door routine. Any attempt to call \fBdoor_call\fR(3C) on a door with a
  38 \fIdata_size\fR value larger than the door's \fBDOOR_PARAM_DATA_MAX\fR
  39 parameter will fail with \fBENOBUFS\fR. At door creation time, this parameter
  40 is initialized to \fBSIZE_MAX\fR and can be set to any value from 0 to
  41 \fBSIZE_MAX\fR, inclusive. This parameter must be greater than or equal to the
  42 \fBDOOR_PARAM_DATA_MIN\fR parameter.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBDOOR_PARAM_DATA_MIN\fR\fR
  49 .ad
  50 .RS 23n
  51 This parameter represents the minimum amount of data that can be passed to
  52 the door routine. Any attempt to call \fBdoor_call\fR(3C) on a door with a
  53 \fIdata_size\fR value smaller than the door's \fBDOOR_PARAM_DATA_MIN\fR
  54 parameter will fail with \fBENOBUFS\fR. At door creation time, this parameter
  55 is initialized to 0, and can be set to any value from 0 to \fBSIZE_MAX\fR,
  56 inclusive. This parameter must be less than or equal to the
  57 \fBDOOR_PARAM_DATA_MAX\fR parameter.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBDOOR_PARAM_DESC_MAX\fR\fR
  64 .ad
  65 .RS 23n
  66 This parameter represents the maximum number of argument descriptors that
  67 can be passed to the door routine. Any attempt to call \fBdoor_call\fR(3C) on a
  68 door with a \fIdesc_nu\fRm value larger than the door's
  69 \fBDOOR_PARAM_DESC_MAX\fR parameter will fail with \fBENFILE\fR. If the door
  70 was created with the \fBDOOR_REFUSE_DESC\fR flag, this parameter is initialized
  71 to 0 and cannot be changed to any other value. Otherwise, it is initialized to
  72 \fBINT_MAX\fR and can be set to any value from 0 to \fBINT_MAX\fR, inclusive.
  73 .RE
  74
  75 .sp
  76 .LP
  77 The \fBdoor_setparam()\fR function can only affect doors that were created by
  78 the current process.
  79 .SH RETURN VALUES
  80 .LP
  81 Upon successful completion, 0 is returned. Otherwise, -1 is returned and
  82 \fBerrno\fR is set to indicate the error.
  83 .SH ERRORS
  84 .LP
  85 The \fBdoor_getparam()\fR function will fail if:
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBEBADF\fR\fR
  90 .ad
  91 .RS 13n
  92 The \fId\fR argument is not a door descriptor.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBEFAULT\fR\fR
  99 .ad
 100 .RS 13n
 101 The \fIout\fR argument is not a valid address.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEINVAL\fR\fR
 108 .ad
 109 .RS 13n
 110 The \fIparam\fR argument is not a recognized parameter.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBEOVERFLOW\fR\fR
 117 .ad
 118 .RS 13n
 119 The value of the parameter is larger than the \fBSIZE_MAX\fR. This condition
 120 can occur only if the calling process is 32-bit and the door targets a 64-bit
 121 process or the kernel.
 122 .RE
 123
 124 .sp
 125 .LP
 126 The \fBdoor_setparam()\fR function will fail if:
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBEBADF\fR\fR
 131 .ad
 132 .RS 11n
 133 The \fId\fR argument is not a door descriptor or has been revoked.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEINVAL\fR\fR
 140 .ad
 141 .RS 11n
 142 The \fIparam\fR argument is not a recognized parameter, or the requested change
 143 would make \fBDOOR_PARAM_DATA_MIN\fR greater than \fBDOOR_PARAM_DATA_MAX\fR.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBENOTSUP\fR\fR
 150 .ad
 151 .RS 11n
 152 The \fIparam\fR argument is \fBDOOR_PARAM_DESC_MAX\fR, \fId\fR was created with
 153 the \fBDOOR_REFUSE_DESC\fR flag, and \fIval\fR is not zero.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBEPERM\fR\fR
 160 .ad
 161 .RS 11n
 162 The \fId\fR argument was not created by this process.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBERANGE\fR\fR
 169 .ad
 170 .RS 11n
 171 The \fIval\fR argument is not in supported range of \fIparam\fR.
 172 .RE
 173
 174 .SH EXAMPLES
 175 .LP
 176 \fBExample 1 \fRSet up a door with a fixed request size.
 177 .sp
 178 .in +2
 179 .nf
 180 typedef struct my_request {
 181      int request;
 182 ar buffer[4096];
 183 } my_request_t;
 184
 185 fd = door_create(my_handler, DOOR_REFUSE_DESC);
 186 if (fd < 0)
 187      /* handle error */
 188
 189 if (door_setparam(fd, DOOR_PARAM_DATA_MIN,
 190     sizeof (my_request_t)) < 0 ||
 191     door_setparam(fd, DOOR_PARAM_DATA_MAX,
 192     sizeof (my_request_t)) < 0)
 193  /* handle error */
 194
 195 /*
 196  * the door will only accept door_call(3DOOR)s with a
 197  * data_size which is exactly sizeof (my_request_t).
 198  */
 199 .fi
 200 .in -2
 201
 202 .SH ATTRIBUTES
 203 .LP
 204 See \fBattributes\fR(5) for descriptions of the following attributes:
 205 .sp
 206
 207 .sp
 208 .TS
 209 box;
 210 c | c
 211 l | l .
 212 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 213 _
 214 Interface Stability     Stable
 215 _
 216 MT-Level        MT-Safe
 217 .TE
 218
 219 .SH SEE ALSO
 220 .LP
 221 \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBattributes\fR(5)
 222 .SH NOTES
 223 .LP
 224 The parameters that can be manipulated by \fBdoor_setparam()\fR are not the
 225 only limitation on the size of requests. If the door server thread's stack size
 226 is not large enough to hold all of the data requested plus room for processing
 227 the request, the door call will fail with \fBE2BIG\fR.
 228 .sp
 229 .LP
 230 The \fBDOOR_PARAM_DATA_MIN\fR parameter will not prevent \fBDOOR_UNREF_DATA\fR
 231 notifications from being sent to the door.