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

NAME

6       localtime,  localtime_r  -  convert a time value to a broken-down local
7       time
8

SYNOPSIS

10       #include <time.h>
11
12       struct tm *localtime(const time_t *timer);
13
14
15       struct tm *localtime_r(const time_t *restrict timer,
16              struct tm *restrict result);
17
18

DESCRIPTION

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

RETURN VALUE

59       Upon successful completion, the localtime()  function  shall  return  a
60       pointer  to  the  broken-down  time structure. If an error is detected,
61       localtime() shall return a null pointer  and set errno to indicate  the
62       error.
63
64       Upon successful completion, localtime_r() shall return a pointer to the
65       structure pointed to by the argument result.
66

ERRORS

68       The localtime() function shall fail if:
69
70       EOVERFLOW
71              The result cannot be represented.
72
73
74       The following sections are informative.
75

EXAMPLES

77   Getting the Local Date and Time
78       The following example uses the time() function to  calculate  the  time
79       elapsed, in seconds, since January 1, 1970 0:00 UTC (the Epoch), local‐
80       time() to convert that value to a broken-down time,  and  asctime()  to
81       convert the broken-down time values into a printable string.
82
83
84              #include <stdio.h>
85              #include <time.h>
86
87
88              int main(void)
89              {
90                  time_t result;
91
92
93                  result = time(NULL);
94                  printf("%s%ju secs since the Epoch\n",
95                      asctime(localtime(&result)),
96                          (uintmax_t)result);
97                  return(0);
98              }
99
100       This example writes the current time to stdout in a form like this:
101
102
103              Wed Jun 26 10:32:15 1996
104              835810335 secs since the Epoch
105
106   Getting the Modification Time for a File
107       The following example gets the modification time for a file. The local‐
108       time() function converts the time_t  value  of  the  last  modification
109       date,  obtained  by a previous call to stat(), into a tm structure that
110       contains the year, month, day, and so on.
111
112
113              #include <time.h>
114              ...
115              struct stat statbuf;
116              ...
117              tm = localtime(&statbuf.st_mtime);
118              ...
119
120   Timing an Event
121       The following example gets the current time, converts it  to  a  string
122       using localtime() and asctime(), and prints it to standard output using
123       fputs(). It then prints the number of minutes to an event being timed.
124
125
126              #include <time.h>
127              #include <stdio.h>
128              ...
129              time_t now;
130              int minutes_to_event;
131              ...
132              time(&now);
133              printf("The time is ");
134              fputs(asctime(localtime(&now)), stdout);
135              printf("There are still %d minutes to the event.\n",
136                  minutes_to_event);
137              ...
138

APPLICATION USAGE

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

RATIONALE

145       None.
146

FUTURE DIRECTIONS

148       None.
149

SEE ALSO

151       asctime() , clock() , ctime() , difftime() ,  getdate()  ,  gmtime()  ,
152       mktime()  , strftime() , strptime() , time() , utime() , the Base Defi‐
153       nitions volume of IEEE Std 1003.1-2001, <time.h>
154
156       Portions of this text are reprinted and reproduced in  electronic  form
157       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
158       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
159       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
160       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
161       event of any discrepancy between this version and the original IEEE and
162       The Open Group Standard, the original IEEE and The Open Group  Standard
163       is  the  referee document. The original Standard can be obtained online
164       at http://www.opengroup.org/unix/online.html .
165
166
167
168IEEE/The Open Group                  2003                         LOCALTIME(P)
Impressum