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.4 2004/07/16 05:04:36 hmp Exp $ 60.\" " 61.Dd May 10, 2004 62.Os 63.Dt SLEEP 9 64.Sh NAME 65.Nm tsleep , 66.Nm wakeup , 67.Nm wakeup_one 68.Nd wait/sleep/block for events 69.Sh SYNOPSIS 70.In sys/param.h 71.In sys/systm.h 72.In sys/proc.h 73.Ft int 74.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo" 75.Ft void 76.Fn wakeup "void *ident" 77.Ft void 78.Fn wakeup_one "void *ident" 79.Sh DESCRIPTION 80The functions 81.Fn tsleep 82and 83.Fn wakeup 84handle event-based process blocking. 85If a process must wait for an 86external event, it is put on sleep by 87.Nm tsleep . 88The parameter 89.Ar ident 90is an arbitrary address that uniquely identifies the event on which 91the process is being asleep. 92All processes sleeping on a single 93.Fa ident 94are woken up later by 95.Nm wakeup , 96often called from inside an interrupt routine, to indicate that the 97resource the process/thread was blocking on is available now. 98.Pp 99The parameter 100.Fa wmesg 101is a string describing the sleep condition for tools like 102.Xr ps 1 . 103Due to the limited space of those programs to display arbitrary strings, 104this message should not be longer than 6 characters. 105.Pp 106The 107.Fn wakeup_one 108function is used to make the first process/thread in the queue that is 109sleeping on the parameter 110.Fa ident 111runnable. 112This can prevent the system from becoming saturated 113when a large number of processes/threads are sleeping on the same address, 114but only one of them can actually do any useful work when made 115runnable. 116.Pp 117The 118.Fn tsleep 119function is general in its use and suspends the current process/thread until a 120wakeup is performed on the specified identifier. 121The process/thread will then be made runnable. 122The process/thread will sleep at most 123.Fa timo 124\&/ hz seconds (0 means no timeout). 125If 126.Fa flags 127contains the 128.Dv PCATCH 129flag, signals are checked before and after sleeping, else signals are 130ignored. 131.Sh IMPLEMENTATION NOTES 132Unlike 133.Fx , 134the 135.Fn tsleep 136function in 137.Dx 138ignores priority information because it is not required by the 139.Tn LWKT 140subsystem. 141Sleeps without the 142.Dv P_SINTR 143flag set are assumed to be disk-waits, otherwise they are 144normal sleeps. 145.Sh RETURN VALUES 146The 147.Fn tsleep 148function returns 149.Li 0 150if awakened, otherwise an appropriate error code is returned. 151.Sh ERRORS 152.Bl -tag -width Er 153.It Bq EWOULDBLOCK 154The timeout will expire. 155.It Bq ERESTART 156The signal needs to be delivered to the system call should and 157it should be restarted if possible. 158This only happens if 159.Dv PCATCH 160was set in 161.Fa flags . 162.It Bq EINTR 163The system needs to be interrupted by the signal. 164This only happens if 165.Dv PCATCH 166was set in 167.Fa flags . 168.El 169.Sh SEE ALSO 170.Xr ps 1 , 171.Xr malloc 9 172.Sh HISTORY 173The sleep/wakeup process synchronization mechanism is very old. 174It appeared in a very early version of Unix. 175.Pp 176.Nm Tsleep 177appeared in 178.Bx 4.4 . 179.Sh AUTHORS 180.An -nosplit 181This manual page was written by 182.An J\(:org Wunsch 183and modified for 184.Dx 185by 186.An Hiten Pandya Aq hmp@dragonflybsd.org 187