'\"macro stdmacro
.if n .pH ddi_dki.sleep @(#)sleep	40.7 of 11/16/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} sleep D3DK "" "DDI/DKI" "\&"
.if \nX=1 .ds x} sleep D3DK "" "DDI/DKI"
.if \nX=2 .ds x} sleep D3DK "" "\&"
.if \nX=3 .ds x} sleep "" "" "\&"
.TH \*(x}
.IX "\f4sleep\fP(D3DK)"
.SH NAME
\f4sleep\f1 \- suspend process activity pending execution of an event
.SH SYNOPSIS
.nf
.na
\f4#include <sys/types.h>
#include <sys/param.h>
.sp 0.5
int sleep(caddr_t \f2event, \f4int \f2priority\f4);\f1
.ad
.fi
.SH ARGUMENTS
.RS 0n 10
.IP "\f2event\f1" 10n
Address (signifying an event) for which the process will wait to be updated.
.IP "\f2priority\f1" 10n
Priority that is assigned to the process when it is awakened.
If \f2priority\f1 is \s-1OR\s0ed with the defined constant
\f4PCATCH\f1,
the \f4sleep\f1 function does not call \f4longjmp\f1 on receipt
of a signal.
Instead,
it returns the value \f41 \f1to the calling routine.
.RE
.SH DESCRIPTION
\f4sleep\f1 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 is available,
the driver may
need to call \f4sleep\f1 to wait for data to become available
before returning.
This causes the kernel to suspend executing
the process that called \f4sleep\f1 and schedule another process.
The process that called \f4sleep\f1 can be restarted by a call to the
\f4wakeup\f1(D3DK)
function with the same \f2event\f1 specified as that used to call
\f4sleep\f1.
.P
A driver (with data stored in local variables)
may call \f4sleep\f1 while waiting for an event to occur.
Make sure another process will not
interrupt the driver and overwrite the local variables.
.P
The \f2event\f1 address used when calling \f4sleep\f1 should be the
address of a kernel data structure or one of the driver's own data
structures.  The \f4sleep\f1 address is an arbitrary address that has
no meaning except to the corresponding \f4wakeup\f1 function call.
This does not mean that any arbitrary kernel address should be used for
\f4sleep\f1.  Doing this could conflict with other, unrelated
\f4sleep\f1/\f4wakeup\f1 operations in the kernel.  A kernel address
used for \f4sleep\f1 should be the address of a kernel data structure
directly associated with the driver I/O operation (for example, a buffer
assigned to the 
driver).
.P
Before a process calls \f4sleep\f1,
the driver usually sets a
flag in a driver data structure indicating the reason why \f4sleep\f1 is
being called.
.P
The \f2priority\f1 argument, called the \f4sleep\f1 priority, is used
for scheduling purposes when the process awakens.  This parameter has
critical effects on how the process that called \f4sleep\f1 reacts to
signals.  If the numerical value of the \f4sleep\f1 priority is less
than or equal to the constant \f4PZERO\f1 (defined in the
\f4sys/param.h\f1 header file), then the sleeping process will not
be awakened by a signal.  However, if the numerical value is greater
than \f4PZERO\f1, the system awakens the process that called
\f4sleep\f1 prematurely (that is, before the event on which
\f4sleep\f1 was called occurred) on receipt of a non-ignored, non-held signal.
In this case, it returns the value \f41\f1 to the calling routine if
\f4PCATCH\f1 is set; otherwise it does a \f4longjmp\f1 and never
returns to the driver.
If the event occurred, \f40\f1 is returned.
.P
To pick the correct \f4sleep\f1 priority, base your decision on
whether or not the process should be awakened on the receipt of a
signal.  If the driver calls \f4sleep\f1 for an event that is certain
to happen, the driver should use a priority numerically less than
or equal to \f4PZERO\f1.  (However, you should only use priorities less than or
equal to \f4PZERO\f1 if your driver is crucial to system operation.) 
If the driver calls \f4sleep\f1 while it awaits an event that may not
happen, use a priority numerically greater than \f4PZERO\f1.
.P
An example of an event that may not happen is the arrival of data from a
remote device. When the system tries to read data from a terminal, the
terminal driver might call \f4sleep\f1 to suspend the current process
while waiting for data to arrive from the terminal.  If data never
arrives, the \f4sleep\f1 call will never be answered.  When a user at
the terminal presses the 
BREAK
key or hangs up, the terminal driver interrupt handler sends a signal to
the reading process, which is still executing \f4sleep\f1.  The signal
causes the reading process to finish the system call without having read
any data.  If \f4sleep\f1 is called with a priority value that is not
awakened by signals, the process can be awakened only by a specific
\f4wakeup\f1 call.  If that \f4wakeup\f1 call never happened (the
user hung up the terminal), then the process executes \f4sleep\f1
until the system is rebooted.
.P
Another important criteria for selecting the appropriate priority is
how important the event or resource being waited for is to overall
system performance.  For example, disk I/O is often a bottleneck, so the
priority for disk I/O is higher than most other priorities.  In
contrast, terminal I/O is a much lower priority.  The
sooner the process runs, the faster the resource will be used and freed
again.
.P
Drivers calling \f4sleep\f1 must occasionally perform cleanup
operations before returning.
Typical items that need cleaning up
are locked data structures that should be unlocked when the system call
completes.  This is done by \s-1OR\s0ing \f2priority\f1 with
\f4PCATCH\f1 and executing \f4sleep\f1.  If \f4sleep\f1 returns a
\f41\f1, then you can cleanup any locked structures or free any
allocated resources, and return.
\f3CAUTION:\f1
If \f4sleep\f1 is called from the driver
\f4strategy\f1(D2DK) routine, you should \s-1OR\s0 the \f2priority\f1
argument with \f4PCATCH\f1 or select a \f2priority\f1 of \f4PZERO\f1
or less.
.SH RETURN VALUE
If the \f4sleep \f2priority\f1 argument is \s-1OR\s0ed with the defined constant
\f4PCATCH\f1,
the \f4sleep\f1 function does not call \f4longjmp\f1 on receipt
of a signal; instead,
it returns the value \f41\f1 to the calling routine.
If the
process put in a wait state by \f4sleep\f1 is awakened by an explicit
\f4wakeup\f1 call rather than by a signal,
the \f4sleep\f1 call
returns \f40\f1.
.SH LEVEL
Base Only  (Do not call from an interrupt routine)
.SH SEE ALSO
\f2BCI Driver Development Guide\f1, Chapter 10, ``Synchronizing Hardware and Software Events''
.P
.na
\f4delay\f1(D3DK),
\f4biodone\f1(D3DK),
\f4biowait\f1(D3DK),
\f4timeout\f1(D3DK),
\f4untimeout\f1(D3DK),
\f4wakeup\f1(D3DK)
.ad
.SH EXAMPLE
See the \f4untimeout\f1(D3DK) function page for an example of \f4sleep\f1.
