1.\" $OpenBSD: gettimeofday.2,v 1.33 2022/03/31 17:27:16 naddy Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)gettimeofday.2 8.2 (Berkeley) 5/26/95 31.\" 32.Dd $Mdocdate: March 31 2022 $ 33.Dt GETTIMEOFDAY 2 34.Os 35.Sh NAME 36.Nm gettimeofday , 37.Nm settimeofday 38.Nd get or set the time of day 39.Sh SYNOPSIS 40.In sys/time.h 41.Ft int 42.Fn gettimeofday "struct timeval *now" "struct timezone *tz" 43.Ft int 44.Fn settimeofday "const struct timeval *now" "const struct timezone *tz" 45.Sh DESCRIPTION 46The 47.Fn gettimeofday 48function writes the absolute value of the system's Coordinated Universal Time 49.Pq UTC 50clock to 51.Fa now 52unless 53.Fa now 54is 55.Dv NULL . 56.Pp 57The UTC clock's absolute value is the time elapsed since 58Jan 1 1970 00:00:00 +0000 59.Pq the Epoch . 60The clock normally advances continuously, 61though it may jump discontinuously if a process calls 62.Fn settimeofday 63or 64.Xr clock_settime 2 . 65For this reason, 66.Fn gettimeofday 67is not generally suitable for measuring elapsed time. 68Whenever possible, 69use 70.Xr clock_gettime 2 71to measure elapsed time with one of the system's monotonic clocks instead. 72.Pp 73The 74.Fn settimeofday 75function sets the system's UTC clock to the absolute value 76.Fa now 77unless 78.Fa now 79is 80.Dv NULL . 81Only the superuser may set the clock. 82If the system 83.Xr securelevel 7 84is 2 or greater, the clock may only be advanced. 85This limitation prevents a malicious superuser 86from setting arbitrary timestamps on files. 87Setting the clock cancels any ongoing 88.Xr adjtime 2 89adjustment. 90.Pp 91The structure pointed to by 92.Fa now 93is defined in 94.In sys/time.h 95as: 96.Bd -literal 97struct timeval { 98 time_t tv_sec; /* seconds */ 99 suseconds_t tv_usec; /* and microseconds */ 100}; 101.Ed 102.Pp 103The 104.Fa tz 105argument is historical: 106the system no longer maintains timezone information in the kernel. 107The 108.Fa tz 109argument should always be 110.Dv NULL . 111.Fn gettimeofday 112zeroes 113.Fa tz 114if it is not 115.Dv NULL . 116.Fn settimeofday 117ignores the contents of 118.Fa tz 119if it is not 120.Dv NULL . 121.Sh RETURN VALUES 122.Rv -std 123.Sh ERRORS 124.Fn gettimeofday 125and 126.Fn settimeofday 127will fail if: 128.Bl -tag -width Er 129.It Bq Er EFAULT 130.Fa now 131or 132.Fa tz 133are not 134.Dv NULL 135and reference invalid memory. 136.El 137.Pp 138.Fn settimeofday 139will also fail if: 140.Bl -tag -width Er 141.It Bq Er EINVAL 142.Fa now 143specifies a microsecond value less than zero or greater than or equal to 144one million. 145.It Bq Er EPERM 146The caller is not the superuser. 147.It Bq Er EPERM 148The system 149.Xr securelevel 7 150is 2 or greater and 151.Fa now 152specifies a time in the past. 153.El 154.Sh SEE ALSO 155.Xr date 1 , 156.Xr adjtime 2 , 157.Xr clock_gettime 2 , 158.Xr getitimer 2 , 159.Xr ctime 3 , 160.Xr time 3 , 161.Xr timeradd 3 162.Sh STANDARDS 163The 164.Fn gettimeofday 165function conforms to 166.St -p1003.1-2008 . 167.Pp 168The 169.Fn settimeofday 170function is non-standard, 171though many systems offer it. 172.Sh HISTORY 173As predecessors of these functions, 174former system calls 175.Fn time 176and 177.Fn stime 178first appeared in 179.At v1 , 180and 181.Fn ftime 182first appeared in 183.At v7 . 184The 185.Fn gettimeofday 186and 187.Fn settimeofday 188system calls first appeared in 189.Bx 4.1c . 190.Sh CAVEATS 191Setting the time with 192.Fn settimeofday 193is dangerous; if possible use 194.Xr adjtime 2 195instead. 196Many daemon programming techniques utilize time-delta techniques 197using the results from 198.Fn gettimeofday 199instead of from 200.Xr clock_gettime 2 201on the 202.Dv CLOCK_MONOTONIC 203clock. 204Time jumps can cause these programs to malfunction in unexpected ways. 205If the time must be set, consider rebooting the machine for safety. 206