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