'\"macro stdmacro
.if n .pH ddi_dki.open @(#)open	40.6 of 11/16/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} open D2DK "" "DDI/DKI" "\&"
.if \nX=1 .ds x} open D2DK "" "DDI/DKI"
.if \nX=2 .ds x} open D2DK "" "\&"
.if \nX=3 .ds x} open "" "" "\&"
.TH \*(x}
.IX "\f4open\fP(D2DK)"
.SH "NAME"
\f4open\f1 \- gain 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>
.sp 0.5
\f2prefix\f4open(\f4dev_t *\f2dev, \f4int\f1 \f2flag, \f4int\f1 \f2otyp, \f4cred_t *\f1\f2cred_p\f4);\f1
.ad
.fi
.SH "ARGUMENTS"
.RS 0n
.IP "\f2dev\f1" 10n
Pointer to a device number.
.IP "\f2flag\f1" 10n
Information passed from the user program \f4open\f1(2) or
\f4create\f1(2) system call instructs the driver on
how to open the file.  The bit settings for the flag are found in
\f4file.h\f1 associated with the \f4f_flag\f1 member of the
\f4file\f1 structure.  Valid settings are:
.RS 12
.TP 12
\f4FNDELAY\f1
open the device and return immediately without sleeping (do not block
the open even if there is a problem) 
.TP
\f4FREAD\f1
open the device with read-only permission
(if \s-1OR\s0ed with \f4FWRITE\f1, then allow both read and write access)
.TP
\f4FWRITE\f1
open a device with write-only permission
(if \s-1OR\s0ed with \f4FREAD\f1, then allow both read and write access)
.RE
.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.  
All flags are defined in \f4open.h\f1.
.RS 12
.TP 12
\f4OTYP_BLK\f1
open occurred through block interface for the device 
.TP 
\f4OTYP_CHAR\f1
open occurred through the raw/character interface for the device
.TP
\f4OTYP_MNT\f1
the file system on the block device is being opened due to a
\f4mount\f1(2) system call
.TP
\f4OTYP_SWP\f1
open a swapping device
.TP
\f4OTYP_LYR\f1
open a layered process.
This flag is used when one driver
calls another driver's \f4open\f1 or \f4close\f1 routine.
In this case,
there is exactly one \f4close\f1 for each \f4open\f1 called.
This permits software drivers to exist above hardware drivers
and removes any ambiguity from the hardware driver
regarding how a device is used.
This flag applies to both block and character devices.
.RE
.IP "\f2*cred_p\f1" 10n
Pointer to the \f4cred\f1(D4DK) user credential structure.
.RE
.SH "SYNOPSIS     [STREAMS]"
.nf
.na
\f4#include <sys/file.h>
#include <sys/stream.h>
.sp 0.5
\f2prefix\f4open(\f4queue_t *\f1\f2q, \f4dev_t *\f1\f2dev, \f4int\f1 \f2oflag, \f4int\f1 \f2sflag, \f4cred_t *\f2cred_p\f4);\f1
.ad
.fi
.SH "ARGUMENTS     [STREAMS]"
.RS 0n
.IP "\f2*q\f1" 10n
A pointer to the read \f4queue\f1. (A queue is the central node of a
collection of structures and routines pointed to by a queue.)
.IP "\f2*dev\f1" 10n
Pointer to a device number.  For modules, \f2*dev\f1 always points to the
device number associated with the driver at the end (tail) of the stream.
.IP "\f2oflag\f1" 10n
Valid \f2oflag\f1 values are the same as those listed above, with the
exception that \f4FAPPEND, FCREAT\f1,
and \f4FTRUNC\f1 have no meaning to a STREAMS
device.
For modules, \f2oflag\f1 is always set to \f40.
.IP "\f2sflag\f1" 10n
Valid values are as follows:
.P
.RS 12
.TP 12
\f4CLONEOPEN
Eliminates the need for user processes to poll many minor devices when
looking for an unused one.  If the driver wishes to assign the
device a device file, the \f4open\fP routine must assign and return
a minor number.  If no device file is required, the \f4open\fP
routine does not have to return a minor number.
.TP
\f4MODOPEN\f1
Indicates that an \f4open\f1 routine is being called
for a module, not a driver.  Drivers should return error numbers or
0 if an open is attempted with \f2sflag\f1 set to \f4MODOPEN\f1.
.TP
\f40\f1
Indicates a driver opened directly, without
calling the clone driver.
.RE
.IP "\f2*cred_p\f1" 10n
Pointer to the \f4cred\f1(D4DK) user credential structure.
.RE
.SH "DESCRIPTION"
The driver's \f4open\f1 routine is called by
the kernel through the \f4cdevsw\f1 or \f4bdevsw\f1 entry for the
device during an \f4open\f1(2) or a \f4mount\f1(2) on the special file
for the device.  The routine should verify that the minor number component of
\f2dev\f1 is valid, that the type of access requested by \f2otyp\f1
and \f2flag\f1 is appropriate for the device, and, if required,
check permissions using the user credentials pointed to by \f2cred_p\f1.
.SH "RETURN VALUE"
The \f4open\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.
.SH "SEE ALSO"
.na
\f4close\f1(D2DK)
.ad
