1.\" $NetBSD: clock_settime.2,v 1.24 2015/12/09 08:30:03 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 December 8, 2015 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 79A 80.Fa clock_id 81of 82.Dv CLOCK_REALTIME 83identifies the realtime clock for the system. 84For this clock, the values specified by 85.Fn clock_settime 86and obtained by 87.Fn clock_gettime 88represent the amount of time (in seconds and nanoseconds) 89since 00:00 Universal Coordinated Time, January 1, 1970. 90.Pp 91A 92.Fa clock_id 93of 94.Dv CLOCK_MONOTONIC 95identifies a clock that increases at a steady rate (monotonically). 96This clock 97is not affected by calls to 98.Xr adjtime 2 99and 100.Xr settimeofday 2 101and will 102fail with an 103.Er EINVAL 104error if it's the clock specified in a call to 105.Fn clock_settime . 106The origin of the clock is unspecified. 107.Pp 108A 109.Fa clock_id 110of 111.Dv CLOCK_VIRTUAL 112identifies a clock that increments only when the CPU is running in 113user mode on behalf of the calling process. 114.Pp 115A 116.Fa clock_id 117of 118.Dv CLOCK_PROF 119identifies a clock that increments when the CPU is running in user 120or kernel mode on behalf of the calling process. 121.Pp 122If the calling user is not the super-user, the 123.Fn clock_settime 124system call will fail, and the 125.Fn clock_settime 126function in the standard C library will try to use the 127.Xr clockctl 4 128device if present, thus making it possible for non privileged users to 129set the system time. 130If 131.Xr clockctl 4 132is not present or not accessible, then 133.Fn clock_settime 134returns 135.Er EPERM . 136.Sh RETURN VALUES 137A value of 0 is returned on success. 138Otherwise, a value of \-1 is returned and 139.Va errno 140is set to indicate the error. 141.Sh ERRORS 142The 143.Fn clock_settime , 144.Fn clock_gettime 145and 146.Fn clock_getres 147functions will fail if: 148.Bl -tag -width Er 149.It Bq Er EINVAL 150The 151.Fa clock_id 152argument does not specify a known clock. 153.It Bq Er ENOSYS 154The function is not supported by this implementation. 155.El 156.Pp 157The 158.Fn clock_settime 159function will fail if: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162The 163.Fa tp 164argument is outside the range for the specified clock, 165.Fa clock_id ; 166or the 167.Fa tp 168argument specified a nanosecond value less than zero of greater than or equal 1691000 million; 170or the 171.Fa clock_id 172argument is a clock that can not be adjusted. 173.It Bq Er EPERM 174The 175calling process does not have the appropriate privilege to set the specified 176clock, 177.Fa clock_id . 178.El 179.Pp 180The 181.Fn clock_gettime 182function will fail if: 183.Bl -tag -width Er 184.It Bq Er EFAULT 185The 186.Fa tp 187argument specifies an address that is not a valid part of the process address 188space. 189.El 190.Sh SEE ALSO 191.Xr ctime 3 , 192.Xr time 3 , 193.\" .Xr timer_gettime 3 , 194.Xr clockctl 4 195.Sh STANDARDS 196The 197.Fn clock_settime , 198.Fn clock_gettime 199and 200.Fn clock_getres 201functions conform to 202.St -p1003.1b-93 . 203