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