lib/libc/sys/clock_settime.2

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