'\" te .\" Copyright 2003 AT&T .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved .\" 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. .\" 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. .\" 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] .TH CLOSE 9E "Apr 24, 2008" .SH NAME close \- relinquish access to a device .SH SYNOPSIS .SS "Block and Character" .LP .nf #include #include #include #include #include #include #include \fBint prefix\fR\fBclose\fR(\fBdev_t\fR \fIdev\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR, \fBcred_t *\fR\fIcred_p\fR); .fi .SS "STREAMS" .LP .nf #include #include #include #include #include #include #include #include \fBint prefix\fR\fBclose\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcred_p\fR); .fi .SH INTERFACE LEVEL .sp .LP Architecture independent level 1 (DDI/DKI). This entry point is \fIrequired\fR for block devices. .SH PARAMETERS .SS "Block and Character" .sp .ne 2 .na \fB\fIdev\fR\fR .ad .RS 11n Device number. .RE .sp .ne 2 .na \fB\fIflag\fR\fR .ad .RS 11n File status flag, as set by the \fBopen\fR(2) or modified by the \fBfcntl\fR(2) system calls. The flag is for information only\(emthe file should always be closed completely. Possible values are: \fBFEXCL\fR, \fBFNDELAY\fR, \fBFREAD,\fR \fBFKLYR,\fR and \fBFWRITE\fR. Refer to \fBopen\fR(9E) for more information. .RE .sp .ne 2 .na \fB\fIotyp\fR\fR .ad .RS 11n Parameter supplied so that the driver can determine how many times a device was opened and for what reasons. The flags assume the \fBopen()\fR routine may be called many times, but the \fBclose()\fR routine should only be called on the last \fBclose()\fR of a device. .sp .ne 2 .na \fB\fBOTYP_BLK\fR\fR .ad .RS 12n Close was through block interface for the device. .RE .sp .ne 2 .na \fB\fBOTYP_CHR\fR\fR .ad .RS 12n Close was through the raw/character interface for the device. .RE .sp .ne 2 .na \fB\fBOTYP_LYR\fR\fR .ad .RS 12n Close a layered process (a higher-level driver called the \fBclose()\fR routine of the device). .RE .RE .sp .ne 2 .na \fB\fI*cred_p\fR\fR .ad .RS 11n Pointer to the user credential structure. .RE .SS "STREAMS" .sp .ne 2 .na \fB\fI*q\fR\fR .ad .RS 11n Pointer to \fBqueue\fR(9S) structure used to reference the read side of the driver. (A queue is the central node of a collection of structures and routines pointed to by a queue.) .RE .sp .ne 2 .na \fB\fIflag\fR\fR .ad .RS 11n File status flag. .RE .sp .ne 2 .na \fB\fI*cred_p\fR\fR .ad .RS 11n Pointer to the user credential structure. .RE .SH DESCRIPTION .sp .LP For STREAMS drivers, the \fBclose()\fR routine is called by the kernel through the \fBcb_ops\fR(9S) table entry for the device. (Modules use the \fBfmodsw\fR table.) A non-null value in the \fBd_str\fR field of the \fBcb_ops\fR entry points to a \fBstreamtab\fR structure, which points to a \fBqinit\fR(9S) containing a pointer to the \fBclose()\fR routine. Non-STREAMS \fBclose()\fR routines are called directly from the \fBcb_ops\fR table. .sp .LP \fBclose()\fR ends the connection between the user process and the device, and prepares the device (hardware and software) so that it is ready to be opened again. .sp .LP A device may be opened simultaneously by multiple processes and the \fBopen()\fR driver routine is called for each open. For all \fIotyp\fR values other than \fBOTYP_LYR\fR, the kernel calls the \fBclose()\fR routine when the last-reference occurs. For \fBOTYP_LYR\fR each close operation will call the driver. .sp .LP Kernel accounting for last-reference occurs at (\fIdev\fR, \fIotyp\fR) granularity. Note that a device is referenced once its associated \fBopen\fR(9E) routine is entered, and thus \fBopen\fR(9E)'s which have not yet completed will prevent \fBclose()\fR from being called. The driver's \fBclose()\fR call associated with the last-reference going away is typically issued as result of a \fBclose\fR(2), \fBexit\fR(2), \fBmunmap\fR(2), or \fBumount\fR(2). However, a failed \fBopen\fR(9E) call can cause this last-reference \fBclose()\fR call to be issued as a result of an \fBopen\fR(2) or \fBmount\fR(2). .sp .LP The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the driver at the same \fIdevp\fR, \fIotyp\fR granularity as last-reference accounting. The kernel delays new calls to the \fBopen()\fR driver routine while the last-reference \fBclose()\fR call is executing. For example, a driver that blocks in \fBclose()\fR will not see new calls to \fBopen()\fR until it returns from \fBclose()\fR. This effectively delays invocation of other \fBcb_ops\fR(9S) driver entry points that also depend on an \fBopen\fR(9E) established device reference. If the driver has indicated that an \fBEINTR\fR return is safe via the \fBD_OPEN_RETURNS_EINTR\fR \fBcb_flag\fR, then a delayed \fBopen()\fR may be interrupted by a signal, resulting in an \fBEINTR\fR return from \fBopen()\fR prior to calling \fBopen\fR(9E). .sp .LP Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically simplify driver writing. In some cases, however, they might be an impediment for certain types of drivers. To overcome any impediment, the driver can change minor numbers in \fBopen\fR(9E), as described below, or implement multiple minor nodes for the same device. Both techniques give the driver control over when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will be delayed while \fBclose()\fR is executing. .sp .LP In general, a \fBclose()\fR routine should always check the validity of the minor number component of the \fIdev\fR parameter. The routine should also check permissions as necessary, by using the user credential structure (if pertinent), and the appropriateness of the \fIflag\fR and \fIotyp\fR parameter values. .sp .LP \fBclose()\fR could perform any of the following general functions: .RS +4 .TP .ie t \(bu .el o disable interrupts .RE .RS +4 .TP .ie t \(bu .el o hang up phone lines .RE .RS +4 .TP .ie t \(bu .el o rewind a tape .RE .RS +4 .TP .ie t \(bu .el o deallocate buffers from a private buffering scheme .RE .RS +4 .TP .ie t \(bu .el o unlock an unsharable device (that was locked in the \fBopen()\fR routine) .RE .RS +4 .TP .ie t \(bu .el o flush buffers .RE .RS +4 .TP .ie t \(bu .el o notify a device of the close .RE .RS +4 .TP .ie t \(bu .el o deallocate any resources allocated on open .RE .sp .LP The \fBclose()\fR routines of STREAMS drivers and modules are called when a stream is dismantled or a module popped. The steps for dismantling a stream are performed in the following order. First, any multiplexor links present are unlinked and the lower streams are closed. Next, the following steps are performed for each module or driver on the stream, starting at the head and working toward the tail: .RS +4 .TP 1. The write queue is given a chance to drain. .RE .RS +4 .TP 2. The \fBclose()\fR routine is called. .RE .RS +4 .TP 3. The module or driver is removed from the stream. .RE .SH RETURN VALUES .sp .LP \fBclose()\fR should return \fB0\fR for success, or the appropriate error number. Return errors rarely occur, but if a failure is detected, the driver should decide whether the severity of the problem warrants either displaying a message on the console or, in worst cases, triggering a system panic. Generally, a failure in a \fBclose()\fR routine occurs because a problem occurred in the associated device. .SH NOTES .sp .LP If you use \fBqwait_sig\fR(9F), \fBcv_wait_sig\fR(9F) or \fBcv_timedwait_sig\fR(9F), you should note that \fBclose()\fR may be called in contexts in which signals cannot be received. The \fBddi_can_receive_sig\fR(9F) function is provided to determine when this hazard exists. .SH SEE ALSO .sp .LP .BR close (2), .BR fcntl (2), .BR open (2), .BR umount (2), .BR detach (9E), .BR open (9E), .BR ddi_can_receive_sig (9F), .BR cb_ops (9S), .BR qinit (9S), .BR queue (9S) .sp .LP \fIWriting Device Drivers\fR .sp .LP \fISTREAMS Programming Guide\fR