1.\" 2.\" Copyright (c) 2004 The DragonFly Project. All rights reserved. 3.\" 4.\" This code is derived from software contributed to The DragonFly Project 5.\" by Hiten Pandya <hmp@backplane.com>. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 3. Neither the name of The DragonFly Project nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific, prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 31.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Copyright (c) 1996 Joerg Wunsch 35.\" 36.\" All rights reserved. 37.\" 38.\" Redistribution and use in source and binary forms, with or without 39.\" modification, are permitted provided that the following conditions 40.\" are met: 41.\" 1. Redistributions of source code must retain the above copyright 42.\" notice, this list of conditions and the following disclaimer. 43.\" 2. Redistributions in binary form must reproduce the above copyright 44.\" notice, this list of conditions and the following disclaimer in the 45.\" documentation and/or other materials provided with the distribution. 46.\" 47.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 48.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 49.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 50.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 51.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 52.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 53.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 54.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 55.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 56.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 57.\" 58.\" $FreeBSD: src/share/man/man9/sleep.9,v 1.18.2.5 2001/12/17 11:30:19 ru Exp $ 59.\" $DragonFly: src/share/man/man9/sleep.9,v 1.9 2007/12/05 20:34:12 swildner Exp $ 60.\" " 61.Dd January 9, 2007 62.Os 63.Dt SLEEP 9 64.Sh NAME 65.Nm tsleep , 66.Nm msleep , 67.Nm wakeup , 68.Nm wakeup_one 69.Nd wait/sleep/block for events 70.Sh SYNOPSIS 71.In sys/param.h 72.In sys/systm.h 73.In sys/proc.h 74.Ft int 75.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo" 76.Ft int 77.Fn msleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo" 78.Ft void 79.Fn wakeup "void *ident" 80.Ft void 81.Fn wakeup_one "void *ident" 82.Sh DESCRIPTION 83The functions 84.Fn tsleep , 85.Fn msleep 86and 87.Fn wakeup 88handle event-based process blocking. 89If a process must wait for an 90external event, it is put on sleep by 91.Fn tsleep 92or 93.Fn msleep . 94The parameter 95.Ar ident 96is an arbitrary address that uniquely identifies the event on which 97the process is being asleep. 98All processes sleeping on a single 99.Fa ident 100are woken up later by 101.Nm wakeup , 102often called from inside an interrupt routine, to indicate that the 103resource the process/thread was blocking on is available now. 104.Pp 105The parameter 106.Fa wmesg 107is a string describing the sleep condition for tools like 108.Xr ps 1 . 109Due to the limited space of those programs to display arbitrary strings, 110this message should not be longer than 6 characters. 111.Pp 112The 113.Fn wakeup_one 114function is used to make the first process/thread in the queue that is 115sleeping on the parameter 116.Fa ident 117runnable. 118This can prevent the system from becoming saturated 119when a large number of processes/threads are sleeping on the same address, 120but only one of them can actually do any useful work when made 121runnable. 122.Pp 123The 124.Fn tsleep 125function is general in its use and suspends the current process/thread until a 126wakeup is performed on the specified identifier. 127The process/thread will then be made runnable. 128The process/thread will sleep at most 129.Fa timo 130\&/ hz seconds (0 means no timeout). 131If 132.Fa flags 133contains the 134.Dv PCATCH 135flag, signals are checked before and after sleeping, else signals are 136ignored. 137.Pp 138The 139.Fn msleep 140function works like 141.Fn tsleep 142while at the same time releasing the exclusive (write) spinlock 143.Fa spin 144before sleeping and reacquiring it before 145.Fn msleep 146returns. 147This is an atomic operation, which guarantees that a 148.Fn wakeup 149interlocked by 150.Fa spin 151will not be missed. 152.Sh IMPLEMENTATION NOTES 153Unlike 154.Fx , 155the 156.Fn tsleep 157function in 158.Dx 159ignores priority information because it is not required by the 160.Tn LWKT 161subsystem. 162Sleeps without the 163.Dv LWP_SINTR 164flag set are assumed to be disk-waits, otherwise they are 165normal sleeps. 166.Sh RETURN VALUES 167The 168.Fn tsleep 169function returns 170.Li 0 171if awakened, otherwise an appropriate error code is returned. 172.Sh ERRORS 173.Bl -tag -width Er 174.It Bq Er EWOULDBLOCK 175The timeout expired. 176.It Bq Er ERESTART 177A signal needs to be delivered and the system call should 178be restarted if possible. 179This only happens if 180.Dv PCATCH 181was set in 182.Fa flags . 183.It Bq Er EINTR 184The system call needs to be interrupted by the signal. 185This only happens if 186.Dv PCATCH 187was set in 188.Fa flags . 189.El 190.Sh SEE ALSO 191.Xr ps 1 , 192.Xr kmalloc 9 193.Sh HISTORY 194The sleep/wakeup process synchronization mechanism is very old. 195It appeared in a very early version of Unix. 196.Pp 197.Nm Tsleep 198appeared in 199.Bx 4.4 . 200.Sh AUTHORS 201.An -nosplit 202This manual page was written by 203.An J\(:org Wunsch 204and modified for 205.Dx 206by 207.An Hiten Pandya Aq hmp@dragonflybsd.org 208