1LOCALTIME(3P)              POSIX Programmer's Manual             LOCALTIME(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       localtime, localtime_r — convert a time value to  a  broken-down  local
14       time
15

SYNOPSIS

17       #include <time.h>
18
19       struct tm *localtime(const time_t *timer);
20       struct tm *localtime_r(const time_t *restrict timer,
21           struct tm *restrict result);
22

DESCRIPTION

24       For  localtime(): The functionality described on this reference page is
25       aligned with the ISO C standard. Any conflict between the  requirements
26       described  here and the ISO C standard is unintentional. This volume of
27       POSIX.1‐2008 defers to the ISO C standard.
28
29       The localtime() function shall convert the time in  seconds  since  the
30       Epoch pointed to by timer into a broken-down time, expressed as a local
31       time. The function corrects for the  timezone  and  any  seasonal  time
32       adjustments.   Local timezone information is used as though localtime()
33       calls tzset().
34
35       The relationship between a time in seconds since the Epoch used  as  an
36       argument  to  localtime() and the tm structure (defined in the <time.h>
37       header) is that the result shall be  as  specified  in  the  expression
38       given  in the definition of seconds since the Epoch (see the Base Defi‐
39       nitions volume of POSIX.1‐2008, Section 4.15, Seconds Since the  Epoch)
40       corrected  for  timezone  and  any seasonal time adjustments, where the
41       names in the structure and in the expression correspond.
42
43       The same relationship shall apply for localtime_r().
44
45       The localtime() function need not be thread-safe.
46
47       The asctime(),  ctime(),  gmtime(),  and  localtime()  functions  shall
48       return  values  in one of two static objects: a broken-down time struc‐
49       ture and an array of type char.  Execution of any of the functions  may
50       overwrite the information returned in either of these objects by any of
51       the other functions.
52
53       The localtime_r() function shall convert the time in seconds since  the
54       Epoch  pointed to by timer into a broken-down time stored in the struc‐
55       ture to which result points.  The  localtime_r()  function  shall  also
56       return a pointer to that same structure.
57
58       Unlike  localtime(),  the localtime_r() function is not required to set
59       tzname.  If localtime_r() does not set tzname, it shall  not  set  day‐
60       light and shall not set timezone.
61

RETURN VALUE

63       Upon  successful  completion,  the  localtime() function shall return a
64       pointer to the broken-down time structure.  If an  error  is  detected,
65       localtime()  shall  return a null pointer and set errno to indicate the
66       error.
67
68       Upon successful completion, localtime_r() shall return a pointer to the
69       structure  pointed to by the argument result.  If an error is detected,
70       localtime_r() shall return a null pointer and set errno to indicate the
71       error.
72

ERRORS

74       The localtime() and localtime_r() functions shall fail if:
75
76       EOVERFLOW
77              The result cannot be represented.
78
79       The following sections are informative.
80

EXAMPLES

82   Getting the Local Date and Time
83       The  following  example  uses the time() function to calculate the time
84       elapsed, in seconds, since January 1, 1970 0:00 UTC (the Epoch), local‐
85       time()  to  convert  that value to a broken-down time, and asctime() to
86       convert the broken-down time values into a printable string.
87
88           #include <stdio.h>
89           #include <time.h>
90
91           int main(void)
92           {
93               time_t result;
94
95               result = time(NULL);
96               printf("%s%ju secs since the Epoch\n",
97                   asctime(localtime(&result)),
98                       (uintmax_t)result);
99               return(0);
100           }
101
102       This example writes the current time to stdout in a form like this:
103
104           Wed Jun 26 10:32:15 1996
105           835810335 secs since the Epoch
106
107   Getting the Modification Time for a File
108       The following example prints the last data  modification  timestamp  in
109       the local timezone for a given file.
110
111           #include <stdio.h>
112           #include <time.h>
113           #include <sys/stat.h>
114
115           int
116           print_file_time(const char *pathname)
117           {
118               struct stat statbuf;
119               struct tm *tm;
120               char timestr[BUFSIZ];
121
122               if(stat(pathname, &statbuf) == −1)
123                   return −1;
124               if((tm = localtime(&statbuf.st_mtime)) == NULL)
125                   return −1;
126               if(strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S", tm) == 0)
127                   return −1;
128               printf("%s: %s.%09ld\n", pathname, timestr, statbuf.st_mtim.tv_nsec);
129               return 0;
130           }
131
132   Timing an Event
133       The  following  example  gets the current time, converts it to a string
134       using localtime() and asctime(), and prints it to standard output using
135       fputs().  It then prints the number of minutes to an event being timed.
136
137           #include <time.h>
138           #include <stdio.h>
139           ...
140           time_t now;
141           int minutes_to_event;
142           ...
143           time(&now);
144           printf("The time is ");
145           fputs(asctime(localtime(&now)), stdout);
146           printf("There are still %d minutes to the event.\n",
147               minutes_to_event);
148           ...
149

APPLICATION USAGE

151       The localtime_r() function is thread-safe and returns values in a user-
152       supplied buffer instead of possibly using a static data area  that  may
153       be overwritten by each call.
154

RATIONALE

156       None.
157

FUTURE DIRECTIONS

159       None.
160

SEE ALSO

162       asctime(), clock(), ctime(), difftime(), getdate(), gmtime(), mktime(),
163       strftime(), strptime(), time(), tzset(), utime()
164
165       The Base Definitions volume  of  POSIX.1‐2008,  Section  4.15,  Seconds
166       Since the Epoch, <time.h>
167
169       Portions  of  this text are reprinted and reproduced in electronic form
170       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
171       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
172       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
173       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
174       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
175       event of any discrepancy between this version and the original IEEE and
176       The Open Group Standard, the original IEEE and The Open Group  Standard
177       is  the  referee document. The original Standard can be obtained online
178       at http://www.unix.org/online.html .
179
180       Any typographical or formatting errors that appear  in  this  page  are
181       most likely to have been introduced during the conversion of the source
182       files to man page format. To report such errors,  see  https://www.ker
183       nel.org/doc/man-pages/reporting_bugs.html .
184
185
186
187IEEE/The Open Group                  2013                        LOCALTIME(3P)
Impressum