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