sleep(9)

NAME

sleep, msleep, tsleep, wakeup - wait for events

SYNOPSIS

#include <sys/param.h>
#include <sys/systm.h>
#include <sys/proc.h>
int
tsleep(void *ident, int priority,  const  char  *wmesg,  int
timo);
int
msleep(void  *ident,  struct  mtx  *mtx, int priority, const
char *wmesg,
        int timo);
void
wakeup(void *ident);
void
wakeup_one(void *ident);

DESCRIPTION

The functions tsleep() and wakeup() handle event-based pro

cess blocking.
If a process must wait for an external event, it is put on

sleep by
tsleep(). The parameter ident is an arbitrary address that

uniquely
identifies the event on which the process is being asleep.

All processes
sleeping on a single ident are woken up later by wakeup(),

often called
from inside an interrupt routine, to indicate that the re

source the process was blocking on is available now.

The parameter wmesg is a string describing the sleep condi

tion for tools
like ps(1). Due to the limited space of those programs to

display arbitrary strings, this message should not be longer than 6

characters.

The wakeup_one() function is used to make the first process

in the queue
that is sleeping on the parameter ident runnable. This can

prevent the
system from becoming saturated when a large number of pro

cesses are
sleeping on the same address, but only one of them can actu

ally do any
useful work when made runnable.

The tsleep() function is the general sleep call. Suspends

the current
process until a wakeup is performed on the specified identi

fier. The
process will then be made runnable with the specified

priority. Sleeps
at most timo / hz seconds (0 means no timeout). If the

Giant lock is not
held and mtx is NULL, then timo must be non-zero. If

priority includes
the PCATCH flag, signals are checked before and after sleep

ing, else signals are not checked. Returns 0 if awakened, EWOULDBLOCK if

the timeout
expires. If PCATCH is set and a signal needs to be deliv

ered, ERESTART
is returned if the current system call should be restarted

if possible,
and EINTR is returned if the system call should be inter

rupted by the
signal (return EINTR).

The msleep() function is a variation on tsleep. The parame

ter mtx is a
mutex which will be released before sleeping and reacquired

before
msleep() returns. If priority includes the PDROP flag, the

mtx parameter
will not be reacquired before returning. The mutex is used

to ensure
that a condition can be checked atomically, and that the

current process
can be suspended without missing a change to the condition,

or an associated wakeup.

RETURN VALUES

See above.

SEE ALSO

ps(1), malloc(9), mi_switch(9)

HISTORY

The sleep/wakeup process synchronization mechanism is very

old. It
appeared in a very early version of UNIX.

The tsleep() function appeared in 4.4BSD.

The sleep() function used to be the traditional form. It

did not let you
specify a timeout or a wmesg, hence it was discontinued.

AUTHORS

This manual page was written by Jorg Wunsch <joerg@FreeB

SD.org>.

BSD December 17, 1998

BSD