lib/libc/sys/nanosleep.2

   1 .\"     $NetBSD: nanosleep.2,v 1.13 2012/10/08 18:08:40 njoly 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 .\"     @(#)sleep.3     8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd October 1, 2012
  33 .Dt NANOSLEEP 2
  34 .Os
  35 .Sh NAME
  36 .Nm nanosleep
  37 .Nd high resolution sleep
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In time.h
  42 .Ft int
  43 .Fn clock_nanosleep "clockid_t clock_id" "int flags" "const struct timespec *rqtp" "struct timespec *rmtp"
  44 .Ft int
  45 .Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp"
  46 .Sh DESCRIPTION
  47 If the
  48 .Dv TIMER_ABSTIME
  49 flag is not set in the
  50 .Fa flags
  51 argument, then
  52 .Fn clock_nanosleep
  53 suspends execution of the calling thread until either the number of
  54 seconds and nanoseconds specified in the
  55 .Fa rqtp
  56 argument have elapsed using the clock in the
  57 .Fa clock_id
  58 argument, or a signal is delivered to the calling process and its
  59 action is to invoke a signal catching function or to terminate the
  60 process.
  61 .Pp
  62 If the
  63 .Dv TIMER_ABSTIME
  64 flag is set in the
  65 .Fa flags
  66 argument, then
  67 .Fn clock_nanosleep
  68 suspends execution of the calling thread until either the value
  69 of the clock specified in the
  70 .Fa clock_id
  71 argument reaches the value of the
  72 .Fa rqtp
  73 argument in seconds and nanoseconds,
  74 or a signal is delivered to the calling process and its
  75 action is to invoke a signal catching function or to terminate the
  76 process.
  77 .Pp
  78 The suspension time may be longer than requested due to the
  79 scheduling of other activity by the system.
  80 .Pp
  81 The
  82 .Fn nanosleep
  83 function behaves like
  84 .Fn clock_nanosleep
  85 with the
  86 .Fa clock_id
  87 argument equal to
  88 .Dv CLOCK_MONOTONIC
  89 and the
  90 .Fa flags
  91 argument having
  92 .Dv TIMER_ABSTIME
  93 not set.
  94 .Pp
  95 The
  96 .Em struct timespec
  97 is described in
  98 .Xr timespec 3 .
  99 The
 100 .Fa clock_id
 101 specified is the time source.
 102 .Sh RETURN VALUES
 103 If the
 104 .Fn clock_nanosleep
 105 or the
 106 .Fn nanosleep
 107 functions return because the requested time has elapsed, the value
 108 returned will be zero.
 109 .Pp
 110 If the
 111 .Fn clock_nanosleep
 112 or the
 113 .Fn nanosleep
 114 functions return due to the delivery of a signal, the value returned
 115 will be the \-1, and the global variable
 116 .Va errno
 117 will be set to indicate the interruption.
 118 If
 119 .Fa rmtp
 120 is
 121 .Pf non- Dv NULL ,
 122 the timespec structure it references is updated to contain the
 123 unslept amount (the request time minus the time actually slept).
 124 .Sh ERRORS
 125 If any of the following conditions occur, the
 126 .Nm
 127 function shall return \-1 and set
 128 .Va errno
 129 to the corresponding value.
 130 .Bl -tag -width Er
 131 .It Bq Er EFAULT
 132 Either
 133 .Fa rqtp
 134 or
 135 .Fa rmtp
 136 points to memory that is not a valid part of the process
 137 address space.
 138 .It Bq Er EINTR
 139 .Nm
 140 was interrupted by the delivery of a signal.
 141 .It Bq Er EINVAL
 142 .Fa rqtp
 143 specified a nanosecond value less than zero or greater than 1000 million.
 144 .It Bq Er ENOSYS
 145 .Nm
 146 is not supported by this implementation.
 147 .It Bq Er ENOTSUP
 148 for
 149 .Fn clock_nanosleep ,
 150 the clock specified in the
 151 .Fa clock_id
 152 argument is not supported.
 153 .El
 154 .Sh SEE ALSO
 155 .Xr sleep 3 ,
 156 .Xr timespec 3
 157 .Sh STANDARDS
 158 The
 159 .Fn nanosleep
 160 function conforms to
 161 .St -p1003.1b-93 .
 162 The
 163 .Fn clock_nanosleep
 164 function conforms to
 165 .St -p1003.1j-2000 .