path: root/usr/src/man/man9e/open.9e

'\" te
.\"  Copyright 1989 AT&T
.\"  Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
.\"  Copyright 2019, Joyent, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH OPEN 9E "March 7, 2019"
.SH NAME
open \- gain access to a device
.SH SYNOPSIS
.SS "Block and Character"
.LP
.nf
#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint prefix\fR\fBopen\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR,
     \fBcred_t *\fR\fIcred_p\fR);
.fi

.SS "STREAMS"
.LP
.nf
#include <sys/file.h>
#include <sys/stream.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint prefix\fR\fBopen\fR(\fBqueue_t *\fR\fIq\fR, \fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIoflag\fR, \fBint\fR \fIsflag\fR,
     \fBcred_t *\fR\fIcred_p\fR);
.fi

.SH INTERFACE LEVEL
.LP
Architecture independent level 1 (DDI/DKI). This entry point is required, but
it can be \fBnulldev\fR(9F)
.SH PARAMETERS
.SS "Block and Character"
.ne 2
.na
\fB\fIdevp\fR\fR
.ad
.RS 10n
Pointer to a device number.
.RE

.sp
.ne 2
.na
\fB\fIflag\fR\fR
.ad
.RS 10n
A bit field passed from the user program \fBopen\fR(2) system call that
instructs the driver on how to open the file. Valid settings are:
.sp
.ne 2
.na
\fB\fBFEXCL\fR\fR
.ad
.RS 11n
Open the device with exclusive access; fail all other attempts to open the
device.
.RE

.sp
.ne 2
.na
\fB\fBFNDELAY\fR\fR
.ad
.RS 11n
Open the device and return immediately. Do not block the open even if something
is wrong.
.RE

.sp
.ne 2
.na
\fB\fBFREAD\fR\fR
.ad
.RS 11n
Open the device with read-only permission, If \fBOR\fRed with \fBFWRITE\fR,
allow both read and write access.
.RE

.sp
.ne 2
.na
\fB\fBFWRITE\fR\fR
.ad
.RS 11n
Open a device with write-only permission. If ORed with \fBFREAD\fR, allow both
read and write access.
.RE

.RE

.sp
.ne 2
.na
\fB\fIotyp\fR\fR
.ad
.RS 10n
Parameter supplied for driver to determine how many times a device was opened
and for what reasons. For \fBOTYP_BLK\fR and \fBOTYP_CHR\fR, the \fBopen()\fR
function can be called many times, but the \fBclose\fR(9E) function is called
only when the last reference to a device is removed. If the device is accessed
through file descriptors, it is done by a call to \fBclose\fR(2) or
\fBexit\fR(2). If the device is accessed through memory mapping, it is done by
a call to  \fBmunmap\fR(2) or \fBexit\fR(2). For \fBOTYP_LYR\fR, there is
exactly one \fBclose\fR(9E) for each \fBopen()\fR operation that is called.
This permits software drivers to exist above hardware drivers and removes any
ambiguity from the hardware driver regarding how a device is used.
.sp
.ne 2
.na
\fB\fBOTYP_BLK\fR\fR
.ad
.RS 12n
Open occurred through block interface for the device.
.RE

.sp
.ne 2
.na
\fB\fBOTYP_CHR\fR\fR
.ad
.RS 12n
Open occurred through the raw/character interface for the device.
.RE

.sp
.ne 2
.na
\fB\fBOTYP_LYR\fR\fR
.ad
.RS 12n
Open a layered process. This flag is used when one driver calls another
driver's \fBopen()\fR or \fBclose\fR(9E) function. The calling driver ensures
that there is one-layered close for each layered open. This flag applies to
both block and character devices.
.RE

.RE

.sp
.ne 2
.na
\fB\fIcred_p\fR\fR
.ad
.RS 10n
Pointer to the user credential structure.
.RE

.SS "STREAMS"
.ne 2
.na
\fB\fIq\fR\fR
.ad
.RS 10n
A pointer to the read \fBqueue\fR.
.RE

.sp
.ne 2
.na
\fB\fIdevp\fR\fR
.ad
.RS 10n
Pointer to a device number. For \fBSTREAMS \fRmodules, \fIdevp\fR always points
to the device number associated with the driver at the end (tail) of the
stream.
.RE

.sp
.ne 2
.na
\fB\fIoflag\fR\fR
.ad
.RS 10n
Valid \fIoflag\fR values are \fBFEXCL\fR, \fBFNDELAY\fR, \fBFREAD\fR, and
\fBFWRITEL\fR \(em the same as those listed above for \fIflag.\fR. For
\fBSTREAMS\fR modules, \fIoflag\fR is always set to \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fIsflag\fR\fR
.ad
.RS 10n
Valid values are as follows:
.sp
.ne 2
.na
\fB\fBCLONEOPEN\fR\fR
.ad
.RS 13n
Indicates that the \fBopen()\fR function is called through the clone driver.
The driver should return a unique device number.
.RE

.sp
.ne 2
.na
\fB\fBMODOPEN\fR\fR
.ad
.RS 13n
Modules should be called with \fIsflag\fR set to this value. Modules should
return an error if they are called with \fIsflag\fR set to a different value.
Drivers should return an error if they are called with \fIsflag\fR set to this
value.
.RE

.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 13n
Indicates a driver is opened directly, without calling the clone driver.
.RE

.RE

.sp
.ne 2
.na
\fB\fIcred_p\fR\fR
.ad
.RS 10n
Pointer to the user credential structure.
.RE

.SH DESCRIPTION
.LP
The driver's  \fBopen()\fR function is called by the kernel during an
\fBopen\fR(2) or a \fBmount\fR(2) on the special file for the device. A device
can be opened simultaneously by multiple processes and the \fBopen()\fR driver
operation is called for each open. Note that a device is referenced once its
associated \fBopen\fR(9E) function is entered, and thus \fBopen\fR(9E)
operations which have not yet completed will prevent \fBclose\fR(9E) from being
called. The function should verify that the minor number component of
\fI*devp\fR is valid, that the type of access requested by \fIotyp\fR and
\fIflag\fR is appropriate for the device, and, if required, check permissions
using the user credentials pointed to by \fIcred_p\fR.
.sp
.LP
When exclusive access is requested by including the \fBFEXCL\fR flag in
\fIflag\fR or \fIoflag\fR, but the caller cannot be granted exclusive access
to the device because it is already open, then the device driver should
conventionally return \fBEBUSY\fR. If instead, exclusive opens are not
supported, then the driver should return \fBENOTSUP\fR or \fBEINVAL\fR.
.sp
.LP
The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the
driver at *\fIdevp\fR, \fIotyp\fR granularity. This delays new \fBopen()\fR
calls to the driver while a last-reference \fBclose()\fR call is executing. If
the driver has indicated that an \fBEINTR\fR returns safe via the
\fBD_OPEN_RETURNS_EINTR\fR \fBcb_ops\fR(9S) \fBcb_flag\fR, a delayed
\fBopen()\fR may be interrupted by a signal that results in an \fBEINTR\fR
return.
.sp
.LP
Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically
simplify driver writing. In some cases, however, they might be an impediment
for certain types of drivers. To overcome any impediment, the driver can change
minor numbers in \fBopen\fR(9E), as described below, or implement multiple
minor nodes for the same device. Both techniques give the driver control over
when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will
be delayed while \fBclose()\fR is executing.
.sp
.LP
The \fBopen()\fR function is passed a pointer to a device number so that the
driver can change the minor number. This allows drivers to dynamically create
minor instances of the device. An example of this might be a pseudo-terminal
driver that creates a new pseudo-terminal whenever it is opened. A driver that
chooses the minor number dynamically, normally creates only one minor device
node in \fBattach\fR(9E) with \fBddi_create_minor_node\fR(9F). It then changes
the minor number component of \fI*devp\fR using \fBmakedevice\fR(9F) and
\fBgetmajor\fR(9F). The driver needs to keep track of available minor numbers
internally. A driver that dynamically creates minor numbers might want to avoid
returning the original minor number since returning the original minor will
result in postponed dynamic opens when original minor \fBclose()\fR call
occurs.
.sp
.in +2
.nf
*devp = makedevice(getmajor(*devp), new_minor);
.fi
.in -2

.SH RETURN VALUES
.LP
The \fBopen()\fR function should return \fB0\fR for success, or the appropriate
error number.
.SH SEE ALSO
.LP
.BR close (2),
.BR exit (2),
.BR mmap (2),
.BR mount (2),
.BR munmap (2),
.BR open (2),
.BR Intro (9E),
.BR attach (9E),
.BR close (9E),
.BR ddi_create_minor_node (9F),
.BR getmajor (9F),
.BR getminor (9F),
.BR makedevice (9F),
.BR nulldev (9F),
.BR cb_ops (9S)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fISTREAMS Programming Guide\fR
.SH WARNINGS
.LP
Do not attempt to change the major number.
.sp
.LP
When a driver modifies the device number passed in, it must not change the
major number portion of the device number. Unless CLONEOPEN is specified, the
modified device number must map to the same driver instance indicated by the
driver's getinfo(9e) implementation. In other words, cloning across different
drivers is not supported. Cloning across different instances of the same driver
in only permitted if the driver specified in \fBCLONE_DEV\fR in
\fBddi_create_minor_node\fR(9F) is not supported.