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
11

NAME

13       time — get time
14

SYNOPSIS

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

DESCRIPTION

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
26       The time() function shall return the value of time in seconds since the
27       Epoch.
28
29       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

RETURN VALUE

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

ERRORS

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

EXAMPLES

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
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           Wed Jun 26 10:32:15 1996
69           835810335 secs since the Epoch
70
71   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
76           #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

APPLICATION USAGE

91       None.
92

RATIONALE

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
102       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
107       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
113       The use of the <time.h> header instead of <sys/types.h> allows compati‐
114       bility with the ISO C standard.
115
116       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

FUTURE DIRECTIONS

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

SEE ALSO

131       asctime(),  clock(),  clock_getres(),  ctime(), difftime(), futimens(),
132       gettimeofday(),  gmtime(),  localtime(),  mktime(),  strftime(),  strp‐
133       time(), times(), utime()
134
135       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
149       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 .
153
154
155
156IEEE/The Open Group                  2013                             TIME(3P)
Impressum