gettimeofday(3c)

1gettimeofday(3C)         Standard C Library Functions         gettimeofday(3C)
2
3
4

NAME

6       gettimeofday, settimeofday - get or set the date and time
7

SYNOPSIS

9       #include <sys/time.h>
10
11       int gettimeofday(struct timeval *tp, void *tzp);
12
13
14       int settimeofday(struct timeval *tp, void *tzp);
15
16

DESCRIPTION

18       The  gettimeofday()  function gets and the settimeofday() function sets
19       the system's notion of the current time. The current time is  expressed
20       in  elapsed  seconds and microseconds since 00:00 Universal Coordinated
21       Time, January 1, 1970. The resolution of the system clock  is  hardware
22       dependent; the time may be updated continuously or in clock ticks.
23
24
25       The  tp argument points to a timeval structure, which includes the fol‐
26       lowing members:
27
28         long    tv_sec;    /* seconds since Jan. 1, 1970 */
29         long    tv_usec;   /* and microseconds */
30
31
32
33       If tp is a null pointer, the current time information is  not  returned
34       or set.
35
36
37       The  TZ  environment  variable  holds  time zone information. See TIME‐
38       ZONE(4).
39
40
41       The tzp argument to gettimeofday() and settimeofday() is ignored.
42
43
44       Only privileged processes can set the time of day.
45

RETURN VALUES

47       Upon successful completion, 0 is returned.  Otherwise, −1  is  returned
48       and errno is set to indicate the error.
49

ERRORS

51       The settimeofday() function will fail if:
52
53       EINVAL    The structure pointed to by tp specifies an invalid time.
54
55
56       EPERM     The  {PRIV_SYS_TIME} privilege was not asserted in the effec‐
57                 tive set of the calling process.
58
59
60
61       The gettimeofday() function will fail for 32-bit interfaces if:
62
63       EOVERFLOW    The system time has progressed beyond 2038, thus the  size
64                    of  the  tv_sec member of the timeval structure pointed to
65                    by tp is insufficient to hold the current time in seconds.
66
67

USAGE

69       If the tv_usec member of tp is > 500000, settimeofday() rounds the sec‐
70       onds  upward.  If  the time needs to be set with better than one second
71       accuracy, call settimeofday() for the seconds and then  adjtime(2)  for
72       finer accuracy.
73

ATTRIBUTES

75       See attributes(5) for descriptions of the following attributes:
76
77
78
79
80       ┌─────────────────────────────┬─────────────────────────────┐
81       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
82       ├─────────────────────────────┼─────────────────────────────┤
83       │Interface Stability          │gettimeofday() is Standard.  │
84       ├─────────────────────────────┼─────────────────────────────┤
85       │MT-Level                     │MT-Safe                      │
86       └─────────────────────────────┴─────────────────────────────┘
87