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