Calendar time is represented as a number of seconds. This is convenient for calculation, but has no resemblance to the way people normally represent dates and times. By contrast, broken-down time is a binary representation separated into year, month, day, and so on. Broken down time values are not useful for calculations, but they are useful for printing human readable time.
A broken-down time value is always relative to a choice of local time zone, and it also indicates which time zone was used.
The symbols in this section are declared in the header file `time.h'.
int tm_sec
0
through 59
. (The actual upper limit is 60
, to allow
for leap seconds if leap second support is available.)
int tm_min
0
through
59
.
int tm_hour
0
through
23
.
int tm_mday
1
through 31
.
int tm_mon
0
through
11
.
int tm_year
1900
.
int tm_wday
0
through
6
.
int tm_yday
0
through
365
.
int tm_isdst
long int tm_gmtoff
-5*60*60
.
The tm_gmtoff
field is derived from BSD and is a GNU library
extension; it is not visible in a strict ISO C environment.
const char *tm_zone
tm_gmtoff
, this field is a BSD and
GNU extension, and is not visible in a strict ISO C environment.
localtime
function converts the calendar time pointed to by
time to broken-down time representation, expressed relative to the
user's specified time zone.
The return value is a pointer to a static broken-down time structure, which
might be overwritten by subsequent calls to ctime
, gmtime
,
or localtime
. (But no other library function overwrites the contents
of this object.)
The return value is the null pointer if time cannot be represented
as a broken-down time; typically this is because the year cannot fit into
an int
.
Calling localtime
has one other effect: it sets the variable
tzname
with information about the current time zone. See section Functions and Variables for Time Zones.
Using the localtime
function is a big problem in multi-threaded
programs. The result is returned in a static buffer and this is used in
all threads. POSIX.1c introduced a variant of this function.
localtime_r
function works just like the localtime
function. It takes a pointer to a variable containing the calendar time
and converts it to the broken-down time format.
But the result is not placed in a static buffer. Instead it is placed
in the object of type struct tm
to which the parameter
resultp points.
If the conversion is successful the function returns a pointer to the object the result was written into, i.e., it returns resultp.
localtime
, except that the broken-down
time is expressed as Coordinated Universal Time (UTC)---that is, as
Greenwich Mean Time (GMT)---rather than relative to the local time zone.
Recall that calendar times are always expressed in coordinated universal time.
As for the localtime
function we have the problem that the result
is placed in a static variable. POSIX.1c also provides a replacement for
gmtime
.
localtime_r
, except that it converts
just like gmtime
the given time as Coordinated Universal Time.
If the conversion is successful the function returns a pointer to the object the result was written into, i.e., it returns resultp.
mktime
function is used to convert a broken-down time structure
to a calendar time representation. It also "normalizes" the contents of
the broken-down time structure, by filling in the day of week and day of
year based on the other date and time components.
The mktime
function ignores the specified contents of the
tm_wday
and tm_yday
members of the broken-down time
structure. It uses the values of the other components to compute the
calendar time; it's permissible for these components to have
unnormalized values outside of their normal ranges. The last thing that
mktime
does is adjust the components of the brokentime
structure (including the tm_wday
and tm_yday
).
If the specified broken-down time cannot be represented as a calendar time,
mktime
returns a value of (time_t)(-1)
and does not modify
the contents of brokentime.
Calling mktime
also sets the variable tzname
with
information about the current time zone. See section Functions and Variables for Time Zones.
Go to the first, previous, next, last section, table of contents.