close(9E) Driver Entry Points close(9E)NAMEclose - relinquish access to a device
SYNOPSIS
Block and Character
#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
int prefixclose(dev_t dev, int flag, int otyp, cred_t *cred_p);
STREAMS
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
int prefixclose(queue_t *q, int flag, cred_t *cred_p);
INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI). This entry point is
required for block devices.
PARAMETERS
Block and Character
dev Device number.
flag File status flag, as set by the open(2) or modified by the
fcntl(2) system calls. The flag is for information only—the
file should always be closed completely. Possible values
are: FEXCL, FNDELAY, FREAD, FKLYR, and FWRITE. Refer to
open(9E) for more information.
otyp Parameter supplied so that the driver can determine how many
times a device was opened and for what reasons. The flags
assume the open() routine may be called many times, but the
close() routine should only be called on the last close()
of a device.
OTYP_BLK Close was through block interface for the
device.
OTYP_CHR Close was through the raw/character interface
for the device.
OTYP_LYR Close a layered process (a higher-level driver
called the close() routine of the device).
*cred_p Pointer to the user credential structure.
STREAMS
*q Pointer to queue(9S) structure used to reference the read
side of the driver. (A queue is the central node of a col‐
lection of structures and routines pointed to by a queue.)
flag File status flag.
*cred_p Pointer to the user credential structure.
DESCRIPTION
For STREAMS drivers, the close() routine is called by the kernel
through the cb_ops(9S) table entry for the device. (Modules use the
fmodsw table.) A non-null value in the d_str field of the cb_ops
entry points to a streamtab structure, which points to a qinit(9S)
containing a pointer to the close() routine. Non-STREAMS close() rou‐
tines are called directly from the cb_ops table.
close() 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.
A device may be opened simultaneously by multiple processes and the
open() driver routine is called for each open. For all otyp values
other than OTYP_LYR, the kernel calls the close() routine when the
last-reference occurs. For OTYP_LYR each close operation will call the
driver.
Kernel accounting for last-reference occurs at (dev, otyp) granular‐
ity. Note that a device is referenced once its associated open(9E)
routine is entered, and thus open(9E)'s which have not yet completed
will prevent close() from being called. The driver's close() call
associated with the last-reference going away is typically issued as
result of a close(2), exit(2), munmap(2), or umount(2). However, a
failed open(9E) call can cause this last-reference close() call to be
issued as a result of an open(2) or mount(2).
The kernel provides open()close() exclusion guarantees to the driver
at the same devp, otyp granularity as last-reference accounting. The
kernel delays new calls to the open() driver routine while the last-
reference close() call is executing. For example, a driver that blocks
in close() will not see new calls to open() until it returns from
close(). This effectively delays invocation of other cb_ops(9S) driver
entry points that also depend on an open(9E) established device refer‐
ence. If the driver has indicated that an EINTR return is safe via the
D_OPEN_RETURNS_EINTR cb_flag, then a delayed open() may be interrupted
by a signal, resulting in an EINTR return from open() prior to calling
open(9E).
Last-reference accounting and open()close() exclusion typically sim‐
plify driver writing. In some cases, however, they might be an impedi‐
ment for certain types of drivers. To overcome any impediment, the
driver can change minor numbers in open(9E), as described below, or
implement multiple minor nodes for the same device. Both techniques
give the driver control over when close() calls occur and whether addi‐
tional open() calls will be delayed while close() is executing.
In general, a close() routine should always check the validity of the
minor number component of the dev parameter. The routine should also
check permissions as necessary, by using the user credential structure
(if pertinent), and the appropriateness of the flag and otyp parame‐
ter values.
close() could perform any of the following general functions:
o disable interrupts
o hang up phone lines
o rewind a tape
o deallocate buffers from a private buffering scheme
o unlock an unsharable device (that was locked in the open()
routine)
o flush buffers
o notify a device of the close
o deallocate any resources allocated on open
The close() 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:
1. The write queue is given a chance to drain.
2. The close() routine is called.
3. The module or driver is removed from the stream.
RETURN VALUESclose() should return 0 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 dis‐
playing a message on the console or, in worst cases, triggering a sys‐
tem panic. Generally, a failure in a close() routine occurs because a
problem occurred in the associated device.
NOTES
If you use qwait_sig(9F), cv_wait_sig(9F) or cv_timedwait_sig(9F), you
should note that close() may be called in contexts in which signals
cannot be received. The ddi_can_receive_sig(9F) function is provided
to determine when this hazard exists.
SEE ALSOclose(2), fcntl(2), open(2), umount(2), detach(9E), open(9E),
ddi_can_receive_sig(9F), cb_ops(9S), qinit(9S), queue(9S)
Writing Device Drivers
STREAMS Programming Guide
SunOS 5.11 24 Apr 2008 close(9E)
