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

   1 '\" te
   2 .\"  Copyright 2003 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 CLOSE 9E "Apr 24, 2008"
   8 .SH NAME
   9 close \- relinquish 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\fBclose\fR(\fBdev_t\fR \fIdev\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR, \fBcred_t *\fR\fIcred_p\fR);
  25 .fi
  26
  27 .SS "STREAMS"
  28 .LP
  29 .nf
  30 #include <sys/types.h>
  31 #include <sys/stream.h>
  32 #include <sys/file.h>
  33 #include <sys/errno.h>
  34 #include <sys/open.h>
  35 #include <sys/cred.h>
  36 #include <sys/ddi.h>
  37 #include <sys/sunddi.h>
  38
  39
  40
  41 \fBint prefix\fR\fBclose\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcred_p\fR);
  42 .fi
  43
  44 .SH INTERFACE LEVEL
  45 .sp
  46 .LP
  47 Architecture independent level 1 (DDI/DKI). This entry point is \fIrequired\fR
  48 for block devices.
  49 .SH PARAMETERS
  50 .SS "Block and Character"
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIdev\fR\fR
  55 .ad
  56 .RS 11n
  57 Device number.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIflag\fR\fR
  64 .ad
  65 .RS 11n
  66 File status flag, as set by the  \fBopen\fR(2) or modified by the
  67 \fBfcntl\fR(2) system calls. The flag is for information only\(emthe file
  68 should always be closed completely. Possible values are:   \fBFEXCL\fR,
  69 \fBFNDELAY\fR, \fBFREAD,\fR \fBFKLYR,\fR and  \fBFWRITE\fR. Refer to
  70 \fBopen\fR(9E) for more information.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIotyp\fR\fR
  77 .ad
  78 .RS 11n
  79 Parameter supplied so that the driver can determine how many times a device was
  80 opened and for what reasons.  The flags assume the  \fBopen()\fR routine may be
  81 called many times, but the  \fBclose()\fR routine should only be called on the
  82 last  \fBclose()\fR of a device.
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBOTYP_BLK\fR\fR
  87 .ad
  88 .RS 12n
  89 Close was through block interface for the device.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBOTYP_CHR\fR\fR
  96 .ad
  97 .RS 12n
  98 Close was through the raw/character interface for the device.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBOTYP_LYR\fR\fR
 105 .ad
 106 .RS 12n
 107 Close a layered process (a higher-level driver called the \fBclose()\fR routine
 108 of the device).
 109 .RE
 110
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fI*cred_p\fR\fR
 117 .ad
 118 .RS 11n
 119 Pointer to the  user credential structure.
 120 .RE
 121
 122 .SS "STREAMS"
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fI*q\fR\fR
 127 .ad
 128 .RS 11n
 129 Pointer to  \fBqueue\fR(9S) structure used to reference the read side of the
 130 driver.  (A queue is the central node of a collection of structures and
 131 routines pointed to by a queue.)
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fIflag\fR\fR
 138 .ad
 139 .RS 11n
 140 File status flag.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fI*cred_p\fR\fR
 147 .ad
 148 .RS 11n
 149 Pointer to the  user credential structure.
 150 .RE
 151
 152 .SH DESCRIPTION
 153 .sp
 154 .LP
 155 For STREAMS drivers, the  \fBclose()\fR routine is called by the kernel through
 156 the  \fBcb_ops\fR(9S) table entry for the device. (Modules use the \fBfmodsw\fR
 157 table.) A non-null value in the  \fBd_str\fR field of the  \fBcb_ops\fR entry
 158 points to a  \fBstreamtab\fR structure, which points to a \fBqinit\fR(9S)
 159 containing a pointer to the  \fBclose()\fR routine. Non-STREAMS  \fBclose()\fR
 160 routines are called directly from the  \fBcb_ops\fR table.
 161 .sp
 162 .LP
 163 \fBclose()\fR ends the connection between the user process and the device, and
 164 prepares the device (hardware and software) so that it is ready to be opened
 165 again.
 166 .sp
 167 .LP
 168 A device may be opened simultaneously by multiple processes and the
 169 \fBopen()\fR driver routine is called for each open. For all \fIotyp\fR values
 170 other than \fBOTYP_LYR\fR, the kernel calls the \fBclose()\fR routine when the
 171 last-reference occurs. For \fBOTYP_LYR\fR each close operation will call the
 172 driver.
 173 .sp
 174 .LP
 175 Kernel accounting for last-reference occurs at (\fIdev\fR, \fIotyp\fR)
 176 granularity.  Note that a device is referenced once its associated
 177 \fBopen\fR(9E) routine is entered, and thus \fBopen\fR(9E)'s  which have not
 178 yet completed will prevent \fBclose()\fR from  being called.  The driver's
 179 \fBclose()\fR call associated with the  last-reference going away is typically
 180 issued as result of a \fBclose\fR(2), \fBexit\fR(2), \fBmunmap\fR(2), or
 181 \fBumount\fR(2). However, a failed \fBopen\fR(9E) call can cause this
 182 last-reference \fBclose()\fR call to be issued as a result of an \fBopen\fR(2)
 183 or \fBmount\fR(2).
 184 .sp
 185 .LP
 186 The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the
 187 driver at the same \fIdevp\fR, \fIotyp\fR granularity as last-reference
 188 accounting. The kernel delays new calls to the  \fBopen()\fR driver routine
 189 while the last-reference \fBclose()\fR call is executing. For example, a driver
 190 that blocks in \fBclose()\fR will not see new  calls to \fBopen()\fR until it
 191 returns from \fBclose()\fR.  This effectively delays invocation of other
 192 \fBcb_ops\fR(9S) driver entry points that also depend on an \fBopen\fR(9E)
 193 established device reference. If the driver has indicated that an \fBEINTR\fR
 194 return is safe via the \fBD_OPEN_RETURNS_EINTR\fR \fBcb_flag\fR, then a delayed
 195 \fBopen()\fR may be interrupted by a signal, resulting in an \fBEINTR\fR return
 196 from \fBopen()\fR prior to calling \fBopen\fR(9E).
 197 .sp
 198 .LP
 199 Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically
 200 simplify driver writing. In some cases, however, they might be an impediment
 201 for certain types of drivers. To overcome any impediment, the driver can change
 202 minor numbers in \fBopen\fR(9E), as described below, or implement multiple
 203 minor nodes for the same device. Both techniques give the driver control over
 204 when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will
 205 be delayed while \fBclose()\fR is executing.
 206 .sp
 207 .LP
 208 In general, a  \fBclose()\fR routine should always check the validity of the
 209 minor number component of the  \fIdev\fR parameter.  The routine should also
 210 check permissions as necessary, by using the user credential structure (if
 211 pertinent), and the appropriateness of the  \fIflag\fR and  \fIotyp\fR
 212 parameter values.
 213 .sp
 214 .LP
 215 \fBclose()\fR could perform any of the following general functions:
 216 .RS +4
 217 .TP
 218 .ie t \(bu
 219 .el o
 220 disable interrupts
 221 .RE
 222 .RS +4
 223 .TP
 224 .ie t \(bu
 225 .el o
 226 hang up phone lines
 227 .RE
 228 .RS +4
 229 .TP
 230 .ie t \(bu
 231 .el o
 232 rewind a tape
 233 .RE
 234 .RS +4
 235 .TP
 236 .ie t \(bu
 237 .el o
 238 deallocate buffers from a private buffering scheme
 239 .RE
 240 .RS +4
 241 .TP
 242 .ie t \(bu
 243 .el o
 244 unlock an unsharable device (that was locked in the  \fBopen()\fR routine)
 245 .RE
 246 .RS +4
 247 .TP
 248 .ie t \(bu
 249 .el o
 250 flush buffers
 251 .RE
 252 .RS +4
 253 .TP
 254 .ie t \(bu
 255 .el o
 256 notify a device of the close
 257 .RE
 258 .RS +4
 259 .TP
 260 .ie t \(bu
 261 .el o
 262 deallocate any resources allocated on open
 263 .RE
 264 .sp
 265 .LP
 266 The  \fBclose()\fR routines of STREAMS drivers and modules are called when a
 267 stream is dismantled or a module popped. The steps for dismantling a stream are
 268 performed in the following order. First, any multiplexor links present are
 269 unlinked and the  lower streams are closed. Next, the following steps are
 270 performed for each module or driver on the stream, starting at the head and
 271 working toward the tail:
 272 .RS +4
 273 .TP
 274 1.
 275 The write queue is given a chance to drain.
 276 .RE
 277 .RS +4
 278 .TP
 279 2.
 280 The  \fBclose()\fR routine is called.
 281 .RE
 282 .RS +4
 283 .TP
 284 3.
 285 The module or driver is removed from the stream.
 286 .RE
 287 .SH RETURN VALUES
 288 .sp
 289 .LP
 290 \fBclose()\fR should return \fB0\fR for success, or the appropriate error
 291 number. Return errors rarely occur, but if a failure is detected, the driver
 292 should decide whether the severity of the problem warrants either displaying a
 293 message on the console or, in worst cases, triggering a system panic.
 294 Generally, a failure in a  \fBclose()\fR routine occurs because a problem
 295 occurred in the associated device.
 296 .SH NOTES
 297 .sp
 298 .LP
 299 If you use \fBqwait_sig\fR(9F), \fBcv_wait_sig\fR(9F) or
 300 \fBcv_timedwait_sig\fR(9F), you should note that \fBclose()\fR may be called in
 301 contexts in which signals cannot be received. The \fBddi_can_receive_sig\fR(9F)
 302 function is  provided to determine when this hazard exists.
 303 .SH SEE ALSO
 304 .sp
 305 .LP
 306 \fBclose\fR(2), \fBfcntl\fR(2), \fBopen\fR(2), \fBumount\fR(2),
 307 \fBdetach\fR(9E), \fBopen\fR(9E), \fBddi_can_receive_sig\fR(9F),
 308 \fBcb_ops\fR(9S), \fBqinit\fR(9S), \fBqueue\fR(9S)
 309 .sp
 310 .LP
 311 \fIWriting Device Drivers\fR
 312 .sp
 313 .LP
 314 \fISTREAMS Programming Guide\fR