open(D2)
open - gain access to a device
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
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. 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. STREAMS Description The STREAMS module open routine is called by the kernel during an I_PUSH ioctl(2). 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 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 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), queue(D4)