usr/src/man/man3c/clock_nanosleep.3c

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