1LOCALTIME(3P) POSIX Programmer's Manual LOCALTIME(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
12 localtime, localtime_r - convert a time value to a broken-down local
13 time
14
16 #include <time.h>
17 struct tm *localtime(const time_t *timer);
19 struct tm *localtime_r(const time_t *restrict timer,
22 struct tm *restrict result);
23
26 For localtime(): The functionality described on this reference page
27 is aligned with the ISO C standard. Any conflict between the require‐
28 ments described here and the ISO C standard is unintentional. This vol‐
29 ume of IEEE Std 1003.1-2001 defers to the ISO C standard.
30 The localtime() function shall convert the time in seconds since the
32 Epoch pointed to by timer into a broken-down time, expressed as a local
33 time. The function corrects for the timezone and any seasonal time
34 adjustments. Local timezone information is used as though localtime()
35 calls tzset().
36 The relationship between a time in seconds since the Epoch used as an
38 argument to localtime() and the tm structure (defined in the <time.h>
39 header) is that the result shall be as specified in the expression
40 given in the definition of seconds since the Epoch (see the Base Defi‐
41 nitions volume of IEEE Std 1003.1-2001, Section 4.14, Seconds Since the
42 Epoch) corrected for timezone and any seasonal time adjustments, where
43 the names in the structure and in the expression correspond.
44 The same relationship shall apply for localtime_r().
46 The localtime() function need not be reentrant. A function that is not
48 required to be reentrant is not required to be thread-safe.
49 The asctime(), ctime(), gmtime(), and localtime() functions shall
51 return values in one of two static objects: a broken-down time struc‐
52 ture and an array of type char. Execution of any of the functions may
53 overwrite the information returned in either of these objects by any of
54 the other functions.
55 The localtime_r() function shall convert the time in seconds since the
57 Epoch pointed to by timer into a broken-down time stored in the struc‐
58 ture to which result points. The localtime_r() function shall also
59 return a pointer to that same structure.
60 Unlike localtime(), the reentrant version is not required to set
62 tzname.
63
65 Upon successful completion, the localtime() function shall return a
66 pointer to the broken-down time structure. If an error is detected,
67 localtime() shall return a null pointer and set errno to indicate the
68 error.
69 Upon successful completion, localtime_r() shall return a pointer to the
71 structure pointed to by the argument result.
72
74 The localtime() function shall fail if:
75 EOVERFLOW
77 The result cannot be represented.
78 The following sections are informative.
81
83 Getting the Local Date and Time
84 The following example uses the time() function to calculate the time
85 elapsed, in seconds, since January 1, 1970 0:00 UTC (the Epoch), local‐
86 time() to convert that value to a broken-down time, and asctime() to
87 convert the broken-down time values into a printable string.
88 #include <stdio.h>
91 #include <time.h>
92 int main(void)
95 {
96 time_t result;
97 result = time(NULL);
100 printf("%s%ju secs since the Epoch\n",
101 asctime(localtime(&result)),
102 (uintmax_t)result);
103 return(0);
104 }
105 This example writes the current time to stdout in a form like this:
107 Wed Jun 26 10:32:15 1996
110 835810335 secs since the Epoch
111 Getting the Modification Time for a File
113 The following example gets the modification time for a file. The local‐
114 time() function converts the time_t value of the last modification
115 date, obtained by a previous call to stat(), into a tm structure that
116 contains the year, month, day, and so on.
117 #include <time.h>
120 ...
121 struct stat statbuf;
122 ...
123 tm = localtime(&statbuf.st_mtime);
124 ...
125 Timing an Event
127 The following example gets the current time, converts it to a string
128 using localtime() and asctime(), and prints it to standard output using
129 fputs(). It then prints the number of minutes to an event being timed.
130 #include <time.h>
133 #include <stdio.h>
134 ...
135 time_t now;
136 int minutes_to_event;
137 ...
138 time(&now);
139 printf("The time is ");
140 fputs(asctime(localtime(&now)), stdout);
141 printf("There are still %d minutes to the event.\n",
142 minutes_to_event);
143 ...
144
146 The localtime_r() function is thread-safe and returns values in a user-
147 supplied buffer instead of possibly using a static data area that may
148 be overwritten by each call.
149
151 None.
152
154 None.
155
157 asctime(), clock(), ctime(), difftime(), getdate(), gmtime(), mktime(),
158 strftime(), strptime(), time(), utime(), the Base Definitions volume of
159 IEEE Std 1003.1-2001, <time.h>
160
162 Portions of this text are reprinted and reproduced in electronic form
163 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
164 -- Portable Operating System Interface (POSIX), The Open Group Base
165 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
166 Electrical and Electronics Engineers, Inc and The Open Group. In the
167 event of any discrepancy between this version and the original IEEE and
168 The Open Group Standard, the original IEEE and The Open Group Standard
169 is the referee document. The original Standard can be obtained online
170 at http://www.opengroup.org/unix/online.html .
171IEEE/The Open Group 2003 LOCALTIME(3P)