usr/src/man/man9e/open.9e

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\"  Copyright (c) 2008, 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 OPEN 9E "Apr 24, 2008"
   8 .SH NAME
   9 open \- gain access to a device
  10 .SH SYNOPSIS
  11 .SS "Block and Character"
  12 .LP
  13 .nf
  14 #include <sys/types.h>
  15 #include <sys/file.h>
  16 #include <sys/errno.h>
  17 #include <sys/open.h>
  18 #include <sys/cred.h>
  19 #include <sys/ddi.h>
  20 #include <sys/sunddi.h>
  21
  22
  23
  24 \fBint prefix\fR\fBopen\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR,
  25      \fBcred_t *\fR\fIcred_p\fR);
  26 .fi
  27
  28 .SS "STREAMS"
  29 .LP
  30 .nf
  31 #include <sys/file.h>
  32 #include <sys/stream.h>
  33 #include <sys/ddi.h>
  34 #include <sys/sunddi.h>
  35
  36
  37
  38 \fBint prefix\fR\fBopen\fR(\fBqueue_t *\fR\fIq\fR, \fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIoflag\fR, \fBint\fR \fIsflag\fR,
  39      \fBcred_t *\fR\fIcred_p\fR);
  40 .fi
  41
  42 .SH INTERFACE LEVEL
  43 .sp
  44 .LP
  45 Architecture independent level 1 (DDI/DKI). This entry point is required, but
  46 it can be \fBnulldev\fR(9F)
  47 .SH PARAMETERS
  48 .SS "Block and Character"
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIdevp\fR\fR
  53 .ad
  54 .RS 10n
  55 Pointer to a device number.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIflag\fR\fR
  62 .ad
  63 .RS 10n
  64 A bit field passed from the user program \fBopen\fR(2) system call that
  65 instructs the driver on how to open the file. Valid settings are:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBFEXCL\fR\fR
  70 .ad
  71 .RS 11n
  72 Open the device with exclusive access; fail all other attempts to open the
  73 device.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBFNDELAY\fR\fR
  80 .ad
  81 .RS 11n
  82 Open the device and return immediately. Do not block the open even if something
  83 is wrong.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBFREAD\fR\fR
  90 .ad
  91 .RS 11n
  92 Open the device with read-only permission, If \fBOR\fRed with \fBFWRITE\fR,
  93 allow both read and write access.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBFWRITE\fR\fR
 100 .ad
 101 .RS 11n
 102 Open a device with write-only permission. If ORed with \fBFREAD\fR, allow both
 103 read and write access.
 104 .RE
 105
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fIotyp\fR\fR
 112 .ad
 113 .RS 10n
 114 Parameter supplied for driver to determine how many times a device was opened
 115 and for what reasons. For \fBOTYP_BLK\fR and \fBOTYP_CHR\fR, the \fBopen()\fR
 116 function can be called many times, but the \fBclose\fR(9E) function is called
 117 only when the last reference to a device is removed. If the device is accessed
 118 through file descriptors, it is done by a call to \fBclose\fR(2) or
 119 \fBexit\fR(2). If the device is accessed through memory mapping, it is done by
 120 a call to  \fBmunmap\fR(2) or \fBexit\fR(2). For \fBOTYP_LYR\fR, there is
 121 exactly one \fBclose\fR(9E) for each \fBopen()\fR operation that is called.
 122 This permits software drivers to exist above hardware drivers and removes any
 123 ambiguity from the hardware driver regarding how a device is used.
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBOTYP_BLK\fR\fR
 128 .ad
 129 .RS 12n
 130 Open occurred through block interface for the device.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBOTYP_CHR\fR\fR
 137 .ad
 138 .RS 12n
 139 Open occurred through the raw/character interface for the device.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBOTYP_LYR\fR\fR
 146 .ad
 147 .RS 12n
 148 Open a layered process. This flag is used when one driver calls another
 149 driver's \fBopen()\fR or \fBclose\fR(9E) function. The calling driver ensures
 150 that there is one-layered close for each layered open. This flag applies to
 151 both block and character devices.
 152 .RE
 153
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fIcred_p\fR\fR
 160 .ad
 161 .RS 10n
 162 Pointer to the user credential structure.
 163 .RE
 164
 165 .SS "STREAMS"
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fIq\fR\fR
 170 .ad
 171 .RS 10n
 172 A pointer to the read \fBqueue\fR.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fIdevp\fR\fR
 179 .ad
 180 .RS 10n
 181 Pointer to a device number. For \fBSTREAMS \fRmodules, \fIdevp\fR always points
 182 to the device number associated with the driver at the end (tail) of the
 183 stream.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fIoflag\fR\fR
 190 .ad
 191 .RS 10n
 192 Valid \fIoflag\fR values are \fBFEXCL\fR, \fBFNDELAY\fR, \fBFREAD\fR, and
 193 \fBFWRITEL\fR \(em the same as those listed above for \fIflag.\fR. For
 194 \fBSTREAMS\fR modules, \fIoflag\fR is always set to \fB0\fR.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fIsflag\fR\fR
 201 .ad
 202 .RS 10n
 203 Valid values are as follows:
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBCLONEOPEN\fR\fR
 208 .ad
 209 .RS 13n
 210 Indicates that the \fBopen()\fR function is called through the clone driver.
 211 The driver should return a unique device number.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBMODOPEN\fR\fR
 218 .ad
 219 .RS 13n
 220 Modules should be called with \fIsflag\fR set to this value. Modules should
 221 return an error if they are called with \fIsflag\fR set to a different value.
 222 Drivers should return an error if they are called with \fIsflag\fR set to this
 223 value.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fB0\fR\fR
 230 .ad
 231 .RS 13n
 232 Indicates a driver is opened directly, without calling the clone driver.
 233 .RE
 234
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fIcred_p\fR\fR
 241 .ad
 242 .RS 10n
 243 Pointer to the user credential structure.
 244 .RE
 245
 246 .SH DESCRIPTION
 247 .sp
 248 .LP
 249 The driver's  \fBopen()\fR function is called by the kernel during an
 250 \fBopen\fR(2) or a \fBmount\fR(2) on the special file for the device. A device
 251 can be opened simultaneously by multiple processes and the \fBopen()\fR driver
 252 operation is called for each open. Note that a device is referenced once its
 253 associated \fBopen\fR(9E) function is entered, and thus \fBopen\fR(9E)
 254 operations which have not yet completed will prevent \fBclose\fR(9E) from being
 255 called. The function should verify that the minor number component of
 256 \fI*devp\fR is valid, that the type of access requested by \fIotyp\fR and
 257 \fIflag\fR is appropriate for the device, and, if required, check permissions
 258 using the user credentials pointed to by \fIcred_p\fR.
 259 .sp
 260 .LP
 261 The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the
 262 driver at *\fIdevp\fR, \fIotyp\fR granularity. This delays new \fBopen()\fR
 263 calls to the driver while a last-reference \fBclose()\fR call is executing. If
 264 the driver has indicated that an \fBEINTR\fR returns safe via the
 265 \fBD_OPEN_RETURNS_EINTR\fR \fBcb_ops\fR(9S) \fBcb_flag\fR, a delayed
 266 \fBopen()\fR may be interrupted by a signal that results in an \fBEINTR\fR
 267 return.
 268 .sp
 269 .LP
 270 Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically
 271 simplify driver writing. In some cases, however, they might be an impediment
 272 for certain types of drivers. To overcome any impediment, the driver can change
 273 minor numbers in \fBopen\fR(9E), as described below, or implement multiple
 274 minor nodes for the same device. Both techniques give the driver control over
 275 when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will
 276 be delayed while \fBclose()\fR is executing.
 277 .sp
 278 .LP
 279 The \fBopen()\fR function is passed a pointer to a device number so that the
 280 driver can change the minor number. This allows drivers to dynamically create
 281 minor instances of the device. An example of this might be a pseudo-terminal
 282 driver that creates a new pseudo-terminal whenever it is opened. A driver that
 283 chooses the minor number dynamically, normally creates only one minor device
 284 node in \fBattach\fR(9E) with \fBddi_create_minor_node\fR(9F). It then changes
 285 the minor number component of \fI*devp\fR using \fBmakedevice\fR(9F) and
 286 \fBgetmajor\fR(9F). The driver needs to keep track of available minor numbers
 287 internally. A driver that dynamically creates minor numbers might want to avoid
 288 returning the original minor number since returning the original minor will
 289 result in postponed dynamic opens when original minor \fBclose()\fR call
 290 occurs.
 291 .sp
 292 .in +2
 293 .nf
 294 *devp = makedevice(getmajor(*devp), new_minor);
 295 .fi
 296 .in -2
 297
 298 .SH RETURN VALUES
 299 .sp
 300 .LP
 301 The \fBopen()\fR function should return \fB0\fR for success, or the appropriate
 302 error number.
 303 .SH SEE ALSO
 304 .sp
 305 .LP
 306 \fBclose\fR(2), \fBexit\fR(2), \fBmmap\fR(2), \fBmount\fR(2), \fBmunmap\fR(2),
 307 \fBopen\fR(2), \fBIntro\fR(9E), \fBattach\fR(9E), \fBclose\fR(9E),
 308 \fBddi_create_minor_node\fR(9F), \fBgetmajor\fR(9F), \fBgetminor\fR(9F),
 309 \fBmakedevice\fR(9F), \fBnulldev\fR(9F), \fBcb_ops\fR(9S)
 310 .sp
 311 .LP
 312 \fIWriting Device Drivers\fR
 313 .sp
 314 .LP
 315 \fISTREAMS Programming Guide\fR
 316 .SH WARNINGS
 317 .sp
 318 .LP
 319 Do not attempt to change the major number.
 320 .sp
 321 .LP
 322 When a driver modifies the device number passed in, it must not change the
 323 major number portion of the device number. Unless CLONEOPEN is specified, the
 324 modified device number must map to the same driver instance indicated by the
 325 driver's getinfo(9e) implementation. In other words, cloning across different
 326 drivers is not supported. Cloning across different instances of the same driver
 327 in only permitted if the driver specified in \fBCLONE_DEV\fR in
 328 \fBddi_create_minor_node\fR(9F) is not supported.