localtime, _localtime32, _localtime64

Статья
06/09/2015

Преобразовать значение времени и исправить для местного часового пояса. Существуют более безопасные версии этих функций; см. раздел localtime_s, _localtime32_s, _localtime64_s.

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

Параметры

timer
Указатель на сохраненное время.

Возвращаемое значение

Возвращает указатель на структурированный результат или NULL, если дата, переданная функции, выглядит следующим образом:

До полуночи 1-го января 1970.
После 03:14: 07 19-го января 2038, время в формате UTC (с помощью _time32 и time32_t).
После 23:59:59 31-го декабря 3000, время в формате UTC (с помощью _time64 и __time64_t).

_localtime64, которая использует структуру __time64_t, разрешает даты до 23:59: 59 31-го декабря 3000, время в формате UTC, тогда как _localtime32 представляет даты до 03:14:07 19-го января 2038, время в формате UTC.

localtime — встроенная функция, которая принимает значение _localtime64 и time_t эквивалентна __time64_t. Если необходимо обеспечить интерпретацию компилятором time_tкак старого 32-битного time_t, можно определить _USE_32BIT_TIME_T. Это заставит localtime вычисляться как _localtime32. Это не рекомендуется, поскольку приложение может завершиться с ошибкой после 19-ого января 2038 и не поддерживается на 64 разрядных платформах.

Поля структурного типа tm хранят следующие значения, каждое из которых является int:

tm_sec
Секунды после минуты (0 — 59).
tm_min
Минуты после часа (0 — 59).
tm_hour
Часы после полуночи (от 0 до 23).
tm_mday
День месяца (1 – 31).
tm_mon
Месяц (0 — 11; Январь = 0).
tm_year
Год (текущий год минус 1900).
tm_wday
День недели (0 – 6; 0 = воскресенье).
tm_yday
День года (0 — 365; 1-е января = 0).
tm_isdst
Положительное значение, если действует летнее время; 0, если летнее время не действует; отрицательное значение, если состояние летнего времени неизвестно. Если переменная среды TZ задана, библиотека времени выполнения C принимает правила, соответствующие Соединенным Штатам, для реализации перехода на летнее время (DST).

Заметки

Функция localtime преобразует время, хранящееся в виде значения time_t и сохраняет результат в структуре типа tm. long значение timer представляет секунды, прошедшие с полуночи (00:00:00) 1-го января 1970, время в формате UTC. Это значение обычно получается из функции time.

32-разрядные и 64-разрядные версии gmtime, mktime, mkgmtime и localtime используют единственную для потока структуру tm для преобразования. Каждый вызов одной из этих процедур уничтожает результат предыдущего вызова.

localtime исправляется для местного часового пояса, если пользователь сначала задает глобальную переменную среды TZ. Если TZ задано, три других переменных среды (_timezone, _daylight и _tzname) также устанавливаются автоматически. Если переменная TZ не задана, localtime пытается использовать данные часового пояса, определенные в приложении Дата/время в Панели управления. Если эти сведения недоступны, PST8PDT, что означает Тихоокеанский часовой пояс, используется по умолчанию. См. _tzset для описания этих переменных. TZ является расширением Майкрософт и не является частью стандарта ANSI для localtime.

Примечание

Целевая среда должна попытаться определить, действует ли летнее время.

Эти функции проверяют свои параметры. Если параметр timer — нулевой указатель, или значение таймера отрицательно, эти функции вызывают обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают NULL и устанавливают для errno значение EINVAL.

Требования

Подпрограмма	Обязательный заголовок
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

Дополнительные сведения о совместимости см. в разделе Совместимость во введении.

Пример

// crt_localtime.cpp
// compile with: /W3
/* 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 64-bit integer.
                                         // Convert to local time.
        newtime = _localtime64( &long_time ); // C4996
        // Note: _localtime64 deprecated; consider _localetime64_s

        if( newtime->tm_hour > 12 )        // Set up extension.
                strcpy_s( am_pm, sizeof(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;

        char buff[30];
        asctime_s( buff, sizeof(buff), newtime );
        printf( "%.19s %s\n", buff, am_pm );
}