lib/libc/sys/clock_settime.2

   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
  49 The
  50 .Fn clock_settime
  51 function sets the clock identified by
  52 .Fa clock_id
  53 to the absolute time specified by
  54 .Fa tp .
  55 If the time specified by
  56 .Fa tp
  57 is not a multiple of the resolution of the clock,
  58 .Fa tp
  59 is truncated to a multiple of the resolution.
  60 .Pp
  61 The
  62 .Fn clock_gettime
  63 function stores the time of the clock identified by
  64 .Fa clock_id
  65 into the location specified by
  66 .Fa tp .
  67 .Pp
  68 The
  69 .Fn clock_getres
  70 function stores the resolution of the clock identified by
  71 .Fa clock_id
  72 into the location specified by
  73 .Fa res ,
  74 unless
  75 .Fa res
  76 is
  77 .Dv NULL .
  78 .Pp
  79 A
  80 .Fa clock_id
  81 of
  82 .Dv CLOCK_REALTIME
  83 identifies the realtime clock for the system.
  84 For this clock, the values specified by
  85 .Fn clock_settime
  86 and obtained by
  87 .Fn clock_gettime
  88 represent the amount of time (in seconds and nanoseconds)
  89 since 00:00 Universal Coordinated Time, January 1, 1970.
  90 .Pp
  91 A
  92 .Fa clock_id
  93 of
  94 .Dv CLOCK_MONOTONIC
  95 identifies a clock that increases at a steady rate (monotonically).
  96 This clock
  97 is not affected by calls to
  98 .Xr adjtime 2
  99 and
 100 .Xr settimeofday 2
 101 and will
 102 fail with an
 103 .Er EINVAL
 104 error if it's the clock specified in a call to
 105 .Fn clock_settime .
 106 The origin of the clock is unspecified.
 107 .Pp
 108 If the calling user is not the super-user, then the
 109 .Fn clock_settime
 110 function in the standard C library will try to use the
 111 .Xr clockctl 4
 112 device if present, thus making possible for non privileged users to
 113 set the system time.
 114 If
 115 .Xr clockctl 4
 116 is not present or not accessible, then
 117 .Fn clock_settime
 118 reverts to the
 119 .Fn clock_settime
 120 system call, which is restricted to the super user.
 121 .Sh RETURN VALUES
 122 A value of 0 is returned on success.
 123 Otherwise, a value of \-1 is returned and
 124 .Va errno
 125 is set to indicate the error.
 126 .Sh ERRORS
 127 The
 128 .Fn clock_settime ,
 129 .Fn clock_gettime
 130 and
 131 .Fn clock_getres
 132 functions will fail if:
 133 .Bl -tag -width Er
 134 .It Bq Er EINVAL
 135 The
 136 .Fa clock_id
 137 argument does not specify a known clock.
 138 .It Bq Er ENOSYS
 139 The function is not supported by this implementation.
 140 .El
 141 .Pp
 142 The
 143 .Fn clock_settime
 144 function will fail if:
 145 .Bl -tag -width Er
 146 .It Bq Er EINVAL
 147 The
 148 .Fa tp
 149 argument is outside the range for the specified clock,
 150 .Fa clock_id .
 151 .It Bq Er EINVAL
 152 The
 153 .Fa tp
 154 argument specified a nanosecond value less than zero of greater than or equal
 155 1000 million.
 156 .It Bq Er EINVAL
 157 The
 158 .Fa clock_id
 159 argument is a clock that can not be adjusted.
 160 .It Bq Er EPERM
 161 The
 162 calling process does not have the appropriate privilege to set the specified
 163 clock,
 164 .Fa clock_id .
 165 .El
 166 .Pp
 167 The
 168 .Fn clock_gettime
 169 function will fail if:
 170 .Bl -tag -width Er
 171 .It Bq Er EFAULT
 172 The
 173 .Fa tp
 174 argument specifies an address that is not a valid part of the process address
 175 space.
 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
 183 The
 184 .Fn clock_settime ,
 185 .Fn clock_gettime
 186 and
 187 .Fn clock_getres
 188 functions conform to
 189 .St -p1003.1b-93 .