Calendar time is represented by the usual GNU C library functions as an
elapsed time since a fixed base calendar time. This is convenient for
computation, but has no relation to the way people normally think of
calendar time. By contrast, broken-down time is a binary
representation of calendar time 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 information.
A broken-down time value is always relative to a choice of time
zone, and it also indicates which time zone that is.
The symbols in this section are declared in the header file time.h.
— Data Type: struct tm
This is the data type used to represent a broken-down time. The structure
contains at least the following members, which can appear in any order.
This is the number of full seconds since the top of the minute (normally
in the range 0 through 59, but the actual upper limit is
60, to allow for leap seconds if leap second support is
This is the number of full minutes since the top of the hour (in the
range 0 through 59).
This is the number of full hours past midnight (in the range 0 through
This is the ordinal day of the month (in the range 1 through 31).
Watch out for this one! As the only ordinal number in the structure, it is
inconsistent with the rest of the structure.
This is the number of full calendar months since the beginning of the
year (in the range 0 through 11). Watch out for this one!
People usually use ordinal numbers for month-of-year (where January = 1).
This is the number of full calendar years since 1900.
This is the number of full days since Sunday (in the range 0 through
This is the number of full days since the beginning of the year (in the
range 0 through 365).
This is a flag that indicates whether Daylight Saving Time is (or was, or
will be) in effect at the time described. The value is positive if
Daylight Saving Time is in effect, zero if it is not, and negative if the
information is not available.
long int tm_gmtoff
This field describes the time zone that was used to compute this
broken-down time value, including any adjustment for daylight saving; it
is the number of seconds that you must add to UTC to get local time.
You can also think of this as the number of seconds east of UTC. For
example, for U.S. Eastern Standard Time, the value is -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
This field is the name for the time zone that was used to compute this
broken-down time value. Like tm_gmtoff, this field is a BSD and
GNU extension, and is not visible in a strict ISO C environment.
The localtime function converts the simple 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
Calling localtime has one other effect: it sets the variable
tzname with information about the current time zone. See Time Zone Functions.
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.
This function is similar to localtime, except that the broken-down
time is expressed as Coordinated Universal Time (UTC) (formerly called
Greenwich Mean Time (GMT)) rather than relative to a local time zone.
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
This function is similar to 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.
— Function: time_t mktime (struct tm *brokentime)
The mktime function is used to convert a broken-down time structure
to a simple 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 determine the
calendar time; it's permissible for these components to have
unnormalized values outside 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 simple 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 Time Zone Functions.
timelocal is functionally identical to mktime, but more
mnemonically named. Note that it is the inverse of the localtime
Portability note:mktime is essentially universally
available. timelocal is rather rare.
— Function: time_t timegm (struct tm *brokentime)
timegm is functionally identical to mktime except it
always takes the input values to be Coordinated Universal Time (UTC)
regardless of any local time zone setting.
Note that timegm is the inverse of gmtime.
Portability note:mktime is essentially universally
available. timegm is rather rare. For the most portable
conversion from a UTC broken-down time to a simple time, set
the TZ environment variable to UTC, call mktime, then set
Published under the terms of the GNU General Public License