xref: /dragonfly/lib/libc/sys/gettimeofday.2 (revision 3170ffd7)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 4. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)gettimeofday.2	8.2 (Berkeley) 5/26/95
29.\" $FreeBSD: src/lib/libc/sys/gettimeofday.2,v 1.9.2.9 2003/02/11 06:05:00 nsayer Exp $
30.\" $DragonFly: src/lib/libc/sys/gettimeofday.2,v 1.5 2008/05/02 02:05:04 swildner Exp $
31.\"
32.Dd May 26, 1995
33.Dt GETTIMEOFDAY 2
34.Os
35.Sh NAME
36.Nm gettimeofday ,
37.Nm settimeofday
38.Nd get/set date and time
39.Sh LIBRARY
40.Lb libc
41.Sh SYNOPSIS
42.In sys/time.h
43.Ft int
44.Fn gettimeofday "struct timeval *tp" "struct timezone *tzp"
45.Ft int
46.Fn settimeofday "const struct timeval *tp" "const struct timezone *tzp"
47.Sh DESCRIPTION
48.Bf -symbolic
49Note: timezone is no longer used; this information is kept outside
50the kernel.
51.Ef
52.Pp
53The system's notion of the current Greenwich time and the current time
54zone is obtained with the
55.Fn gettimeofday
56call, and set with the
57.Fn settimeofday
58call.  The time is expressed in seconds and microseconds
59since midnight (0 hour), January 1, 1970.  The resolution of the system
60clock is hardware dependent, and the time may be updated continuously or
61in
62.Dq ticks .
63If
64.Fa tp
65or
66.Fa tzp
67is NULL, the associated time
68information will not be returned or set.
69.Pp
70The structures pointed to by
71.Fa tp
72and
73.Fa tzp
74are defined in
75.In sys/time.h
76as:
77.Bd -literal
78struct timeval {
79	long	tv_sec;		/* seconds since Jan. 1, 1970 */
80	long	tv_usec;	/* and microseconds */
81};
82
83struct timezone {
84	int	tz_minuteswest; /* minutes west of Greenwich */
85	int	tz_dsttime;	/* type of dst correction */
86};
87.Ed
88.Pp
89The
90.Fa timezone
91structure indicates the local time zone
92(measured in minutes of time westward from Greenwich),
93and a flag that, if nonzero, indicates that
94Daylight Saving time applies locally during
95the appropriate part of the year.
96.Pp
97Only the super-user may set the time of day or time zone.
98If the system is running at securelevel \(>= 2 (see
99.Xr init 8 ) ,
100the time may only be advanced or retarded by a maximum of one second.
101This limitation is imposed to prevent a malicious super-user
102from setting arbitrary time stamps on files.
103The system time can be adjusted backwards without restriction using the
104.Xr adjtime 2
105system call even when the system is secure.
106.Sh RETURN VALUES
107.Rv -std
108.Sh ERRORS
109The following error codes may be set in
110.Va errno :
111.Bl -tag -width Er
112.It Bq Er EFAULT
113An argument address referenced invalid memory.
114.It Bq Er EPERM
115A user other than the super-user attempted to set the time.
116.El
117.Sh SEE ALSO
118.Xr date 1 ,
119.Xr adjtime 2 ,
120.Xr ctime 3 ,
121.Xr clocks 7 ,
122.Xr timed 8
123.Sh HISTORY
124The
125.Fn gettimeofday
126function call appeared in
127.Bx 4.2 .
128