SCO OpenServer

sleep(D3oddi)

sleep -- suspend execution pending occurrence of an event

Synopsis

#include <sys/param.h>
#include <sys/types.h>

int sleep(caddr_t address, int priority);

Description

The sleep( ) function suspends task time processing in a driver. It is used when the driver needs to blcok until a resource is available or an I/O operation has completed. It is not guaranteed that when sleep returns, the event or resource that the driver has been waiting for will have occurred.

Arguments

address

Kernel address that represents an event for which the caller is waiting. This must be a unique number; a good way to ensure that the number is unique is to use the address of a global variable that is declared in your driver.

priority

A hint to the scheduling policy as to the relative priority the caller wishes to be assigned while running in the kernel after waking up. A lower priority places the process nearer the top of the run queue.

This value also determines whether the sleeping process can be interrupted by a software signal. of priority is used to determine whether the sleeping process can be interrupted by a software signal. If priority is less than PZERO, then the sleeping process cannot be interrupted by a software signal.

If the process sleeps in an interruptable state, priority can be OR'ed with PCATCH to have control return to the driver on a signal. If PCATCH is not set, a signal causes control to jump back to the process state just after the system call was made.

Return values

sleep returns 0 (zero) if a wakeup(D3oddi) routine has been called using the same address that was specified in the sleep call, or it returns 1 if the priority used has been ORed with PCATCH and the sleeping process has been sent a software signal.

If the driver sleeps with PCATCH set, the driver should be coded to handle catching the signal. The driver should clear any flags that were set and free temporarily allocated memory, then set u.u_error to EINTR, and return -1.

If priority has not been ORed with PCATCH and the sleeping process is interrupted by a software signal, sleep( ) does not return control to the device driver. Instead, sleep( ) returns control to the process state just after the system call was made. The system call invoked by the user process will return -1 and errno will be set to EINTR.

Usage

The address on which the process is sleeping is displayed as the WCHAN value through crash, scodb, and the ps -el command. During debugging, it is useful for the device driver writer to display this number with a CE_NOTE cmn_err(D3oddi) call.

Most processes should sleep at priorities greater than PZERO so that users are able to force termination of their processes by a software signal if an error occurs. A process should only sleep at a priority less than PZERO if it is guaranteed that the event for which it is waiting will occur within a short time.

See ``Examples'' on the wakeup(D3oddi) manual page for more information.

All locks that are held are released, in the opposite order of allocation, when the process goes to sleep, then reacquired on wakeup in the same order as they were originally allocated.

sleep( ) causes a PANIC in both uni- and multiprocessor systems if it is called from interrupt context or if it is called at STREAMS runtime.

Context and synchronization

User or blockable context.

Hardware applicability

All

Version applicability

oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

SVR5 DDI compatibility

Early DDI versions support the equivalent sleep(D3) function, although the priority argument is formed differently. For later DDI versions, use the synchronization variables instead; the SV_WAIT(D3) and SV_WAIT_SIG(D3) functions are used to block on a synchronization variable; see ``Synchronization variables'' in HDK Technical Reference for a comparison of sleep( ) to the synchronization variables.

Note that, while SCO OpenServer releases all spin locks when sleep( ) is called and reacquires them after the wakeup( ) is processed, the context of a DDI driver is changed to non-blockable when a lock is acquired, so DDI drivers cannot call sleep( ) while holding a spin lock.

References

delay(D3oddi), sleep(D3oddi), timeout(D3oddi), wakeup(D3oddi)

``Delays and busy-waits'' in HDK Technical Reference
``Synchronization variables'' in HDK Technical Reference