localtime

Converts a time value and corrects for the local time zone.

struct tm *localtime( const time_t *timer );

For additional compatibility information, see Compatibility in the Introduction.

Libraries

Return Value

localtime returns a pointer to the structure result. If the value in timer represents a date before midnight, January 1, 1970, localtime returns NULL. 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. The C run-time library assumes the United States’s rules for implementing the calculation of Daylight Saving Time (DST).

Parameter

timer

Pointer to stored time

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, coordinated universal time (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. 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.

Example

/* LOCALTIM.C: This program uses time to get the current time 
 * and then uses localtime 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>

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

        time( &long_time );                /* Get time as long integer. */
        newtime = localtime( &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 );
}

Output

Tue Mar 23 11:28:17 AM

Time Management Routines

See Also   asctime, ctime, _ftime, gmtime, time, _tzset