Convert a time value to broken-down local time.

    Format

      #include  <time.h>

      struct tm *localtime  (const time_t *timer);

      struct tm *localtime_r  (const time_t *timer, struct tm *result);
                                   (ISO POSIX-1)

1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    localtime_r function that is equivalent to the behavior before
    OpenVMS Version 7.0.

2  –  Arguments

 timer

    A pointer to a time in seconds since the Epoch. You can generate
    this time by using the time function or you can supply a time.

 result

    A pointer to a tm structure where the result is stored. The tm
    structure is defined in the <time.h> header file, and is also
    shown in tm Structure.

3  –  Description

    The localtime and localtime_r functions convert the time (in
    seconds since the Epoch) pointed to by timer into a broken-down
    time, expressed as a local time, and store it in a tm structure.

    The difference between the localtime_r and localtime functions
    is that the former stores the result into a user-specified tm
    structure. The latter stores the result into thread-specific
    static memory allocated by the C RTL, and which is
    overwritten by subsequent calls to localtime; you must make a
    copy if you want to save it.

    On success, localtime returns a pointer to the tm structure;
    localtime_r returns its second argument. On failure, these
    functions return the NULL pointer.

    The tm structure is defined in the <time.h> header file and
    described in tm Structure.

    Table REF-4 tm Structure

    int tm_sec;      Seconds after the minute (0-60)
    int tm_min;      Minutes after the hour (0-59)
    int tm_hour;     Hours since midnight (0-23)
    int tm_mday;     Day of the month (1-31)
    int tm_mon;      Months since January (1-11)
    int tm_year;     Years since 1900
    int tm_wday;     Days since Sunday (0-6)
    int tm_yday;     Days since January 1 (0-365)
    int tm_isdst;    Daylight Savings Time flag

                     o  tm_isdst = 0 for Standard Time

                     o  tm_isdst = 1 for Daylight Time

    long tm_gmtoff;  Seconds east of Greenwich (negative values
                     indicate seconds west of Greenwich)
    char *tm_zone;   Time zone string, for example "GMT"

    The type time_t is defined in the <time.h> header file as
    follows:

    typedef long int time_t

                                   NOTE

       Generally speaking, UTC-based time functions can affect in-
       memory time-zone information, which is processwide data.
       However, if the system time zone remains the same during
       the execution of the application (which is the common case)
       and the cache of timezone files is enabled (which is the
       default), then the _r variant of the time functions asctime_
       r, ctime_r, gmtime_r and localtime_r, is both thread-safe
       and AST-reentrant.

       If, however, the system time zone can change during the
       execution of the application or the cache of timezone files
       is not enabled, then both variants of the UTC-based time
       functions belong to the third class of functions, which are
       neither thread-safe nor AST-reentrant.

4  –  Return Values

    x                  Pointer to a tm structure.
    NULL               Indicates failure.