1.\" $NetBSD: ltsleep.9,v 1.14 2012/01/28 13:26:12 wiz Exp $ 2.\" 3.\" Copyright (c) 1996, 2002, 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 28, 2012 31.Dt LTSLEEP 9 32.Os 33.Sh NAME 34.Nm ltsleep , 35.Nm tsleep , 36.Nm wakeup 37.Nd process context sleep and wakeup 38.Sh SYNOPSIS 39.In sys/proc.h 40.Ft int 41.Fn "tsleep" "wchan_t ident" "pri_t priority" "const char *wmesg" "int timo" 42.Ft void 43.Fn "wakeup" "wchan_t ident" 44.Sh DESCRIPTION 45.Em The interfaces described in this manual page are obsolete 46.Em and will be removed from a future version of the system. 47.Pp 48.Em The 49.Em Fn ltsleep 50.Em interface has been obsoleted and removed from the system. 51.Pp 52.Em Please see the 53.Xr condvar 9 , 54.Xr mutex 9 , 55.Em and 56.Xr rwlock 9 57.Em manual pages for information on kernel synchronisation primitives. 58.Pp 59These functions implement voluntary context switching. 60.Fn tsleep 61is used throughout the kernel whenever processing in the current context 62can not continue for any of the following reasons: 63.Bl -bullet -offset indent 64.It 65The current process needs to await the results of a pending I/O operation. 66.It 67The current process needs resources 68.Pq e.g., memory 69which are temporarily unavailable. 70.It 71The current process wants access to data-structures which are locked by 72other processes. 73.El 74.Pp 75The function 76.Fn wakeup 77is used to notify sleeping processes of possible changes to the condition 78that caused them to go to sleep. 79Typically, an awakened process will -- after it has acquired a context 80again -- retry the action that blocked its operation to see if the 81.Dq blocking 82condition has cleared. 83.Pp 84The 85.Fn tsleep 86function takes the following arguments: 87.Bl -tag -width priority 88.It Fa ident 89An identifier of the 90.Dq wait channel 91representing the resource for which the current process needs to wait. 92This typically is the virtual address of some kernel data-structure related 93to the resource for which the process is contending. 94The same identifier must be used in a call to 95.Fn wakeup 96to get the process going again. 97.Fa ident 98should not be 99.Dv NULL . 100.It Fa priority 101The process priority to be used when the process is awakened and put on 102the queue of runnable processes. 103This mechanism is used to optimize 104.Dq throughput 105of processes executing in kernel mode. 106If the flag 107.Dv PCATCH 108is OR'ed into 109.Fa priority 110the process checks for posted signals before and after sleeping. 111.It Fa wmesg 112A pointer to a character string indicating the reason a process is sleeping. 113The kernel does not use the string, but makes it available 114.Pq through the process structure field Li p_wmesg 115for user level utilities such as 116.Xr ps 1 . 117.It Fa timo 118If non-zero, the process will sleep for at most 119.Li timo/hz 120seconds. 121If this amount of time elapses and no 122.Fn wakeup "ident" 123has occurred, and no signal 124.Pq if Dv PCATCH No was set 125was posted, 126.Fn tsleep 127will return 128.Er EWOULDBLOCK . 129.El 130.Pp 131The 132.Fn wakeup 133function will mark all processes which are currently sleeping on the identifier 134.Fa ident 135as runnable. 136Eventually, each of the processes will resume execution in the kernel 137context, causing a return from 138.Fn tsleep . 139Note that processes returning from sleep should always re-evaluate the 140conditions that blocked them, since a call to 141.Fn wakeup 142merely signals a 143.Em possible 144change to the blocking conditions. 145For example, when two or more processes are waiting for an exclusive-access 146lock 147.Pq see Xr lock 9 , 148only one of them will succeed in acquiring the lock when it is released. 149All others will have to go back to sleep and wait for the next opportunity. 150.Sh RETURN VALUES 151.Fn tsleep 152returns 0 if it returns as a result of a 153.Fn wakeup . 154If a 155.Fn tsleep 156returns as a result of a signal, the return value is 157.Er ERESTART 158if the signal has the 159.Dv SA_RESTART 160property 161.Pq see Xr sigaction 2 , 162and 163.Er EINTR 164otherwise. 165If 166.Fn tsleep 167returns because of a timeout it returns 168.Er EWOULDBLOCK . 169.Sh SEE ALSO 170.Xr sigaction 2 , 171.Xr condvar 9 , 172.Xr hz 9 , 173.Xr lock 9 , 174.Xr mutex 9 , 175.Xr rwlock 9 176.Sh HISTORY 177The sleep/wakeup process synchronization mechanism is very old. 178It appeared in a very early version of Unix. 179.Fn tsleep 180appeared in 181.Bx 4.4 . 182.Fn ltsleep 183appeared in 184.Nx 1.5 . 185