Debian Codegraph @

upstream/debian-unstable/man2/time.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH time 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 time \- get time in seconds
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <time.h>
15 .P
16 .BI "time_t time(time_t *_Nullable " tloc );
17 .fi
18 .SH DESCRIPTION
19 .BR time ()
20 returns the time as the number of seconds since the
21 Epoch, 1970-01-01 00:00:00 +0000 (UTC).
22 .P
23 If
24 .I tloc
25 is non-NULL,
26 the return value is also stored in the memory pointed to by
27 .IR tloc .
28 .SH RETURN VALUE
29 On success, the value of time in seconds since the Epoch is returned.
30 On error,
31 .I ((time_t)\ \-1)
32 is returned, and
33 .I errno
34 is set to indicate the error.
35 .SH ERRORS
36 .TP
37 .B EOVERFLOW
38 The time cannot be represented as a
39 .I time_t
40 value.
41 This can happen if an executable with 32-bit
42 .I time_t
43 is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later.
44 However, when the system time is out of
45 .I time_t
46 range in other situations, the behavior is undefined.
47 .TP
48 .B EFAULT
49 .I tloc
50 points outside your accessible address space (but see BUGS).
51 .IP
52 On systems where the C library
53 .BR time ()
54 wrapper function invokes an implementation provided by the
55 .BR vdso (7)
56 (so that there is no trap into the kernel),
57 an invalid address may instead trigger a
58 .B SIGSEGV
59 signal.
60 .SH VERSIONS
61 POSIX.1 defines
62 .I seconds since the Epoch
63 using a formula that approximates the number of seconds between a
64 specified time and the Epoch.
65 This formula takes account of the facts that
66 all years that are evenly divisible by 4 are leap years,
67 but years that are evenly divisible by 100 are not leap years
68 unless they are also evenly divisible by 400,
69 in which case they are leap years.
70 This value is not the same as the actual number of seconds between the time
71 and the Epoch, because of leap seconds and because system clocks are not
72 required to be synchronized to a standard reference.
73 Linux systems normally follow the POSIX requirement
74 that this value ignore leap seconds,
75 so that conforming systems interpret it consistently;
76 see POSIX.1-2018 Rationale A.4.16.
77 .P
78 Applications intended to run after 2038 should use ABIs with
79 .I time_t
80 wider than 32 bits;
81 see
82 .BR time_t (3type).
83 .SS C library/kernel differences
84 On some architectures, an implementation of
85 .BR time ()
86 is provided in the
87 .BR vdso (7).
88 .SH STANDARDS
89 C11, POSIX.1-2024.
90 .SH HISTORY
91 SVr4, 4.3BSD, C89, POSIX.1-2001, V7.
92 .SH BUGS
93 Error returns from this system call are indistinguishable from
94 successful reports that the time is a few seconds
95 .I before
96 the Epoch, so the C library wrapper function never sets
97 .I errno
98 as a result of this call.
99 .P
100 The
101 .I tloc
102 argument is obsolescent and should always be NULL in new code.
103 When
104 .I tloc
105 is NULL, the call cannot fail.
106 .SH SEE ALSO
107 .BR date (1),
108 .BR gettimeofday (2),
109 .BR ctime (3),
110 .BR ftime (3),
111 .BR time (7),
112 .BR vdso (7)