1.\" $NetBSD: clock_settime.2,v 1.27 2016/09/27 11:11:43 wiz Exp $ 2.\" 3.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Klaus Klein. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 23, 2016 31.Dt CLOCK_SETTIME 2 32.Os 33.Sh NAME 34.Nm clock_settime , 35.Nm clock_gettime , 36.Nm clock_getres 37.Nd clock and timer functions 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In time.h 42.Ft int 43.Fn clock_settime "clockid_t clock_id" "const struct timespec *tp" 44.Ft int 45.Fn clock_gettime "clockid_t clock_id" "struct timespec *tp" 46.Ft int 47.Fn clock_getres "clockid_t clock_id" "struct timespec *res" 48.Sh DESCRIPTION 49The 50.Fn clock_settime 51function sets the clock identified by 52.Fa clock_id 53to the absolute time specified by 54.Fa tp . 55If the time specified by 56.Fa tp 57is not a multiple of the resolution of the clock, 58.Fa tp 59is truncated to a multiple of the resolution. 60.Pp 61The 62.Fn clock_gettime 63function stores the time of the clock identified by 64.Fa clock_id 65into the location specified by 66.Fa tp . 67.Pp 68The 69.Fn clock_getres 70function stores the resolution of the clock identified by 71.Fa clock_id 72into the location specified by 73.Fa res , 74unless 75.Fa res 76is 77.Dv NULL . 78.Pp 79The following 80.Fa clock_id 81values are supported: 82.Bl -tag -width CLOCK_MONOTONIC 83.It Dv CLOCK_REALTIME 84identifies the realtime clock for the system. 85For this clock, the values specified by 86.Fn clock_settime 87and obtained by 88.Fn clock_gettime 89represent the amount of time (in seconds and nanoseconds) 90since 00:00 Universal Coordinated Time, January 1, 1970. 91.It Dv CLOCK_MONOTONIC 92identifies a clock that increases at a steady rate (monotonically). 93This clock 94is not affected by calls to 95.Xr adjtime 2 96and 97.Xr settimeofday 2 98and will 99fail with an 100.Er EINVAL 101error if it's the clock specified in a call to 102.Fn clock_settime . 103The origin of the clock is unspecified. 104.It Dv CLOCK_VIRTUAL 105identifies a clock that increments only when the CPU is running in 106user mode on behalf of the calling process. 107.It Dv CLOCK_PROF 108identifies a clock that increments when the CPU is running in user 109or kernel mode on behalf of the calling process. 110.It Dv CLOCK_PROCESS_CPUTIME_ID 111identifies a per process clock based on tick values. 112This clock is not settable. 113.It Dv CLOCK_THREAD_CPUTIME_ID 114identifies a per thread clock based on tick values. 115This clock is not settable. 116.El 117.Pp 118If the calling user is not the super-user, the 119.Fn clock_settime 120system call will fail, and the 121.Fn clock_settime 122function in the standard C library will try to use the 123.Xr clockctl 4 124device if present, thus making it possible for non privileged users to 125set the system time. 126If 127.Xr clockctl 4 128is not present or not accessible, then 129.Fn clock_settime 130returns 131.Er EPERM . 132.Sh RETURN VALUES 133A value of 0 is returned on success. 134Otherwise, a value of \-1 is returned and 135.Va errno 136is set to indicate the error. 137.Sh ERRORS 138The 139.Fn clock_settime , 140.Fn clock_gettime 141and 142.Fn clock_getres 143functions will fail if: 144.Bl -tag -width Er 145.It Bq Er EINVAL 146The 147.Fa clock_id 148argument does not specify a known clock. 149.It Bq Er ENOSYS 150The function is not supported by this implementation. 151.El 152.Pp 153The 154.Fn clock_settime 155function will fail if: 156.Bl -tag -width Er 157.It Bq Er EINVAL 158The 159.Fa tp 160argument is outside the range for the specified clock, 161.Fa clock_id ; 162or the 163.Fa tp 164argument specified a nanosecond value less than zero of greater than or equal 1651000 million; 166or the 167.Fa clock_id 168argument is a clock that can not be adjusted. 169.It Bq Er EPERM 170The 171calling process does not have the appropriate privilege to set the specified 172clock, 173.Fa clock_id . 174.El 175.Pp 176The 177.Fn clock_gettime 178function will fail if: 179.Bl -tag -width Er 180.It Bq Er EFAULT 181The 182.Fa tp 183argument specifies an address that is not a valid part of the process address 184space. 185.El 186.Sh SEE ALSO 187.Xr ctime 3 , 188.Xr time 3 , 189.\" .Xr timer_gettime 3 , 190.Xr clockctl 4 191.Sh STANDARDS 192The 193.Fn clock_settime , 194.Fn clock_gettime 195and 196.Fn clock_getres 197functions conform to 198.St -p1003.1b-93 . 199