1.\" $NetBSD: clock_settime.2,v 1.9 2001/10/16 16:08: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.\" 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 <time.h> 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 98If the calling user is not the syper-user, then the 99.Fn clock_settime 100function in the standard C library will try to use the 101.Xr clockctl 4 102device if present, thus making possible for non privileged users to 103set the system time. If 104.Xr clockctl 4 105is not present or not accessible, then 106.Fn clock_settime 107reverts to the 108.Fn clock_settime 109system call, which is restricted to the super user. 110.Sh RETURN VALUES 111A value of 0 is returned on success. Otherwise, a value of -1 is returned and 112.Va errno 113is set to indicate the error. 114.Sh ERRORS 115The 116.Fn clock_settime , 117.Fn clock_gettime 118and 119.Fn clock_getres 120functions will fail if: 121.Bl -tag -width Er 122.It Bq Er EINVAL 123The 124.Fa clock_id 125argument does not specify a known clock. 126.It Bq Er ENOSYS 127The function is not supported by this implementation. 128.El 129.Pp 130The 131.Fn clock_settime 132function will fail if: 133.Bl -tag -width Er 134.It Bq Er EINVAL 135The 136.Fa tp 137argument is outside the range for the specified clock, 138.Fa clock_id . 139.It Bq Er EINVAL 140The 141.Fa tp 142argument specified a nanosecond value less than zero of greater than or equal 1431000 million. 144.It Bq Er EPERM 145The 146calling process does not have the appropriate privilege to set the specified 147clock, 148.Fa clock_id . 149.El 150.Pp 151The 152.Fn clock_gettime 153function will fail if: 154.Bl -tag -width Er 155.It Bq Er EFAULT 156The 157.Fa tp 158argument specifies an address that is not a valid part of the process address 159space. 160.El 161.Sh SEE ALSO 162.Xr ctime 3 , 163.Xr time 3 , 164.\" .Xr timer_gettime 3 , 165.Xr clockctl 4 166.Sh STANDARDS 167The 168.Fn clock_settime , 169.Fn clock_gettime 170and 171.Fn clock_getres 172functions conform to 173.St -p1003.1b-93 . 174