1TIME(3P)                   POSIX Programmer's Manual                  TIME(3P)
2
3
4

PROLOG

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

NAME

12       time — get time
13

SYNOPSIS

15       #include <time.h>
16
17       time_t time(time_t *tloc);
18

DESCRIPTION

20       The functionality described on this reference page is aligned with  the
21       ISO C  standard.  Any  conflict between the requirements described here
22       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2017
23       defers to the ISO C standard.
24
25       The time() function shall return the value of time in seconds since the
26       Epoch.
27
28       The tloc argument points to an area where  the  return  value  is  also
29       stored. If tloc is a null pointer, no value is stored.
30

RETURN VALUE

32       Upon successful completion, time() shall return the value of time. Oth‐
33       erwise, (time_t)-1 shall be returned.
34

ERRORS

36       The time() function may fail if:
37
38       EOVERFLOW
39              The number of seconds since the Epoch will not fit in an  object
40              of type time_t.
41
42       The following sections are informative.
43

EXAMPLES

45   Getting the Current Time
46       The  following  example  uses the time() function to calculate the time
47       elapsed, in seconds, since the Epoch, localtime() to convert that value
48       to  a  broken-down  time, and asctime() to convert the broken-down time
49       values into a printable string.
50
51
52           #include <stdio.h>
53           #include <time.h>
54
55           int main(void)
56           {
57           time_t result;
58
59               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
66       This example writes the current time to stdout in a form like this:
67
68
69           Wed Jun 26 10:32:15 1996
70           835810335 secs since the Epoch
71
72   Timing an Event
73       The following example gets the current  time,  prints  it  out  in  the
74       user's  format,  and  prints  the  number  of minutes to an event being
75       timed.
76
77
78           #include <time.h>
79           #include <stdio.h>
80           ...
81           time_t now;
82           int minutes_to_event;
83           ...
84           time(&now);
85           minutes_to_event = ...;
86           printf("The time is ");
87           puts(asctime(localtime(&now)));
88           printf("There are %d minutes to the event.\n",
89               minutes_to_event);
90           ...
91

APPLICATION USAGE

93       None.
94

RATIONALE

96       The time() function returns a value in  seconds  while  clock_gettime()
97       and  gettimeofday()  return a struct timespec (seconds and nanoseconds)
98       and struct timeval (seconds and microseconds),  respectively,  and  are
99       therefore capable of returning more precise times. The times() function
100       is also capable of more precision than time() as it returns a value  in
101       clock  ticks,  although  it returns the elapsed time since an arbitrary
102       point such as system boot time, not since the epoch.
103
104       Implementations in which time_t is a 32-bit signed integer  (many  his‐
105       torical  implementations)  fail in the year 2038. POSIX.1‐2008 does not
106       address this problem. However, the use of the time_t type  is  mandated
107       in order to ease the eventual fix.
108
109       On  some systems the time() function is implemented using a system call
110       that does not return an error  condition  in  addition  to  the  return
111       value. On these systems it is impossible to differentiate between valid
112       and invalid return values and hence overflow conditions cannot be reli‐
113       ably detected.
114
115       The use of the <time.h> header instead of <sys/types.h> allows compati‐
116       bility with the ISO C standard.
117
118       Many historical implementations (including  Version  7)  and  the  1984
119       /usr/group  standard  use  long  instead  of  time_t.   This  volume of
120       POSIX.1‐2017 uses the latter type in order  to  agree  with  the  ISO C
121       standard.
122

FUTURE DIRECTIONS

124       In a future version of this volume of POSIX.1‐2017, time_t is likely to
125       be required to be capable of representing  times  far  in  the  future.
126       Whether  this will be mandated as a 64-bit type or a requirement that a
127       specific date in the future be representable (for example, 10000 AD) is
128       not yet determined. Systems purchased after the approval of this volume
129       of POSIX.1‐2017 should be evaluated to determine whether their lifetime
130       will extend past 2038.
131

SEE ALSO

133       asctime(),  clock(),  clock_getres(),  ctime(), difftime(), futimens(),
134       gettimeofday(),  gmtime(),  localtime(),  mktime(),  strftime(),  strp‐
135       time(), times(), utime()
136
137       The Base Definitions volume of POSIX.1‐2017, <time.h>
138
140       Portions  of  this text are reprinted and reproduced in electronic form
141       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
142       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
143       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
144       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
145       event of any discrepancy between this version and the original IEEE and
146       The  Open Group Standard, the original IEEE and The Open Group Standard
147       is the referee document. The original Standard can be  obtained  online
148       at http://www.opengroup.org/unix/online.html .
149
150       Any  typographical  or  formatting  errors that appear in this page are
151       most likely to have been introduced during the conversion of the source
152       files  to  man page format. To report such errors, see https://www.ker
153       nel.org/doc/man-pages/reporting_bugs.html .
154
155
156
157IEEE/The Open Group                  2017                             TIME(3P)
Impressum