share/man/man9/sleep.9

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