Export (0) Print
Expand All

localtime, _localtime64

Convert a time value and correct for the local time zone.

struct tm *localtime(
   const time_t *timer 
);
struct tm *_localtime64(
   const __time64_t *timer 
);

Parameter

timer
Pointer to stored time.

Return Value

Return a pointer to the structure result. If the value in timer represents a date before midnight, January 1, 1970, return NULL.

_localtime64, which uses the __time64_t structure, allows dates to be expressed up through 23:59:59, December 31, 3000, coordinated universal time (UTC), whereas localtime represents dates through 19:14:07 January 18, 2038, UTC.

The fields of the structure type tm store the following values, each of which is an int:

tm_sec
Seconds after minute (0 – 59).
tm_min
Minutes after hour (0 – 59).
tm_hour
Hours after midnight (0 – 23).
tm_mday
Day of month (1 – 31).
tm_mon
Month (0 – 11; January = 0).
tm_year
Year (current year minus 1900).
tm_wday
Day of week (0 – 6; Sunday = 0).
tm_yday
Day of year (0 – 365; January 1 = 0).
tm_isdst
Positive value if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative value if status of daylight saving time is unknown. If the TZ environment variable is set, the C run-time library assumes rules appropriate to the United States for implementing the calculation of daylight-saving time (DST).

Remarks

The localtime function converts a time stored as a time_t value and stores the result in a structure of type tm. The long value timer represents the seconds elapsed since midnight (00:00:00), January 1, 1970, UTC. This value is usually obtained from the time function.

gmtime, mktime, and localtime all use a single statically allocated tm structure for the conversion. Each call to one of these routines destroys the result of the previous call.

localtime corrects for the local time zone if the user first sets the global environment variable TZ. When TZ is set, three other environment variables (_timezone, _daylight, and _tzname) are automatically set as well. If the TZ variable is not set, localtime attempts to use the time zone information specified in the Date/Time application in Control Panel. If this information cannot be obtained, PST8PDT, which signifies the Pacific time zone, is used by default. See _tzset for a description of these variables. TZ is a Microsoft extension and not part of the ANSI standard definition of localtime.

Note   The target environment should try to determine whether daylight saving time is in effect.

Requirements

Routine Required header Compatibility
localtime <time.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
_localtime64 <time.h> Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_localtim.c
/* This program uses _time64 to get the current time 
 * and then uses localtime64() to convert this time to a structure 
 * representing the local time. The program converts the result 
 * from a 24-hour clock to a 12-hour clock and determines the 
 * proper extension (AM or PM).
 */

#include <stdio.h>
#include <string.h>
#include <time.h>

int main( void )
{
        struct tm *newtime;
        char am_pm[] = "AM";
        __time64_t long_time;

        _time64( &long_time );                /* Get time as long integer. */
        newtime = _localtime64( &long_time ); /* Convert to local time. */

        if( newtime->tm_hour > 12 )        /* Set up extension. */
                strcpy( am_pm, "PM" );
        if( newtime->tm_hour > 12 )        /* Convert from 24-hour */
                newtime->tm_hour -= 12;    /*   to 12-hour clock.  */
        if( newtime->tm_hour == 0 )        /*Set hour to 12 if midnight. */
                newtime->tm_hour = 12;

        printf( "%.19s %s\n", asctime( newtime ), am_pm );
}

Sample Output

Tue Feb 12 10:05:58 AM

See Also

Time Management Routines | asctime | ctime | _ftime | gmtime | time | _tzset | Run-Time Routines and .NET Framework Equivalents

Show:
© 2014 Microsoft