1TIME(3P) POSIX Programmer's Manual TIME(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 time — get time
14
16 #include <time.h>
17 time_t time(time_t *tloc);
19
21 The functionality described on this reference page is aligned with the
22 ISO C standard. Any conflict between the requirements described here
23 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
24 defers to the ISO C standard.
25 The time() function shall return the value of time in seconds since the
27 Epoch.
28 The tloc argument points to an area where the return value is also
30 stored. If tloc is a null pointer, no value is stored.
31
33 Upon successful completion, time() shall return the value of time. Oth‐
34 erwise, (time_t)−1 shall be returned.
35
37 The time() function may fail if:
38 EOVERFLOW
40 The number of seconds since the Epoch will not fit in an object
41 of type time_t.
42 The following sections are informative.
44
46 Getting the Current Time
47 The following example uses the time() function to calculate the time
48 elapsed, in seconds, since the Epoch, localtime() to convert that value
49 to a broken-down time, and asctime() to convert the broken-down time
50 values into a printable string.
51 #include <stdio.h>
53 #include <time.h>
54 int main(void)
56 {
57 time_t result;
58 result = time(NULL);
60 printf("%s%ju secs since the Epoch\n",
61 asctime(localtime(&result)),
62 (uintmax_t)result);
63 return(0);
64 }
65 This example writes the current time to stdout in a form like this:
67 Wed Jun 26 10:32:15 1996
69 835810335 secs since the Epoch
70 Timing an Event
72 The following example gets the current time, prints it out in the
73 user's format, and prints the number of minutes to an event being
74 timed.
75 #include <time.h>
77 #include <stdio.h>
78 ...
79 time_t now;
80 int minutes_to_event;
81 ...
82 time(&now);
83 minutes_to_event = ...;
84 printf("The time is ");
85 puts(asctime(localtime(&now)));
86 printf("There are %d minutes to the event.\n",
87 minutes_to_event);
88 ...
89
91 None.
92
94 The time() function returns a value in seconds while clock_gettime()
95 and gettimeofday() return a struct timespec (seconds and nanoseconds)
96 and struct timeval (seconds and microseconds), respectively, and are
97 therefore capable of returning more precise times. The times() function
98 is also capable of more precision than time() as it returns a value in
99 clock ticks, although it returns the elapsed time since an arbitrary
100 point such as system boot time, not since the epoch.
101 Implementations in which time_t is a 32-bit signed integer (many his‐
103 torical implementations) fail in the year 2038. POSIX.1‐2008 does not
104 address this problem. However, the use of the time_t type is mandated
105 in order to ease the eventual fix.
106 On some systems the time() function is implemented using a system call
108 that does not return an error condition in addition to the return
109 value. On these systems it is impossible to differentiate between valid
110 and invalid return values and hence overflow conditions cannot be reli‐
111 ably detected.
112 The use of the <time.h> header instead of <sys/types.h> allows compati‐
114 bility with the ISO C standard.
115 Many historical implementations (including Version 7) and the 1984
117 /usr/group standard use long instead of time_t. This volume of
118 POSIX.1‐2008 uses the latter type in order to agree with the ISO C
119 standard.
120
122 In a future version of this volume of POSIX.1‐2008, time_t is likely to
123 be required to be capable of representing times far in the future.
124 Whether this will be mandated as a 64-bit type or a requirement that a
125 specific date in the future be representable (for example, 10000 AD) is
126 not yet determined. Systems purchased after the approval of this volume
127 of POSIX.1‐2008 should be evaluated to determine whether their lifetime
128 will extend past 2038.
129
131 asctime(), clock(), clock_getres(), ctime(), difftime(), futimens(),
132 gettimeofday(), gmtime(), localtime(), mktime(), strftime(), strp‐
133 time(), times(), utime()
134 The Base Definitions volume of POSIX.1‐2008, <time.h>
136
138 Portions of this text are reprinted and reproduced in electronic form
139 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
140 -- Portable Operating System Interface (POSIX), The Open Group Base
141 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
142 cal and Electronics Engineers, Inc and The Open Group. (This is
143 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
144 event of any discrepancy between this version and the original IEEE and
145 The Open Group Standard, the original IEEE and The Open Group Standard
146 is the referee document. The original Standard can be obtained online
147 at http://www.unix.org/online.html .
148 Any typographical or formatting errors that appear in this page are
150 most likely to have been introduced during the conversion of the source
151 files to man page format. To report such errors, see https://www.ker‐
152 nel.org/doc/man-pages/reporting_bugs.html .
153IEEE/The Open Group 2013 TIME(3P)