1GETTIMEOFDAY(2)            Linux Programmer's Manual           GETTIMEOFDAY(2)
2
3
4

NAME

6       gettimeofday, settimeofday - get / set time
7

SYNOPSIS

9       #include <sys/time.h>
10
11       int gettimeofday(struct timeval *tv, struct timezone *tz);
12
13       int settimeofday(const struct timeval *tv, const struct timezone *tz);
14
15   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
16
17       settimeofday():
18           Since glibc 2.19:
19               _DEFAULT_SOURCE
20           Glibc 2.19 and earlier:
21               _BSD_SOURCE
22

DESCRIPTION

24       The  functions  gettimeofday()  and  settimeofday() can get and set the
25       time as well as a timezone.  The tv argument is a  struct  timeval  (as
26       specified in <sys/time.h>):
27
28           struct timeval {
29               time_t      tv_sec;     /* seconds */
30               suseconds_t tv_usec;    /* microseconds */
31           };
32
33       and  gives  the number of seconds and microseconds since the Epoch (see
34       time(2)).  The tz argument is a struct timezone:
35
36           struct timezone {
37               int tz_minuteswest;     /* minutes west of Greenwich */
38               int tz_dsttime;         /* type of DST correction */
39           };
40
41       If either tv or tz is NULL, the corresponding structure is not  set  or
42       returned.  (However, compilation warnings will result if tv is NULL.)
43
44       The  use  of the timezone structure is obsolete; the tz argument should
45       normally be specified as NULL.  (See NOTES below.)
46
47       Under Linux, there are some peculiar "warp clock" semantics  associated
48       with  the  settimeofday()  system call if on the very first call (after
49       booting) that has a non-NULL tz argument, the tv argument is  NULL  and
50       the  tz_minuteswest  field is nonzero.  (The tz_dsttime field should be
51       zero for this case.)  In such a case it is assumed that the CMOS  clock
52       is  on  local time, and that it has to be incremented by this amount to
53       get UTC system time.  No doubt it is a bad idea to use this feature.
54

RETURN VALUE

56       gettimeofday() and settimeofday() return 0 for success, or -1 for fail‐
57       ure (in which case errno is set appropriately).
58

ERRORS

60       EFAULT One of tv or tz pointed outside the accessible address space.
61
62       EINVAL (settimeofday()): timezone is invalid.
63
64       EINVAL (settimeofday()): tv.tv_sec is negative or tv.tv_usec is outside
65              the range [0..999,999].
66
67       EINVAL (since Linux 4.3)
68              (settimeofday()): An attempt was made to set the time to a value
69              less  than  the  current value of the CLOCK_MONOTONIC clock (see
70              clock_gettime(2)).
71
72       EPERM  The calling process has insufficient privilege to call  settime‐
73              ofday(); under Linux the CAP_SYS_TIME capability is required.
74

CONFORMING TO

76       SVr4, 4.3BSD.  POSIX.1-2001 describes gettimeofday() but not settimeof‐
77       day().  POSIX.1-2008 marks gettimeofday() as obsolete, recommending the
78       use of clock_gettime(2) instead.
79

NOTES

81       The  time returned by gettimeofday() is affected by discontinuous jumps
82       in the system time (e.g., if the system administrator manually  changes
83       the  system  time).   If you need a monotonically increasing clock, see
84       clock_gettime(2).
85
86       Macros for operating on timeval  structures  are  described  in  timer‐
87       add(3).
88
89       Traditionally, the fields of struct timeval were of type long.
90
91   C library/kernel differences
92       On  some architectures, an implementation of gettimeofday() is provided
93       in the vdso(7).
94
95   The tz_dsttime field
96       On a non-Linux kernel, with glibc, the tz_dsttime field of struct time‐
97       zone  will  be  set to a nonzero value by gettimeofday() if the current
98       timezone has ever had or will have a daylight saving rule applied.   In
99       this  sense  it exactly mirrors the meaning of daylight(3) for the cur‐
100       rent zone.  On Linux, with glibc, the setting of the  tz_dsttime  field
101       of  struct timezone has never been used by settimeofday() or gettimeof‐
102       day().  Thus, the following is purely of historical interest.
103
104       On old systems, the field tz_dsttime contains a symbolic constant (val‐
105       ues  are given below) that indicates in which part of the year Daylight
106       Saving Time is in force.  (Note: this value is constant throughout  the
107       year:  it  does  not  indicate that DST is in force, it just selects an
108       algorithm.)  The daylight saving time algorithms defined  are  as  fol‐
109       lows:
110
111           DST_NONE     /* not on DST */
112           DST_USA      /* USA style DST */
113           DST_AUST     /* Australian style DST */
114           DST_WET      /* Western European DST */
115           DST_MET      /* Middle European DST */
116           DST_EET      /* Eastern European DST */
117           DST_CAN      /* Canada */
118           DST_GB       /* Great Britain and Eire */
119           DST_RUM      /* Romania */
120           DST_TUR      /* Turkey */
121           DST_AUSTALT  /* Australian style with shift in 1986 */
122
123       Of  course  it turned out that the period in which Daylight Saving Time
124       is in force cannot be given by a simple  algorithm,  one  per  country;
125       indeed, this period is determined by unpredictable political decisions.
126       So this method of representing timezones has been abandoned.
127

SEE ALSO

129       date(1), adjtimex(2), clock_gettime(2),  time(2),  ctime(3),  ftime(3),
130       timeradd(3), capabilities(7), time(7), vdso(7), hwclock(8)
131

COLOPHON

133       This  page  is  part of release 5.04 of the Linux man-pages project.  A
134       description of the project, information about reporting bugs,  and  the
135       latest     version     of     this    page,    can    be    found    at
136       https://www.kernel.org/doc/man-pages/.
137
138
139
140Linux                             2019-03-06                   GETTIMEOFDAY(2)
Impressum