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

NAME

12       localtime, localtime_r — convert a time value to  a  broken-down  local
13       time
14

SYNOPSIS

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

DESCRIPTION

23       For  localtime(): The functionality described on this reference page is
24       aligned with the ISO C standard. Any conflict between the  requirements
25       described  here and the ISO C standard is unintentional. This volume of
26       POSIX.1‐2017 defers to the ISO C standard.
27
28       The localtime() function shall convert the time in  seconds  since  the
29       Epoch pointed to by timer into a broken-down time, expressed as a local
30       time. The function corrects for the  timezone  and  any  seasonal  time
31       adjustments.   Local timezone information is used as though localtime()
32       calls tzset().
33
34       The relationship between a time in seconds since the Epoch used  as  an
35       argument  to  localtime() and the tm structure (defined in the <time.h>
36       header) is that the result shall be  as  specified  in  the  expression
37       given  in the definition of seconds since the Epoch (see the Base Defi‐
38       nitions volume of POSIX.1‐2017, Section 4.16, Seconds Since the  Epoch)
39       corrected  for  timezone  and  any seasonal time adjustments, where the
40       names in the structure and in the expression correspond.
41
42       The same relationship shall apply for localtime_r().
43
44       The localtime() function need not be thread-safe.
45
46       The asctime(),  ctime(),  gmtime(),  and  localtime()  functions  shall
47       return  values  in one of two static objects: a broken-down time struc‐
48       ture and an array of type char.  Execution of any of the functions  may
49       overwrite the information returned in either of these objects by any of
50       the other functions.
51
52       The localtime_r() function shall convert the time in seconds since  the
53       Epoch  pointed to by timer into a broken-down time stored in the struc‐
54       ture to which result points.  The  localtime_r()  function  shall  also
55       return a pointer to that same structure.
56
57       Unlike  localtime(),  the localtime_r() function is not required to set
58       tzname.  If localtime_r() sets tzname, it shall also set  daylight  and
59       timezone.   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
89           #include <stdio.h>
90           #include <time.h>
91
92           int main(void)
93           {
94               time_t result;
95
96               result = time(NULL);
97               printf("%s%ju secs since the Epoch\n",
98                   asctime(localtime(&result)),
99                       (uintmax_t)result);
100               return(0);
101           }
102
103       This example writes the current time to stdout in a form like this:
104
105
106           Wed Jun 26 10:32:15 1996
107           835810335 secs since the Epoch
108
109   Getting the Modification Time for a File
110       The  following  example  prints the last data modification timestamp in
111       the local timezone for a given file.
112
113
114           #include <stdio.h>
115           #include <time.h>
116           #include <sys/stat.h>
117
118           int
119           print_file_time(const char *pathname)
120           {
121               struct stat statbuf;
122               struct tm *tm;
123               char timestr[BUFSIZ];
124
125               if(stat(pathname, &statbuf) == -1)
126                   return -1;
127               if((tm = localtime(&statbuf.st_mtime)) == NULL)
128                   return -1;
129               if(strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S", tm) == 0)
130                   return -1;
131               printf("%s: %s.%09ld\n", pathname, timestr, statbuf.st_mtim.tv_nsec);
132               return 0;
133           }
134
135   Timing an Event
136       The following example gets the current time, converts it  to  a  string
137       using localtime() and asctime(), and prints it to standard output using
138       fputs().  It then prints the number of minutes to an event being timed.
139
140
141           #include <time.h>
142           #include <stdio.h>
143           ...
144           time_t now;
145           int minutes_to_event;
146           ...
147           time(&now);
148           printf("The time is ");
149           fputs(asctime(localtime(&now)), stdout);
150           printf("There are still %d minutes to the event.\n",
151               minutes_to_event);
152           ...
153

APPLICATION USAGE

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

RATIONALE

160       None.
161

FUTURE DIRECTIONS

163       None.
164

SEE ALSO

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