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.11 2008/03/05 17:20:23 swildner Exp $ 60.\" " 61.Dd December 14, 2009 62.Os 63.Dt SLEEP 9 64.Sh NAME 65.Nm tsleep , 66.Nm ssleep , 67.Nm lksleep , 68.Nm zsleep , 69.Nm wakeup , 70.Nm wakeup_one 71.Nd wait/sleep/block for events 72.Sh SYNOPSIS 73.In sys/param.h 74.In sys/serialize.h 75.In sys/systm.h 76.In sys/proc.h 77.Ft int 78.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo" 79.Ft int 80.Fn ssleep "void *ident" "struct spinlock *spin" "int flag" "const char *wmesg" "int timo" 81.Ft int 82.Fn lksleep "void *ident" "struct lock *lock" "int flag" "const char *wmesg" "int timo" 83.Ft int 84.Fn zsleep "void *ident" "struct lwkt_serialize *slz" "int flag" "const char *wmesg" "int timo" 85.Ft void 86.Fn wakeup "void *ident" 87.Ft void 88.Fn wakeup_one "void *ident" 89.Sh DESCRIPTION 90The functions 91.Fn tsleep , 92.Fn ssleep , 93.Fn lksleep , 94.Fn zsleep , 95and 96.Fn wakeup 97handle event-based process blocking. 98If a process must wait for an 99external event, it is put on sleep by 100.Fn tsleep , 101.Fn ssleep , 102.Fn lksleep 103or 104.Fn zsleep . 105The parameter 106.Ar ident 107is an arbitrary address that uniquely identifies the event on which 108the process is being asleep. 109All processes sleeping on a single 110.Fa ident 111are woken up later by 112.Nm wakeup , 113often called from inside an interrupt routine, to indicate that the 114resource the process/thread was blocking on is available now. 115.Pp 116The parameter 117.Fa wmesg 118is a string describing the sleep condition for tools like 119.Xr ps 1 . 120Due to the limited space of those programs to display arbitrary strings, 121this message should not be longer than 6 characters. 122.Pp 123The 124.Fn wakeup_one 125function is used to make the first process/thread in the queue that is 126sleeping on the parameter 127.Fa ident 128runnable. 129This can prevent the system from becoming saturated 130when a large number of processes/threads are sleeping on the same address, 131but only one of them can actually do any useful work when made 132runnable. 133.Pp 134The 135.Fn tsleep 136function is general in its use and suspends the current process/thread until a 137wakeup is performed on the specified identifier. 138The process/thread will then be made runnable. 139The process/thread will sleep at most 140.Fa timo 141\&/ hz seconds (0 means no timeout). 142If 143.Fa flags 144contains the 145.Dv PCATCH 146flag, signals are checked before and after sleeping, else signals are 147ignored. 148.Pp 149The 150.Fn ssleep 151function works like 152.Fn tsleep 153while at the same time releasing the exclusive (write) spinlock 154.Fa spin 155before sleeping and reacquiring it before 156.Fn ssleep 157returns. 158This is an atomic operation, which guarantees that a 159.Fn wakeup 160interlocked by 161.Fa spin 162will not be missed. 163.Pp 164The 165.Fn lksleep 166function works like 167.Fn tsleep 168while at the same time releasing the exclusive lockmgr lock 169.Fa lock 170before sleeping and reacquiring it before 171.Fn lksleep 172returns. 173This is an atomic operation, which guarantees that a 174.Fn wakeup 175interlocked by 176.Fa lock 177will not be missed. 178.Pp 179The 180.Fn zsleep 181function works like 182.Fn tsleep 183while at the same time releasing the serializer 184.Fa slz 185before sleeping and reacquiring it before 186.Fn zsleep 187returns. 188This is an atomic operation, which guarantees that a 189.Fn wakeup 190interlocked by 191.Fa slz 192will not be missed. 193.Sh IMPLEMENTATION NOTES 194Unlike 195.Fx , 196the 197.Fn tsleep 198function in 199.Dx 200ignores priority information because it is not required by the 201.Tn LWKT 202subsystem. 203Sleeps without the 204.Dv LWP_SINTR 205flag set are assumed to be disk-waits, otherwise they are 206normal sleeps. 207.Sh RETURN VALUES 208The 209.Fn tsleep 210function returns 211.Li 0 212if awakened, otherwise an appropriate error code is returned. 213.Sh ERRORS 214.Bl -tag -width Er 215.It Bq Er EWOULDBLOCK 216The timeout expired. 217.It Bq Er ERESTART 218A signal needs to be delivered and the system call should 219be restarted if possible. 220This only happens if 221.Dv PCATCH 222was set in 223.Fa flags . 224.It Bq Er EINTR 225The system call needs to be interrupted by the signal. 226This only happens if 227.Dv PCATCH 228was set in 229.Fa flags . 230.El 231.Sh SEE ALSO 232.Xr ps 1 , 233.Xr kmalloc 9 , 234.Xr serializer 9 235.Sh HISTORY 236The sleep/wakeup process synchronization mechanism is very old. 237It appeared in a very early version of Unix. 238.Pp 239.Nm Tsleep 240appeared in 241.Bx 4.4 . 242.Sh AUTHORS 243.An -nosplit 244This manual page was written by 245.An J\(:org Wunsch 246and modified for 247.Dx 248by 249.An Hiten Pandya Aq hmp@dragonflybsd.org 250