close(D2)

NAME
     close - relinquish access to a device

SYNOPSIS
   Block and Character Synopsis
     #include <sys/types.h>
     #include <sys/file.h>
     #include <sys/errno.h>
     #include <sys/open.h>
     #include <sys/cred.h>
     #include <sys/ddi.h>
     int prefixclose(dev_t dev, int flag, int otyp, cred_t *crp);

   Block and Character Arguments
     dev       Device number.

     flag      File status flags.

     otyp      Parameter supplied so that the driver can determine how many
               times a device was opened and for what reasons.

     crp       Pointer to the user credential structure.

   STREAMS Synopsis
     #include <sys/types.h>
     #include <sys/stream.h>
     #include <sys/file.h>
     #include <sys/errno.h>
     #include <sys/cred.h>
     #include <sys/ddi.h>
     int prefixclose(queue_t *q, int flag, cred_t *crp);

   STREAMS Arguments
     q         Pointer to queue used to reference the read side of the driver.

     flag      File status flag.

     crp       Pointer to the user credential structure.

DESCRIPTION
   Block and Character Description
     The close routine 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.

     Valid values for flag and their definitions can be found in open(D2).

     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(2) 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 will be two calls to the driver's close routine; one when the block
     interface is finished being used, and one when the character interface is
     finished being used.

     For OTYP_LYR, there will be one such close for every corresponding open.
     Here, the driver should count each open and close based on the otyp
     parameter to determine when the device should really be closed.

   STREAMS Description
     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 non-persistent
     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.  Interrupts from STREAMS devices are blocked.

          3.  The close routine is called.

          4.  The module or driver is removed from the stream.

          5.  Any remaining messages on the queues are freed.

   Return Values
     The close routine should return 0 for success, or the appropriate error
     number.  Refer to errnos(D5) for a list of DDI/DKI error numbers.  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 in all drivers and STREAMS modules.

     A close routine could perform any of the following general functions,
     depending on the type of device and the service provided:

          disable device interrupts

          hang up phone lines

          rewind a tape

          deallocate buffers from a private buffering scheme

          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

   Synchronization Constraints
     The close routine has user context and can sleep.  However, STREAMS
     drivers and modules must sleep such that signals do not cause the sleep
     to longjump [see sleep(D3)].  Also, if a close routine does sleep, it is
     important that the driver writer synchronize the driver's open and close
     routines, since a driver can be reopened while being closed.

     If the FNDELAY or FNONBLOCK flags are specified in the flag argument, the
     driver should try to avoid sleeping, if possible, during close
     processing.

REFERENCES
     drv_priv(D3), errnos(D5), open(D2), queue(D4), unbufcall(D3),
     untimeout(D3), sleep(D3)