libc - Broken-down Time

Broken-down Time

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

-- 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' (*note Time
          Zone Functions::.).  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. *Note Time Zone Functions::.

--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. *Note Time Zone Functions::.

converted by gnuinfo