lib/libc/sys/nanosleep.2

   1 .\"     $NetBSD: nanosleep.2,v 1.23 2016/11/14 10:40:59 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1986, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd April 3, 2022
  31 .Dt NANOSLEEP 2
  32 .Os
  33 .Sh NAME
  34 .Nm nanosleep
  35 .Nd high resolution sleep
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In time.h
  40 .Ft int
  41 .Fo clock_nanosleep
  42 .Fa "clockid_t clock_id"
  43 .Fa "int flags"
  44 .Fa "const struct timespec *rqtp"
  45 .Fa "struct timespec *rmtp"
  46 .Fc
  47 .Ft int
  48 .Fo nanosleep
  49 .Fa "const struct timespec *rqtp"
  50 .Fa "struct timespec *rmtp"
  51 .Fc
  52 .Sh DESCRIPTION
  53 If the
  54 .Dv TIMER_ABSTIME
  55 flag is not set in the
  56 .Fa flags
  57 argument, then
  58 .Fn clock_nanosleep
  59 suspends execution of the calling thread until either the
  60 time interval specified by the
  61 .Fa rqtp
  62 argument has elapsed,
  63 or a signal is delivered to the calling process and its
  64 action is to invoke a signal-catching function or to terminate the
  65 process.
  66 The clock used to measure the time is specified by the
  67 .Fa clock_id
  68 argument.
  69 .Pp
  70 If the
  71 .Dv TIMER_ABSTIME
  72 flag is set in the
  73 .Fa flags
  74 argument, then
  75 .Fn clock_nanosleep
  76 suspends execution of the calling thread until either the value
  77 of the clock specified by the
  78 .Fa clock_id
  79 argument reaches the absolute time specified by the
  80 .Fa rqtp
  81 argument,
  82 or a signal is delivered to the calling process and its
  83 action is to invoke a signal-catching function or to terminate the
  84 process.
  85 If, at the time of the call, the time value specified by
  86 .Fa rqtp
  87 is less than or equal to the time value of the specified clock, then
  88 .Fn clock_nanosleep
  89 returns immediately and the calling thread is not suspended.
  90 .Pp
  91 The suspension time may be longer than requested due to the
  92 scheduling of other activity by the system.
  93 It is also subject to the allowed time interval deviation
  94 specified by the
  95 .Va kern.timecounter.alloweddeviation
  96 .Xr sysctl 8
  97 variable.
  98 An unmasked signal will terminate the sleep early, regardless of the
  99 .Dv SA_RESTART
 100 value on the interrupting signal.
 101 The
 102 .Fa rqtp
 103 and
 104 .Fa rmtp
 105 arguments can point to the same object.
 106 .Pp
 107 The following
 108 .Fa clock_id
 109 values are supported:
 110 .Pp
 111 .Bl -item -compact -offset indent
 112 .It
 113 CLOCK_MONOTONIC
 114 .It
 115 CLOCK_MONOTONIC_FAST
 116 .It
 117 CLOCK_MONOTONIC_PRECISE
 118 .It
 119 CLOCK_REALTIME
 120 .It
 121 CLOCK_REALTIME_FAST
 122 .It
 123 CLOCK_REALTIME_PRECISE
 124 .It
 125 CLOCK_SECOND
 126 .It
 127 CLOCK_UPTIME
 128 .It
 129 CLOCK_UPTIME_FAST
 130 .It
 131 CLOCK_UPTIME_PRECISE
 132 .El
 133 .Pp
 134 The
 135 .Fn nanosleep
 136 function behaves like
 137 .Fn clock_nanosleep
 138 with a
 139 .Fa clock_id
 140 argument of
 141 .Dv CLOCK_REALTIME
 142 and without the
 143 .Dv TIMER_ABSTIME
 144 flag in the
 145 .Fa flags
 146 argument.
 147 .Sh RETURN VALUES
 148 These functions return zero when the requested time has elapsed.
 149 .Pp
 150 If these functions return for any other reason, then
 151 .Fn clock_nanosleep
 152 will directly return the error number, and
 153 .Fn nanosleep
 154 will return \-1 with the global variable
 155 .Va errno
 156 set to indicate the error.
 157 If a relative sleep is interrupted by a signal and
 158 .Fa rmtp
 159 is
 160 .Pf non- Dv NULL ,
 161 the timespec structure it references is updated to contain the
 162 unslept amount (the request time minus the time actually slept).
 163 .Sh ERRORS
 164 These functions can fail with the following errors.
 165 .Bl -tag -width Er
 166 .It Bq Er EFAULT
 167 Either
 168 .Fa rqtp
 169 or
 170 .Fa rmtp
 171 points to memory that is not a valid part of the process
 172 address space.
 173 .It Bq Er EINTR
 174 The function was interrupted by the delivery of a signal.
 175 .It Bq Er EINVAL
 176 The
 177 .Fa rqtp
 178 argument specified a nanosecond value less than zero
 179 or greater than or equal to 1000 million.
 180 .It Bq Er EINVAL
 181 The
 182 .Fa flags
 183 argument contained an invalid flag.
 184 .It Bq Er EINVAL
 185 The
 186 .Fa clock_id
 187 argument was
 188 .Dv CLOCK_THREAD_CPUTIME_ID
 189 or an unrecognized value.
 190 .It Bq Er ENOTSUP
 191 The
 192 .Fa clock_id
 193 argument was valid but not supported by this implementation of
 194 .Fn clock_nanosleep .
 195 .El
 196 .Sh SEE ALSO
 197 .Xr clock_gettime 2 ,
 198 .Xr sigaction 2 ,
 199 .Xr sleep 3
 200 .Sh STANDARDS
 201 These functions conform to
 202 .St -p1003.1-2008 .
 203 .Sh HISTORY
 204 The predecessor of this system call,
 205 .Fn sleep ,
 206 appeared in
 207 .At v3 ,
 208 but was removed when
 209 .Xr alarm 3
 210 was introduced into
 211 .At v7 .
 212 The
 213 .Fn nanosleep
 214 system call has been available since
 215 .Nx 1.3
 216 and was ported to
 217 .Ox 2.1
 218 and
 219 .Fx 3.0 .