GNU Info

Info Node: (libc.info)Broken-down Time

(libc.info)Broken-down Time


Next: High Accuracy Clock Prev: High-Resolution Calendar Up: Calendar Time
Enter node , (file) or (file)node

Broken-down Time
----------------

   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.

    `int tm_sec'
          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 available).

    `int tm_min'
          This is the number of full minutes since the top of the hour
          (in the range `0' through `59').

    `int tm_hour'
          This is the number of full hours past midnight (in the range
          `0' through `23').

    `int tm_mday'
          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.

    `int tm_mon'
          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).

    `int tm_year'
          This is the number of full calendar years since 1900.

    `int tm_wday'
          This is the number of full days since Sunday (in the range
          `0' through `6').

    `int tm_yday'
          This is the number of full days since the beginning of the
          year (in the range `0' through `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, 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.

 - Function: struct tm * localtime (const time_t *TIME)
     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 an `int'.

     Calling `localtime' has one other effect: it sets the variable
     `tzname' with information about the current time zone.  Note: 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.

 - Function: struct tm * localtime_r (const time_t *TIME, struct tm
          *RESULTP)
     The `localtime_r' function works just like the `localtime'
     function.  It takes a pointer to a variable containing a simple
     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.

 - 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)
     (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 `gmtime'.

 - Function: struct tm * gmtime_r (const time_t *TIME, struct tm
          *RESULTP)
     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.  Note: Time Zone Functions.

 - Function: time_t timelocal (struct tm *BROKENTIME)
     `timelocal' is functionally identical to `mktime', but more
     mnemonically named.  Note that it is the inverse of the `localtime'
     function.

     *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 `TZ'
     back.



automatically generated by info2www version 1.2.2.9