time(2) - f39

1time(2)                       System Calls Manual                      time(2)
2
3
4

NAME

6       time - get time in seconds
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <time.h>
13
14       time_t time(time_t *_Nullable tloc);
15

DESCRIPTION

17       time()  returns  the  time  as  the  number of seconds since the Epoch,
18       1970-01-01 00:00:00 +0000 (UTC).
19
20       If tloc is non-NULL, the return value is  also  stored  in  the  memory
21       pointed to by tloc.
22

RETURN VALUE

24       On  success,  the value of time in seconds since the Epoch is returned.
25       On error, ((time_t) -1) is returned, and errno is set to  indicate  the
26       error.
27

ERRORS

29       EFAULT tloc  points  outside  your  accessible  address  space (but see
30              BUGS).
31
32              On systems where the C library time() wrapper  function  invokes
33              an  implementation  provided by the vdso(7) (so that there is no
34              trap into the kernel), an invalid address may instead trigger  a
35              SIGSEGV signal.
36

VERSIONS

38       POSIX.1  defines  seconds since the Epoch using a formula that approxi‐
39       mates the number of seconds between a specified  time  and  the  Epoch.
40       This  formula takes account of the facts that all years that are evenly
41       divisible by 4 are leap years, but years that are evenly  divisible  by
42       100 are not leap years unless they are also evenly divisible by 400, in
43       which case they are leap years.  This value is not the same as the  ac‐
44       tual  number of seconds between the time and the Epoch, because of leap
45       seconds and because system clocks are not required to  be  synchronized
46       to  a  standard reference.  The intention is that the interpretation of
47       seconds since the Epoch values be consistent; see  POSIX.1-2008  Ratio‐
48       nale A.4.15 for further rationale.
49
50       On Linux, a call to time() with tloc specified as NULL cannot fail with
51       the error EOVERFLOW, even on ABIs where time_t is a signed 32-bit inte‐
52       ger and the clock reaches or exceeds 2**31 seconds (2038-01-19 03:14:08
53       UTC, ignoring leap seconds).  (POSIX.1 permits, but does  not  require,
54       the  EOVERFLOW error in the case where the seconds since the Epoch will
55       not fit in time_t.)  Instead, the behavior on Linux is  undefined  when
56       the  system  time is out of the time_t range.  Applications intended to
57       run after 2038 should use ABIs with time_t wider than 32 bits.
58
59   C library/kernel differences
60       On some architectures, an implementation of time() is provided  in  the
61       vdso(7).
62

STANDARDS

64       C11, POSIX.1-2008.
65

HISTORY

67       SVr4, 4.3BSD, C89, POSIX.1-2001.
68

BUGS

70       Error returns from this system call are indistinguishable from success‐
71       ful reports that the time is a few seconds before the Epoch, so  the  C
72       library wrapper function never sets errno as a result of this call.
73
74       The tloc argument is obsolescent and should always be NULL in new code.
75       When tloc is NULL, the call cannot fail.
76