share/man/man3c/clock_nanosleep.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
  44 .\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
  45 .\"
  46 .TH CLOCK_NANOSLEEP 3C "Feb 5, 2008"
  47 .SH NAME
  48 clock_nanosleep \- high resolution sleep with specifiable clock
  49 .SH SYNOPSIS
  50 .LP
  51 .nf
  52 #include <time.h>
  53
  54 \fBint\fR \fBclock_nanosleep\fR(\fBclockid_t\fR \fIclock_id\fR, \fBint\fR \fIflags\fR,
  55      \fBconst struct timespec *\fR\fIrqtp\fR, \fBstruct timespec *\fR\fIrmtp\fR);
  56 .fi
  57
  58 .SH DESCRIPTION
  59 .sp
  60 .LP
  61 If the flag \fBTIMER_ABSTIME\fR is not set in the \fIflags\fR argument, the
  62 \fBclock_nanosleep()\fR function causes the current thread to be suspended from
  63 execution until either the time interval specified by the \fIrqtp\fR argument
  64 has elapsed, or a signal is delivered to the calling thread and its action is
  65 to invoke a signal-catching function, or the process is terminated. The clock
  66 used to measure the time is the clock specified by \fIclock_id\fR.
  67 .sp
  68 .LP
  69 If the flag \fBTIMER_ABSTIME\fR is set in the \fIflags\fR argument, the
  70 \fBclock_nanosleep()\fR function causes the current thread to be suspended from
  71 execution until either the time value of the clock specified by \fIclock_id\fR
  72 reaches the absolute time specified by the \fIrqtp\fR argument, or a signal is
  73 delivered to the calling thread and its action is to invoke a signal-catching
  74 function, or the process is terminated. If, at the time of the call, the time
  75 value specified by \fIrqtp\fR is less than or equal to the time value of the
  76 specified clock, then \fBclock_nanosleep()\fR returns immediately and the
  77 calling process is not suspended.
  78 .sp
  79 .LP
  80 The suspension time caused by this function can be longer than requested
  81 because the argument value is rounded up to an integer multiple of the sleep
  82 resolution, or because of the scheduling of other activity by the system. But,
  83 except for the case of being interrupted by a signal, the suspension time for
  84 the relative \fBclock_nanosleep()\fR function (that is, with the
  85 \fBTIMER_ABSTIME\fR flag not set) will not be less than the time interval
  86 specified by rqtp, as measured by the corresponding clock. The suspension for
  87 the absolute \fBclock_nanosleep()\fR function (that is, with the
  88 \fBTIMER_ABSTIME\fR flag set) will be in effect at least until the value of the
  89 corresponding clock reaches the absolute time specified by \fIrqtp\fR, except
  90 for the case of being interrupted by a signal.
  91 .sp
  92 .LP
  93 The use of the \fBclock_nanosleep()\fR function has no effect on the action or
  94 blockage of any signal.
  95 .sp
  96 .LP
  97 The \fBclock_nanosleep()\fR function fails if the \fIclock_id\fR argument
  98 refers to the CPU-time clock of the calling thread. It is unspecified if
  99 \fIclock_id\fR values of other CPU-time clocks are allowed.
 100 .SH RETURN VALUES
 101 .sp
 102 .LP
 103 If the \fBclock_nanosleep()\fR function returns because the requested time has
 104 elapsed, its return value is 0.
 105 .sp
 106 .LP
 107 If the \fBclock_nanosleep()\fR function returns because it has been interrupted
 108 by a signal, it returns the corresponding error value. For the relative
 109 \fBclock_nanosleep()\fR function, if the \fIrmtp\fR argument is non-null, the
 110 timespec structure referenced by it is updated to contain the amount of time
 111 remaining in the interval (the requested time minus the time actually slept).
 112 If the \fIrmtp\fR argument is NULL, the remaining time is not returned. The
 113 absolute \fBclock_nanosleep()\fR function has no effect on the structure
 114 referenced by \fIrmtp\fR.
 115 .sp
 116 .LP
 117 If \fBclock_nanosleep()\fR fails, it shall return the corresponding error
 118 value.
 119 .SH ERRORS
 120 .sp
 121 .LP
 122 The \fBclock_nanosleep()\fR function will fail if:
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBEINTR\fR\fR
 127 .ad
 128 .RS 11n
 129 The \fBclock_nanosleep()\fR function was interrupted by a signal.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBEINVAL\fR\fR
 136 .ad
 137 .RS 11n
 138 The \fIrqtp\fR argument specified a nanosecond value less than zero or greater
 139 than or equal to 1,000 million; or the TIMER_ABSTIME flag was specified in
 140 \fIflags\fR and the \fIrqtp\fR argument is outside the range for the clock
 141 specified by \fIclock_id\fR; or the \fIclock_id\fR argument does not specify a
 142 known clock, or specifies the CPU-time clock of the calling thread.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBENOTSUP\fR\fR
 149 .ad
 150 .RS 11n
 151 The \fIclock_id\fR argument specifies a clock for which \fBclock_nanosleep()\fR
 152 is not supported, such as a CPU-time clock.
 153 .RE
 154
 155 .SH ATTRIBUTES
 156 .sp
 157 .LP
 158 See \fBattributes\fR(5) for descriptions of the following attributes:
 159 .sp
 160
 161 .sp
 162 .TS
 163 box;
 164 c | c
 165 l | l .
 166 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 167 _
 168 Interface Stability     Committed
 169 _
 170 MT-Level        MT-Safe
 171 _
 172 Standard        See \fBstandards\fR(5).
 173 .TE
 174
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBclock_getres\fR(3C), \fBnanosleep\fR(3C), \fBpthread_cond_timedwait\fR(3C),
 179 \fBsleep\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)