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