open(D2DK) —

.IX \f4open\fP(D2DK)

NAME

open − gain access to a device

SYNOPSIS [Block and Character]

#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
int prefixopen(dev_t ∗devp, int oflag, int otyp, cred_t ∗crp);

ARGUMENTS

devp Pointer to a device number.

oflag Information passed from the user that instructs the driver on how to open the file. The bit settings for the flag 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.

otyp Parameter supplied so that the driver can determine how many times a device was opened and for what reasons. All flags 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_MNT
The file system on the block device is being opened due to a mount(2) system call.

OTYP_DMP
Open a device for crash dump.

OTYP_SWP
Open a swapping device.

OTYP_LYR
Open a layered device. This flag is used when one driver calls another driver’s open routine.

crp Pointer to the user credential structure.

SYNOPSIS [STREAMS]

#include <sys/types.h>
#include <sys/file.h>
#include <sys/stream.h>
#include <sys/errno.h>
#include <sys/cred.h>
int prefixopen(queue_t ∗q, dev_t ∗devp, int oflag, int sflag, cred_t ∗crp);

ARGUMENTS [STREAMS]

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. Valid values are the same as those listed above.

sflag STREAMS flag. Values are mutually exclusive and are given as follows:

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.

crp Pointer to the user credential structure.

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 STREAMS module open routine is called by the kernel during an I_PUSH ioctl(2) or an autopush-style open [see autopush(1M)].

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

enable 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

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(D3DK)].

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.

NOTES

This entry point is required in all drivers. The open routine has user context and can sleep. Before returning, STREAMS drivers and modules must call qprocson(D3DK) to enable their put(D2DK) and service [srv(D2DK)] routines. Support of cloning is optional. 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 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.

RETURN VALUE

The open routine should return 0 for success, or the appropriate error number.

ERROR RETURN CODES

EAGAINTemporary resource allocation failure; try again later. Drivers can return this error when resource allocation fails, for example, kmem_alloc(D3DK) or allocb(D3DK).

EFAULTBad address. Drivers should return this error whenever a call to copyin(D3DK) or copyout(D3DK) fails.

EINTRInterrupted operation. Drivers can return this error whenever an interruptible operation is interrupted by receipt of an asynchronous signal.

EINVALInvalid argument. Drivers can return this error for operations that have invalid parameters specified.

EIOAn I/O error has occurred. Drivers can return this error when an input or output request has failed.

ENXIONo such device or address. Drivers can return this error when trying to open an invalid minor device, or when trying to perform I/O past the end of a device.

EPERMPermission denied. Drivers can return this error when the current process doesn’t have sufficient privilege for the operation attempted.

EROFSAn attempt was made to open for writing a read-only device.

Museum