share/man/man9/sleep.9

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