SVR5
close(D2)
close --
relinquish access to a device
Synopsis
#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/stream.h>
#include <sys/ddi.h>
int prefixclose(void idata, channel_t channel, int oflags, cred_t *crp, queue_t q);
Description
The driver's close entry point routine
is called to terminate a connection, established by the
open(D2)
entry point routine, to the driver.
NOTE:
Starting with DDI version 8,
the syntax of the
close( )
entry point routine is the same
for STREAMS and non-STREAMS drivers.
Arguments
idata-
For hardware drivers,
a pointer to the device-specific instance data
as output by the CFG_ADD subfunction of the
config(D2)
entry point routine.
For software-only drivers, idata is undefined
and should not be referenced.
See
``Device instance'' in HDK Technical Reference.
channel-
Channel number used to select subcomponents
and/or operating modes of this device instance.
For STREAMS modules,
channel is undefined
and should not be referenced.
See
``Channel number'' in HDK Technical Reference.
oflags-
Contains the file flags set when the device was opened.
The driver can use this to determine
if the device was opened for reading (FREAD),
writing (FWRITE), and so on.
See
open(D2)
for a description of the values.
crp-
Pointer to the user credential structure.
q-
Pointer to the read-side STREAMS queue
for the device being closed.
For non-STREAMS drivers,
q is undefined and should not be referenced.
Return values
The
close( )
entry point routine should return 0 for success, or the
appropriate error number from
errnos(D5).
Return errors rarely occur, but if a failure is
detected, the driver should still close the device and then
decide whether the severity of the problem
warrants displaying a message on the console.
Usage
This entry point is required for all drivers.
It is called when the indicated channel is no longer in use.
This call will have been preceded by
one or more calls to the
open(D2)
entry point for the same idata and channel number.
After this call,
no driver entry point routines will be called
for this channel without a new
open(D2)
call.
The driver must flush all pages from the buffer cache
before returning from the last
close( )
operation of a "block device,"
even if the channel is still open
as a "character device."
Note that SDI HBA drivers
that support SDI passthrough operations
use a different form of this entry point routine; see
close(D2sdi).
On close, the driver typically performs
some or all of the following functions:
-
disable device interrupts
-
hang up phone lines
-
rewind a tape
-
unlock an unsharable device
(that was locked in the open routine)
-
flush buffers
-
notify a device of the close
-
cancel any pending timeout or bufcall routines
that access data that are deinitialized
or deallocated during close
-
deallocate any resources allocated on open
Context and synchronization
Blockable
context.
The driver can block but cannot do operations such as
copyout(D3)
that require access to
the requesting process's address space.
If the FNONBLOCK flag is set in oflags,
the driver must not wait for long-term conditions to change
in order to complete this operation.
It should, however, block for system resource allocations
such as memory allocations
if it needs to.
Hardware applicability
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
Differences between versions
In DDI versions prior to version 8,
the syntax of the
close( )
routine for non-STREAMS drivers is:
int prefixclose(dev_t dev, int oflags,
int otyp, cred_t *crp);
dev is
the device number for the device to be closed;
otyp is a parameter supplied so that the driver can determine
how many times a device was opened and for what reasons.
The values for otyp are mutually exclusive:
OTYP_BLK-
Close was through the block interface for the device.
OTYP_CHR-
Close was through the raw/character interface for the device.
OTYP_LYR-
Close a layered device.
This flag is used when one driver
calls another driver's close routine.
For OTYP_BLK and OTYP_CHR,
a device may be opened simultaneously by multiple processes and the
driver open routine is called for each open, but the kernel will
only call the close routine when the last process using the
device issues a
close
system call or exits.
There is one exception to this rule.
If a device is opened
through both its character and its block interfaces,
then there will be one close per interface.
For example, if the same device is opened
twice through its block interface
and three times through its character interface,
then there are two calls to the driver's
close( )
routine:
one to close the block interface
and one to close the character interface.
For OTYP_LYR,
there is one
close( )
call for every corresponding
open( )
call.
Thus, the driver must carefully examine
the otyp parameter for every
open( )
and
close( )
to determine when the device should really be closed.
In DDI versions prior to version 8,
close( )
is a named entry point for non-STREAMS drivers
and must be defined as a global symbol.
Some earlier versions of the documentation
claimed that this entry point had user context,
but this is not true in all cases.
External dependencies
For DDI 8 and later versions,
drivers must declare this entry point routine
in the d_close
member of their
drvops(D4)
structure.
Named entry point routines must be declared
in the driver's
Master(DSP/4dsp)
file.
The declaration for this entry point is
$entry close.
This applies only to non-STREAMS drivers
that use DDI versions prior to version 8.
SDI HBA drivers
that support passthrough operations
use a different form of this routine,
which is declared in the driver's
hba_info(D4sdi)
structure. See
close(D2sdi).
References
drv_priv(D3),
errnos(D5),
open(D2),
sleep(D3),
unbufcall(D3str),
untimeout(D3),
close(D2mdi),
close(D2sdi),
close(D2str)
Examples
See
``DDI: 8 sample driver'' in HDK code samples
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005