localtime
Converts a time value and corrects for the local time zone.
structtm*localtime(consttime_t*timer);
| Routine | Required Header | Compatibility |
| localtime | <time.h> | ANSI, Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
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