1.\" $NetBSD: clock_settime.2,v 1.22 2014/03/28 15:35:55 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 February 11, 1999 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, then the 123.Fn clock_settime 124function in the standard C library will try to use the 125.Xr clockctl 4 126device if present, thus making possible for non privileged users to 127set the system time. 128If 129.Xr clockctl 4 130is not present or not accessible, then 131.Fn clock_settime 132reverts to the 133.Fn clock_settime 134system call, which is restricted to the super user. 135.Sh RETURN VALUES 136A value of 0 is returned on success. 137Otherwise, a value of \-1 is returned and 138.Va errno 139is set to indicate the error. 140.Sh ERRORS 141The 142.Fn clock_settime , 143.Fn clock_gettime 144and 145.Fn clock_getres 146functions will fail if: 147.Bl -tag -width Er 148.It Bq Er EINVAL 149The 150.Fa clock_id 151argument does not specify a known clock. 152.It Bq Er ENOSYS 153The function is not supported by this implementation. 154.El 155.Pp 156The 157.Fn clock_settime 158function will fail if: 159.Bl -tag -width Er 160.It Bq Er EINVAL 161The 162.Fa tp 163argument is outside the range for the specified clock, 164.Fa clock_id ; 165or the 166.Fa tp 167argument specified a nanosecond value less than zero of greater than or equal 1681000 million; 169or the 170.Fa clock_id 171argument is a clock that can not be adjusted. 172.It Bq Er EPERM 173The 174calling process does not have the appropriate privilege to set the specified 175clock, 176.Fa clock_id . 177.El 178.Pp 179The 180.Fn clock_gettime 181function will fail if: 182.Bl -tag -width Er 183.It Bq Er EFAULT 184The 185.Fa tp 186argument specifies an address that is not a valid part of the process address 187space. 188.El 189.Sh SEE ALSO 190.Xr ctime 3 , 191.Xr time 3 , 192.\" .Xr timer_gettime 3 , 193.Xr clockctl 4 194.Sh STANDARDS 195The 196.Fn clock_settime , 197.Fn clock_gettime 198and 199.Fn clock_getres 200functions conform to 201.St -p1003.1b-93 . 202