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.

     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)