localtime, localtime_r, localtime_s

Определено в заголовке `<time.h>`
struct tm localtime ( const time_t timer );	(1)
struct tm localtime_r( const time_t timer, struct tm *buf );	(2)	(с C23)
struct tm localtime_s( const time_t restrict timer, struct tm *restrict buf );	(3)	(с C11)

1) Преобразует заданное время с момента эпохи (значение time_t, на которое указывает timer) в календарное время, выраженное в местном времени, в формате struct tm. Результат хранится в статической памяти, и указатель на эту статическую память возвращается.

2) Аналогично (1), за исключением того, что функция использует предоставленную пользователем память buf для хранения результата.

3) Аналогично (1), за исключением того, что функция использует предоставленную пользователем память buf для хранения результата и что следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений обработчика ограничений:

timer или buf является нулевым указателем

Как и во всех функциях с проверкой границ, localtime_s гарантированно доступна только в том случае, если __STDC_LIB_EXT1__ определена реализацией, а пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <time.h>.

Параметры

timer	-	указатель на объект `time_t` для преобразования
buf	-	указатель на объект `struct tm` для хранения результата

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

1) указатель на статический внутренний объект tm при успешном выполнении или нулевой указатель в противном случае. Структура может быть общей между gmtime, localtime, и ctime и может быть перезаписана при каждом вызове.

2-3) копия указателя buf, или нулевой указатель при ошибке (которая может быть нарушением ограничения во время выполнения или ошибкой преобразования указанного времени в местное календарное время)

Примечания

Функция localtime может быть небезопасной для многопоточного доступа.

POSIX требует, чтобы localtime и localtime_r устанавливали errno в EOVERFLOW в случае неудачи из-за слишком большого аргумента.

POSIX определяет, что информация о часовом поясе определяется localtime и localtime_r как при вызове tzset, который читает переменную окружения TZ.

Реализация localtime_s в Microsoft CRT несовместима со стандартом C, поскольку она изменила порядок параметров и возвращает errno_t.

Пример

#define __STDC_WANT_LIB_EXT1__ 1
#define _XOPEN_SOURCE // for putenv
#include <time.h>
#include <stdio.h>
#include <stdlib.h>   // for putenv
 
int main(void)
{
    time_t t = time(NULL);
    printf("UTC:       %s", asctime(gmtime(&t)));
    printf("local:     %s", asctime(localtime(&t)));
    // POSIX-specific
    putenv("TZ=Asia/Singapore");
    printf("Singapore: %s", asctime(localtime(&t)));
 
#ifdef __STDC_LIB_EXT1__
    struct tm buf;
    char str[26];
    asctime_s(str,sizeof str,gmtime_s(&t, &buf));
    printf("UTC:       %s", str);
    asctime_s(str,sizeof str,localtime_s(&t, &buf));
    printf("local:     %s", str);
#endif
}

Возможный вывод:

UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017
Singapore: Fri Sep 15 22:22:05 2017
UTC:       Fri Sep 15 14:22:05 2017
local:     Fri Sep 15 14:22:05 2017

Ссылки

Стандарт C17 (ISO/IEC 9899:2018):

7.27.3.4 Функция localtime (стр. 288)
K.3.8.2.4 Функция localtime_s (стр. 455)

Стандарт C11 (ISO/IEC 9899:2011):

7.27.3.4 Функция localtime (стр. 394)
K.3.8.2.4 Функция localtime_s (стр. 627)

Стандарт C99 (ISO/IEC 9899:1999):

7.23.3.4 Функция localtime (стр. 343)

Стандарт C89/C90 (ISO/IEC 9899:1990):

4.12.3.4 Функция localtime

См. также

gmtimegmtime_rgmtime_s (C23)(C11)	преобразует время с момента эпохи в календарное время, выраженное в координированном всемирном времени (UTC) (функция)
Документация C++ для `localtime`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/chrono/localtime