1.\" $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $ 2.\" $FreeBSD: src/lib/libc/sys/clock_gettime.2,v 1.3.2.8 2001/12/14 18:34:00 ru Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd March 17, 2015 32.Dt CLOCK_GETTIME 2 33.Os 34.Sh NAME 35.Nm clock_gettime , 36.Nm clock_settime , 37.Nm clock_getres 38.Nd get/set/calibrate date and time 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/time.h 43.Ft int 44.Fn clock_gettime "clockid_t clock_id" "struct timespec *tp" 45.Ft int 46.Fn clock_settime "clockid_t clock_id" "const struct timespec *tp" 47.Ft int 48.Fn clock_getres "clockid_t clock_id" "struct timespec *tp" 49.Sh DESCRIPTION 50The 51.Fn clock_gettime 52and 53.Fn clock_settime 54allow the calling process to retrieve or set the value used by a clock 55which is specified by 56.Fa clock_id . 57.Pp 58.Fa clock_id 59can be one of the following values: 60.Dv CLOCK_REALTIME , 61.Dv CLOCK_REALTIME_PRECISE , 62and 63.Dv CLOCK_REALTIME_FAST 64for time that increments as a wall clock should; 65.Dv CLOCK_MONOTONIC , 66.Dv CLOCK_MONOTONIC_PRECISE , 67and 68.Dv CLOCK_MONOTONIC_FAST 69which increments in SI seconds; 70.Dv CLOCK_UPTIME , 71.Dv CLOCK_UPTIME_PRECISE , 72and 73.Dv CLOCK_UPTIME_FAST 74which starts at zero when the kernel boots and increments 75monotonically in SI seconds while the machine is running; 76.Dv CLOCK_VIRTUAL 77for time that increments only when 78the CPU is running in user mode on behalf of the calling process; 79.Dv CLOCK_PROF 80for time that increments when the CPU is running in user or 81kernel mode; or 82.Dv CLOCK_SECOND 83which returns the current second without performing a full time counter 84query, using in-kernel cached value of current second. 85.Pp 86The clock IDs 87.Dv CLOCK_REALTIME_FAST , 88.Dv CLOCK_MONOTONIC_FAST , 89and 90.Dv CLOCK_UPTIME_FAST 91are analogs of corresponding IDs without _FAST suffix but do not perform 92a full time counter query, so their accuracy is one timer tick. 93Similarly, 94.Dv CLOCK_REALTIME_PRECISE , 95.Dv CLOCK_MONOTONIC_PRECISE , 96and 97.Dv CLOCK_UPTIME_PRECISE 98are used to get the most exact value as possible, at the expense of 99execution time. 100.Pp 101The clock IDs 102.Dv CLOCK_UPTIME_FAST , 103.Dv CLOCK_MONOTONIC_FAST , 104.Dv CLOCK_REALTIME_FAST , 105and 106.Dv CLOCK_SECOND 107make use of 108.Xr kpmap 4 109and do not incur any system call overhead after a certain amount of calls. 110.Pp 111The structure pointed to by 112.Fa tp 113is defined in 114.In sys/time.h 115as: 116.Bd -literal 117struct timespec { 118 time_t tv_sec; /* seconds */ 119 long tv_nsec; /* and nanoseconds */ 120}; 121.Ed 122.Pp 123Only the super-user may set the time of day. 124If the system securelevel is greater than 1 (see 125.Xr init 8 ) , 126the time may only be advanced. 127This limitation is imposed to prevent a malicious super-user 128from setting arbitrary time stamps on files. 129The system time can still be adjusted backwards using the 130.Xr adjtime 2 131system call even when the system is secure. 132.Pp 133The resolution (granularity) of a clock is returned by the 134.Fn clock_getres 135call. 136This value is placed in a (non-NULL) 137.Fa *tp . 138.Sh RETURN VALUES 139.Rv -std 140.Sh ERRORS 141The following error codes may be set in 142.Va errno : 143.Bl -tag -width Er 144.It Bq Er EINVAL 145The 146.Fa clock_id 147was not a valid value. 148.It Bq Er EFAULT 149The 150.Fa *tp 151argument address referenced invalid memory. 152.It Bq Er EPERM 153A user other than the super-user attempted to set the time. 154.El 155.Sh SEE ALSO 156.Xr date 1 , 157.Xr adjtime 2 , 158.Xr ctime 3 , 159.Xr timed 8 160.Sh STANDARDS 161The 162.Fn clock_gettime , 163etc.\& 164functions conform to 165.St -p1003.1b-93 . 166The clock IDs 167.Dv CLOCK_REALTIME_FAST , 168.Dv CLOCK_REALTIME_PRECISE , 169.Dv CLOCK_MONOTONIC_FAST , 170.Dv CLOCK_MONOTONIC_PRECISE , 171.Dv CLOCK_UPTIME , 172.Dv CLOCK_UPTIME_FAST , 173.Dv CLOCK_UPTIME_PRECISE , 174and 175.Dv CLOCK_SECOND 176are 177.Fx 178extensions to the POSIX interface. 179