Go to the previous, next section.

Broken-down Time

Calender 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'.

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:

int tm_sec

This is the number of seconds after the minute, normally in the range 0 to 59. (The actual upper limit is 61, to allow for "leap seconds".)

int tm_min

This is the number of minutes after the hour, in the range 0 to 59.

int tm_hour

This is the number of hours past midnight, in the range 0 to 23.

int tm_mday

This is the day of the month, in the range 1 to 31.

int tm_mon

This is the number of months since January, in the range 0 to 11.

int tm_year

This is the number of years since 1900.

int tm_wday

This is the number of days since Sunday, in the range 0 to 6.

int tm_yday

This is the number of days since January 1, in the range 0 to 365.

int tm_isdst

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; it is the amount you must add to the local time in that zone to get GMT, in units of seconds. The value is like that of the variable timezone (see section Functions and Variables for Time Zones). You can also think of this as the "number of seconds west" of GMT. The tm_gmtoff field is a GNU library extension.

const char *tm_zone

This field is the three-letter name for the time zone that was used to compute this broken-down time value. It is a GNU library extension.

Function: struct tm * localtime (const time_t *time)

The 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 any of the date and time functions. (But no other library function overwrites the contents of this object.)

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.

Function: struct tm * gmtime (const time_t *time)

This function is similar to 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.

Function: time_t mktime (struct tm *brokentime)

The 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 previous, next section.