1.\" 2.\" Copyright (c) 1996 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd December 17, 1998 29.Os 30.Dt SLEEP 9 31.Sh NAME 32.Nm sleep , 33.Nm msleep , 34.Nm tsleep , 35.Nm wakeup 36.Nd wait for events 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/systm.h 40.In sys/proc.h 41.Ft int 42.Fn tsleep "void *ident" "int priority" "const char *wmesg" "int timo" 43.Ft int 44.Fn msleep "void *ident" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" 45.Ft void 46.Fn wakeup "void *ident" 47.Ft void 48.Fn wakeup_one "void *ident" 49.Sh DESCRIPTION 50The functions 51.Fn tsleep 52and 53.Fn wakeup 54handle event-based process blocking. 55If a process must wait for an 56external event, it is put on sleep by 57.Fn tsleep . 58The parameter 59.Fa ident 60is an arbitrary address that uniquely identifies the event on which 61the process is being asleep. All processes sleeping on a single 62.Fa ident 63are woken up later by 64.Fn wakeup , 65often called from inside an interrupt routine, to indicate that the 66resource the process was blocking on is available now. 67.Pp 68The parameter 69.Fa wmesg 70is a string describing the sleep condition for tools like 71.Xr ps 1 . 72Due to the limited space of those programs to display arbitrary strings, 73this message should not be longer than 6 characters. 74.Pp 75The 76.Fn wakeup_one 77function is used to make the first process in the queue that is 78sleeping on the parameter 79.Fa ident 80runnable. This can prevent the system from becoming saturated 81when a large number of processes are sleeping on the same address, 82but only one of them can actually do any useful work when made 83runnable. 84.Pp 85The 86.Fn tsleep 87function is the general sleep call. 88Suspends the current process until a wakeup is 89performed on the specified identifier. 90The process will then be made 91runnable with the specified 92.Fa priority . 93Sleeps at most 94.Fa timo 95\&/ hz seconds (0 means no timeout). 96If 97.Fa pri 98includes the 99.Dv PCATCH 100flag, signals are checked before and after sleeping, else signals are 101not checked. Returns 0 if awakened, 102.Er EWOULDBLOCK 103if the timeout expires. 104If 105.Dv PCATCH 106is set and a signal needs to be delivered, 107.Er ERESTART 108is returned if the current system call should be restarted if 109possible, and 110.Er EINTR 111is returned if the system call should be interrupted by the signal 112(return 113.Er EINTR ) . 114.Pp 115The 116.Fn msleep 117function is a variation on tsleep. 118The parameter 119.Fa mtx 120is a mutex which will be released before sleeping and reacquired before 121.Fn msleep 122returns. 123If 124.Fa pri 125includes the 126.Dv PDROP 127flag, the 128.Fa mtx 129parameter will not be reacquired before returning. 130The mutex is 131used to ensure that a condition can be checked atomically, and 132that the current process can be suspended without missing a 133change to the condition, or an associated wakeup. 134.Sh RETURN VALUES 135See above. 136.Sh SEE ALSO 137.Xr ps 1 , 138.Xr malloc 9 , 139.Xr mi_switch 9 140.Sh HISTORY 141The sleep/wakeup process synchronization mechanism is very old. 142It 143appeared in a very early version of 144.Ux . 145.Pp 146The 147.Fn tsleep 148function appeared in 149.Bx 4.4 . 150.Pp 151The 152.Fn sleep 153function used to be the traditional form. 154It did not let you specify a timeout or a 155.Fa wmesg , 156hence it was discontinued. 157.Sh AUTHORS 158.An -nosplit 159This man page was written by 160.An J\(:org Wunsch Aq joerg@FreeBSD.org . 161