usr/src/man/man3c/clock_settime.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 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH CLOCK_SETTIME 3C "Nov 26, 2017"
  48 .SH NAME
  49 clock_settime, clock_gettime, clock_getres \- high-resolution clock operations
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <time.h>
  54
  55 \fBint\fR \fBclock_settime\fR(\fBclockid_t\fR \fIclock_id\fR, \fBconst struct timespec *\fR\fItp\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBint\fR \fBclock_gettime\fR(\fBclockid_t\fR \fIclock_id\fR, \fBstruct timespec *\fR\fItp\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBint\fR \fBclock_getres\fR(\fBclockid_t\fR \fIclock_id\fR, \fBstruct timespec *\fR\fIres\fR);
  66 .fi
  67
  68 .SH DESCRIPTION
  69 .LP
  70 The \fBclock_settime()\fR function sets the specified clock, \fIclock_id\fR, to
  71 the value specified by \fItp\fR. Time values that are between two consecutive
  72 non-negative integer multiples of the resolution of the specified clock are
  73 truncated down to the smaller multiple of the resolution.
  74 .sp
  75 .LP
  76 The \fBclock_gettime()\fR function returns the current value \fItp\fR for the
  77 specified clock, \fIclock_id\fR.
  78 .sp
  79 .LP
  80 The resolution of any clock can be obtained by calling \fBclock_getres()\fR.
  81 Clock resolutions are system-dependent and cannot be set by a process. If the
  82 argument \fIres\fR is not \fINULL\fR, the resolution of the specified clock is
  83 stored in the location pointed to by \fIres\fR. If \fIres\fR is \fINULL\fR, the
  84 clock resolution is not returned. If the time argument of \fBclock_settime()\fR
  85 is not a multiple of \fIres\fR, then the value is truncated to a multiple of
  86 \fIres\fR.
  87 .sp
  88 .LP
  89 A clock may be system wide (that is, visible to all processes) or per-process
  90 (measuring time that is meaningful only within a process).
  91 .sp
  92 .LP
  93 A \fIclock_id\fR of \fBCLOCK_REALTIME\fR is defined in <\fBtime.h\fR>. This
  94 clock represents the realtime clock for the system. For this clock, the values
  95 returned by \fBclock_gettime()\fR and specified by \fBclock_settime()\fR
  96 represent the amount of time (in seconds and nanoseconds) since the Epoch.
  97 Additional clocks may also be supported. The interpretation of time values for
  98 these clocks is unspecified.
  99 .sp
 100 .LP
 101 A \fIclock_id\fR of \fBCLOCK_HIGHRES\fR represents the non-adjustable,
 102 high-resolution clock for the system. For this clock, the value returned by
 103 \fBclock_gettime\fR(3C) represents the amount of time (in seconds and
 104 nanoseconds) since some arbitrary time in the past; it is not correlated in any
 105 way to the time of day, and thus is not subject to resetting or drifting by way
 106 of \fBadjtime\fR(2), \fBntp_adjtime\fR(2), \fBsettimeofday\fR(3C), or
 107 \fBclock_settime()\fR.  The time source for this clock is the same as that for
 108 \fBgethrtime\fR(3C).
 109 .sp
 110 .LP
 111 Additional clocks may also be supported. The interpretation of time values for
 112 these clocks is unspecified.
 113 .SH RETURN VALUES
 114 .LP
 115 Upon successful completion, \fB0\fR  is returned. Otherwise, \fB\(mi1\fR is
 116 returned and \fBerrno\fR is set to indicate the error.
 117 .SH ERRORS
 118 .LP
 119 The \fBclock_settime()\fR, \fBclock_gettime()\fR and \fBclock_getres()\fR
 120 functions will fail if:
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEINVAL\fR\fR
 125 .ad
 126 .RS 10n
 127 The \fIclock_id\fR argument does not specify a known clock.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBENOSYS\fR\fR
 134 .ad
 135 .RS 10n
 136 The functions \fBclock_settime()\fR, \fBclock_gettime()\fR, and
 137 \fBclock_getres()\fR are not supported by this implementation.
 138 .RE
 139
 140 .sp
 141 .LP
 142 The \fBclock_settime()\fR function will fail if:
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBEINVAL\fR\fR
 147 .ad
 148 .RS 10n
 149 The \fItp\fR argument to \fBclock_settime()\fR is outside the range for the
 150 given clock ID; or the \fItp\fR argument specified a nanosecond value less than
 151 zero or greater than or equal to 1000 million.
 152 .RE
 153
 154 .sp
 155 .LP
 156 The \fBclock_settime()\fR function may fail if:
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBEPERM\fR\fR
 161 .ad
 162 .RS 9n
 163 The requesting process does not have the appropriate privilege to set the
 164 specified clock.
 165 .RE
 166
 167 .SH ATTRIBUTES
 168 .LP
 169 See \fBattributes\fR(5) for descriptions of the following attributes:
 170 .sp
 171
 172 .sp
 173 .TS
 174 box;
 175 c | c
 176 l | l .
 177 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 178 _
 179 Interface Stability     Committed
 180 _
 181 MT-Level        \fBclock_gettime()\fR is Async-Signal-Safe
 182 _
 183 Standard        See \fBstandards\fR(5).
 184 .TE
 185
 186 .SH SEE ALSO
 187 .LP
 188 \fBtime\fR(2), \fBctime\fR(3C), \fBgethrtime\fR(3C), \fBtime.h\fR(3HEAD),
 189 \fBtimer_gettime\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)