'\"macro stdmacro
.if n .pH ddi_dki.close @(#)close	40.8 of 10/10/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} close D2DK "" "DDI/DKI" "\&"
.if \nX=1 .ds x} close D2DK "" "DDI/DKI"
.if \nX=2 .ds x} close D2DK "" "\&"
.if \nX=3 .ds x} close "" "" "\&"
.TH \*(x}
.IX "\f4close\fP(D2DK)"
.SH NAME
\f4close\f1 \- relinquish access to a device
.SH "SYNOPSIS    [Block and Character]"
.nf
.na
\f4#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
.sp 0.5
int \f2prefix\f4close(dev_t \f2dev, \f4int \f2flag, \f4int \f2otyp, \f4cred_t *\f2cred_p\f4);\f1
.ad
.fi
.SH "ARGUMENTS"
.RS 0n
.IP "\f2dev\f1" 10n
Device number.
.IP "\f2flag\f1" 10n
File status flag, as set by the \f4open\f1(2) or modified by
the \f4fcntl\f1(2) system calls.
The flag is for information only\(emthe file should always be closed
completely.
The flag is taken from the \f4f_flag\f1 member of the
\f4file\f1 structure which is in \f4file.h\f1.   Possible values
are:  \f4FEXCL, FNDELAY, FREAD\f1, and \f4FWRITE\f1.  Refer to
\f4open\f1(D2D) for more information.  
.IP "\f2otyp\f1" 10n
Parameter supplied so that the driver can determine how many
times a device was opened and for what reasons.  The flags assume
the \f4open\f1 routine may be called many times, but the \f4close\f1
routine should only be called on the last \f4close\f1 of a device.
.RS 12n
.TP 12n
\f4OTYP_BLK\f1
close was through block interface for the device 
.TP
\f4OTYP_CHAR\f1
close was through the raw/character interface for the device
.TP
\f4OTYP_MNT\f1
close was called as a 
result of a \f4umount\f1(2) system call;
unmount the file system associated with the block device
.TP
\f4OTYP_SWP\f1
close a swapping device
.TP
\f4OTYP_LYR\f1
close a layered process (a higher-level driver called the
\f4close\f1 routine of the device)
.RE
.IP "\f2*cred_p\f1" 10n
Pointer to the \f4cred\f1(D4D) user credential structure.
.RE
.SH "SYNOPSIS          [STREAMS]"
.nf
.na
\f4#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>
.sp 0.5
int \f2prefix\f4close(queue_t *\f2q, \f4int \f2flag, \f4cred_t *\f2cred_p\f4);\f1
.ad
.fi
.SH "ARGUMENTS"
.RS 0n 8n
.IP "\f2*q\f1" 10n
Pointer to \f4queue\f1 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.) 
.IP "\f2flag\f1" 10n
File status flag.
.IP "\f2*cred_p\f1" 10n
Pointer to the \f4cred\f1(D4DK) user credential structure.
.RE
.SH "DESCRIPTION"
For STREAMS drivers, the \f4close\f1 routine is called
by the kernel through the \f4cdevsw\f1 table entry for the device.
(Modules use the \f4fmodsw\f1 table.)
A non-null value in the \f4d_str\f1 field of the \f4cdevsw\f1
entry points to a \f4streamtab\f1 structure, which points to a
\f4qinit\f1 structure containing a pointer to the \f4close\f1
routine.
Non-STREAMS \f4close\f1 routines are called directly from
the \f4bdevsw\f1 (block) or \f4cdevsw\f1 (character) tables.
.P
The \f4close\f1 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.
.P
A device may be opened simultaneously by multiple processes and the
\f4open\f1 driver routine is called for each open, but the kernel will
only call the \f4close\f1 routine when the last process using the
device issues a \f4close\f1(2) or \f4umount\f1(2) system call or
exits.  (An exception is a close occurring with the \f2otyp\f1 argument
set to \f4OTYP_LYR\f1, for which a close (also having \f2otyp\f1 =
\f4OTYP_LYR\f1) occurs for each open.)
.P
In general, a \f4close\f1 routine should always check the validity of
the minor number component of the \f2dev\f1 parameter.  The routine
should also check permissions as necessary, by using the
\f4cred\f1(D4D) structure (if pertinent), and the appropriateness of
the \f2flag\f1 and \f2otyp\f1 parameter values.
.P
A \f4close\f1 routine could perform any of the following general
functions:
.P
.PD 0
.IP
disable interrupts
.IP
hang up phone lines
.IP
rewind a tape
.IP
deallocate buffers from a private buffering scheme
.IP
unlock an unsharable device
(that was locked in the \f4open\f1 routine)
.IP
flush buffers
.IP
notify a device of the close
.IP
deallocate any resources allocated on open
.PD
.P
The \f4close\f1 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 2n
.TP 4n
1.
The write queue is given a chance to drain.
.TP
2.
The \f4close\f1 routine is called.
.TP
3.
The module or driver is removed from the stream.
.RE
.SH "RETURN VALUE"
The \f4close\f1 routine should return \f40\f1 for success, or the
appropriate error number.  Refer to Appendix A for a list of DDI/DKI
error numbers.  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 \f4close\f1
routine occurs because a problem occurred in the associated device.
.SH "SEE ALSO"
.na
\f4open\f1(D2D),
\f4cred\f1(D4DK)
.ad
