open(D2) open(D2)
NAME
open - gain 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 prefixopen(dev_t *devp, int oflag, int otyp, cred_t *crp);
Block and Character Arguments
devp Pointer to a device number.
oflag Information passed from the user that instructs the
driver on how to open the file.
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/file.h>
#include <sys/stream.h>
#include <sys/errno.h>
#include <sys/cred.h>
#include <sys/ddi.h>
int prefixopen(queue_t *q, dev_t *devp, int oflag, int sflag, cred_t *crp);
STREAMS Arguments
q Pointer to the queue used to reference the read side of
the driver.
devp Pointer to a device number. For modules, devp always
points to the device number associated with the driver
at the end (tail) of the stream.
oflag Open flags.
sflag STREAMS flag.
Copyright 1994 Novell, Inc. Page 1
open(D2) open(D2)
crp Pointer to the user credential structure.
Return Values
The open routine should return 0 for success, or the
appropriate error number.
DESCRIPTION
Block and Character Description
The driver's open routine is called to prepare a device for
further access. It is called by the kernel during an open(2)
or a mount(2) of the device special file. For non-STREAMS
drivers, it can also be called from another (layered) driver.
The bit settings for oflag are found in file.h. Valid
settings are:
FEXCL Interpreted in a driver-dependent manner.
Some drivers interpret this flag to mean
open the device with exclusive access (fail
all other attempts to open the device.)
FNDELAY Open the device and return immediately
without sleeping (do not block the open even
if there is a problem.)
FNONBLOCK Open the device and return immediately
without sleeping (do not block the open even
if there is a problem.)
FREAD Open the device with read access permission.
FWRITE Open the device with write access
permission.
Valid values for otyp are defined in open.h. The values are
mutually exclusive:
OTYP_BLK Open occurred through block interface for
the device.
OTYP_CHR Open occurred through the raw/character
interface for the device.
OTYP_LYR Open a layered device. This flag is used
when one driver calls another driver's open
routine.
Copyright 1994 Novell, Inc. Page 2
open(D2) open(D2)
STREAMS Description
The STREAMS module open routine is called by the kernel during
an I_PUSH ioctl(2) or an autopush-style open [see
autopush(1M)].
Values for oflag are the same as those described for the block
and character open flags above.
The values for sflag are mutually exclusive:
CLONEOPEN Indicates a clone open (see below.) If the
driver supports cloning, it must assign and
return a device number of an unused device
by changing the value of the device number
to which devp points.
MODOPEN Indicates that an open routine is being
called for a module, not a driver. This is
useful in detecting configuration errors and
in determining how the driver is being used,
since STREAMS drivers can also be configured
as STREAMS modules.
0 Indicates a driver is being opened directly,
without cloning.
USAGE
This entry point is required in all drivers and STREAMS
modules.
The open routine could perform any of the following general
functions, depending on the type of device and the service
provided:
enable device interrupts
allocate buffers or other resources needed to use the
device
lock an unsharable device
notify the device of the open
change the device number if this is a clone open
Copyright 1994 Novell, Inc. Page 3
open(D2) open(D2)
enable put and service procedures for multithreaded
drivers
The open routine should verify that the minor number component
of devp is valid, that the type of access requested by otyp
and oflag is appropriate for the device, and, if required,
check permissions using the user credentials pointed to by crp
[see drv_priv(D3)].
For STREAMS drivers and modules, the open routine is called
with interrupts blocked from all STREAMS devices. If the
driver sets stream head options by sending an M_SETOPTS
message upstream from the open routine, then the changes are
guaranteed to take effect when the system call completes.
Support of cloning is optional. Cloning is the process of the
driver selecting an unused device for the user. It eliminates
the need to poll many devices when looking for an unused one.
Both STREAMS and Non-STREAMS drivers may implement cloning
behavior by changing the device number pointed to by devp. A
driver may designate certain minor devices as special clone
entry points into the driver. When these are opened, the
driver searches for an unused device and returns the new
device number by changing the value of the device number to
which devp points. Both the major device number and the minor
device number can be changed, although usually just the minor
number is changed. The major number is only changed when the
clone controls more than one device.
Using this method of cloning, a STREAMS driver will never see
sflag set to CLONEOPEN. A different method makes use of this
flag. STREAMS drivers can take advantage of a special driver,
known as the clone driver, to perform clone opens. This frees
the driver from having to reserve special minors for the clone
entry points. Here, the device node is actually that of the
clone driver (the major number is the major number from the
clone driver and the minor number is the major number from the
real driver.) When the clone driver is opened, it will call
the real driver open routine with sflag set to CLONEOPEN.
For STREAMS drivers and modules, for a given device number
(queue), only one instance of the open routine can be running
at any given time. However, multiple opens on any two
different device numbers (queues) can be running concurrently.
It is the responsibility of the driver or module to
synchronize access to its private data structures in this
Copyright 1994 Novell, Inc. Page 4
open(D2) open(D2)
case. For clone opens, multiple clone opens can run
concurrently, and it is the driver's responsibility to
synchronize access to its private data structures, as well as
allocation and deallocation of device numbers.
Synchronization Constraints
The open 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)].
REFERENCES
close(D2), drv_priv(D3), errnos(D5), qprocson(D3), queue(D4)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 5