sleep(D3)

NAME
     sleep - suspend process execution pending occurrence of an event

SYNOPSIS
     #include <sys/types.h>
     #include <sys/param.h>
     #include <sys/ddi.h>
     int sleep(caddr_t event, int flags);

   Arguments
     event
          Kernel address signifying an event for which the caller wishes to
          wait.

     flags
          Tells whether the sleep is interruptible or not.

DESCRIPTION
     sleep suspends execution of a process to await certain events such as
     reaching a known system state in hardware or software.  For instance,
     when a process wants to read a device and no data are available, the
     driver may need to call sleep to wait for data to become available before
     returning.  This causes the kernel to suspend execution of the process
     that called sleep and schedule another process.  The process that called
     sleep can be resumed by a call to the wakeup function with the same event
     specified as that used to call sleep.

   Return Values
     sleep returns 0 if the caller woke up because of a call to wakeup.  If
     the sleep is interrupted by a signal the sleep call returns a value of 1.

USAGE
   event Argument
     The address has no significance except that the same address must be
     passed to wakeup(D3) to resume the sleeping process.  The address used
     should be the address of a kernel data structure associated with the
     driver, or one of the driver's own data structures.  Use of arbitrary
     addresses not associated with a private data structure can result in
     conflict with other, unrelated sleep and wakeup operations in the kernel.

   flags Argument
     The value of the flags argument determines whether the sleep may be
     interrupted by signals.  If the value of flags is less than or equal to
     the value of the constant PZERO (defined in sys/param.h), the sleeping
     process will not be awakened by a signal.  If the value of flags is
     greater than PZERO the process will wake up prematurely (without a call
     to wakeup) upon receipt of a non-ignored, non-held signal and will
     normally return 1 to the calling code.
   General Considerations
     If a process were to sleep while it is manipulating global data inside a
     critical section of driver code, it would be possible for another process
     to execute base level driver code which manipulates the same data while
     the first process was sleeping, resulting in data corruption.  A driver
     should not sleep inside such a critical section unless it takes explicit
     steps to prevent concurrent access to the data (for example, the driver
     could implement its own locking protocol to protect the data).

     The value for flags should be selected based on whether or not a wakeup
     is certain to occur as well as the importance of the driver and of any
     resources that the driver will hold after waking up.  If the driver is
     holding or waiting for a critical kernel resource or is otherwise crucial
     to the performance of the system, and the corresponding call to wakeup is
     guaranteed to happen, the driver should specify a flags argument less
     than or equal to PZERO.  If the driver is less performance critical or it
     is possible that the wakeup may not occur, the driver should specify a
     flags argument greater than PZERO.

     sleep will normally return a 1 in the event of a signal, indicating that
     the calling routine should perform any necessary cleanup and then return.

   Level
     Base only.

   Synchronization Constraints
     Can sleep.

   Notes
     sleep and wakeup are not appropriate to use in most multiprocessing
     systems.  They are only useful if it is known that the driver or system
     service will only ever execute on a particular processor.

REFERENCES
     wakeup(D3)