1.\" 2.\" Copyright (c) 2004 Hiten Pandya <hmp@dragonflybsd.org> 3.\" Copyright (c) 1996 Joerg Wunsch 4.\" 5.\" All rights reserved. 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.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/sleep.9,v 1.18.2.5 2001/12/17 11:30:19 ru Exp $ 28.\" $DragonFly: src/share/man/man9/sleep.9,v 1.3 2004/05/10 12:04:36 hmp Exp $ 29.\" " 30.Dd May 10, 2004 31.Os 32.Dt SLEEP 9 33.Sh NAME 34.Nm tsleep , 35.Nm wakeup , 36.Nm wakeup_one 37.Nd wait/sleep/block for events 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/systm.h 41.In sys/proc.h 42.Ft int 43.Fn tsleep "void *ident" "int flag" "const char *wmesg" "int timo" 44.Ft void 45.Fn wakeup "void *ident" 46.Ft void 47.Fn wakeup_one "void *ident" 48.Sh DESCRIPTION 49The functions 50.Fn tsleep 51and 52.Fn wakeup 53handle event-based process blocking. 54If a process must wait for an 55external event, it is put on sleep by 56.Nm tsleep . 57The parameter 58.Ar ident 59is an arbitrary address that uniquely identifies the event on which 60the process is being asleep. 61All processes sleeping on a single 62.Fa ident 63are woken up later by 64.Nm wakeup , 65often called from inside an interrupt routine, to indicate that the 66resource the process/thread 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/thread in the queue that is 78sleeping on the parameter 79.Fa ident 80runnable. 81This can prevent the system from becoming saturated 82when a large number of processes/threads are sleeping on the same address, 83but only one of them can actually do any useful work when made 84runnable. 85.Pp 86The 87.Fn tsleep 88function is general in its use and suspends the current process/thread until a 89wakeup is performed on the specified identifier. 90The process/thread will then be made runnable. 91The process/thread will sleep at most 92.Fa timo 93\&/ hz seconds (0 means no timeout). 94If 95.Fa flags 96contains the 97.Dv PCATCH 98flag, signals are checked before and after sleeping, else signals are 99ignored. 100.Sh IMPLEMENTATION NOTES 101Unlike 102.Fx , 103the 104.Fn tsleep 105function in 106.Dx 107ignores priority information because it is not required by the 108.Tn LWKT 109subsystem. 110Sleeps without the 111.Dv P_SINTR 112flag set are assumed to be disk-waits, otherwise they are 113normal sleeps. 114.Sh RETURN VALUES 115The 116.Fn tsleep 117function returns 118.Li 0 119if awakened, otherwise an appropriate error code is returned. 120.Sh ERRORS 121.Bl -tag -width Er 122.It Bq EWOULDBLOCK 123The timeout will expire. 124.It Bq ERESTART 125The signal needs to be delivered to the system call should and 126it should be restarted if possible. 127This only happens if 128.Dv PCATCH 129was set in 130.Fa flags . 131.It Bq EINTR 132The system needs to be interrupted by the signal. 133This only happens if 134.Dv PCATCH 135was set in 136.Fa flags . 137.El 138.Sh SEE ALSO 139.Xr ps 1 , 140.Xr malloc 9 141.Sh HISTORY 142The sleep/wakeup process synchronization mechanism is very old. 143It appeared in a very early version of Unix. 144.Pp 145.Nm Tsleep 146appeared in 147.Bx 4.4 . 148.Sh AUTHORS 149.An -nosplit 150This manual page was written by 151.An J\(:org Wunsch 152and modified for 153.Dx 154by 155.An Hiten Pandya Aq hmp@dragonflybsd.org 156