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