share/man/man9/kpause.9

   1 .\"     $NetBSD: kpause.9,v 1.4 2008/04/30 13:10:58 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2006, 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Andrew Doran.
   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 .\" ------------------------------------------------------------
  31 .Dd January 2, 2008
  32 .Dt KPAUSE 9
  33 .Os
  34 .\" ------------------------------------------------------------
  35 .Sh NAME
  36 .Nm kpause
  37 .Nd make the calling LWP sleep
  38 .\" ------------------------------------------------------------
  39 .Sh SYNOPSIS
  40 .In sys/proc.h
  41 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  42 .Ft int
  43 .Fn kpause \
  44 "const char *wmesg" "bool intr" "int timeo" "kmutex_t *mtx"
  45 .\" ------------------------------------------------------------
  46 .Sh DESCRIPTION
  47 .Fn kpause
  48 makes the calling LWP sleep.
  49 It's similar to
  50 .Xr cv_timedwait_sig 9
  51 without the corresponding
  52 .Xr cv_signal 9 .
  53 .Pp
  54 .Fn kpause
  55 can wake up spontaneously.
  56 Callers should prepare to handle it.
  57 .Pp
  58 .Bl -tag -width wmesg
  59 .It Fa wmesg
  60 Specifies a string of no more than 8 characters that describes
  61 the resource or condition associated with the call of
  62 .Fn kpause .
  63 The kernel does not use this argument directly but makes it available for
  64 utilities such as
  65 .Xr ps 1
  66 to display.
  67 .It Fa intr
  68 If true, sleep interruptably.
  69 If the LWP receives a signal, or is interrupted by another condition such
  70 as its containing process exiting, the wait is ended early and an error
  71 code returned.
  72 .It Fa timeo
  73 Specify a timeout.
  74 It is an architecture and system dependent value related to the number of
  75 clock interrupts per second.
  76 See
  77 .Xr hz 9
  78 for details.
  79 The
  80 .Xr mstohz 9
  81 macro can be used to convert a timeout expressed in milliseconds to
  82 one suitable for
  83 .Fn kpause .
  84 .Pp
  85 Zero means no timeout.
  86 .It Fa mtx
  87 Convenience and symmetry with other synchronization operations.
  88 If not
  89 .Dv NULL ,
  90 .Fa mtx
  91 will be released once the LWP has prepared to sleep, and will be reacquired
  92 before
  93 .Fn kpause
  94 returns.
  95 .El
  96 .\" ------------------------------------------------------------
  97 .Sh RETURN VALUES
  98 .Fn kpause
  99 returns 0 when waking up spontaneously.
 100 Otherwise,
 101 It returns an error number.
 102 .\" ------------------------------------------------------------
 103 .Sh ERRORS
 104 .Bl -tag -width Er
 105 .It Bq Er EWOULDBLOCK
 106 The timeout expired.
 107 .It Bq Er ERESTART
 108 .Fn kpause
 109 returned as a result of a signal with
 110 .Dv SA_RESTART
 111 property.
 112 .It Bq Er EINTR
 113 .Fn kpause
 114 returned due to other reasons.
 115 Typically as a result of a signal without
 116 .Dv SA_RESTART
 117 property.
 118 .El
 119 .\" ------------------------------------------------------------
 120 .Sh SEE ALSO
 121 .Xr sigaction 2 ,
 122 .Xr errno 9 ,
 123 .Xr condvar 9 ,
 124 .Xr mstohz 9 ,
 125 .Xr hz 9