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