asctime(3) gmtime_r,

ОБЗОР

#include <time.h>

char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *tm, char *buf);
char *ctime(const time_t *timep);
char *ctime_r(const time_t *timep, char *buf);
struct tm *gmtime(const time_t *timep);
struct tm *gmtime_r(const time_t *timep, struct tm *result);
struct tm *localtime(const time_t *timep);
struct tm *localtime_r(const time_t *timep, struct tm *result);
time_t mktime(struct tm *tm);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

asctime_r(), ctime_r(), gmtime_r(), localtime_r():

_POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

ОПИСАНИЕ

Функции ctime(), gmtime() и localtime() в качестве аргумента используют тип данных time_t, представляющий собой календарное время. При его интерпретации как абсолютного времени, оно представляет количество секунд, прошедших с начала эпохи — 00:00:00 1 января 1970 +0000 (UTC).

Функции asctime() и mktime() используют в качестве аргумента время, которое разделено на компоненты: год, месяц, день и т. п.

Время в виде компонент хранится в структуре tm, которая определена в файле <time.h> следующим образом: 

struct tm {
    int tm_sec;    /* секунды (0-60) */
    int tm_min;    /* минуты (0-59) */
    int tm_hour;   /* часы (0-23) */
    int tm_mday;   /* день в месяце (1-31) */
    int tm_mon;    /* месяц (0-11) */
    int tm_year;   /* год - 1900 */
    int tm_wday;   /* день недели (0-6, воскресенье = 0) */
    int tm_yday;   /* день в году (0-365, 1 январь = 0) */
    int tm_isdst;  /* летнее время */
};

Члены структуры tm:

tm_sec
Количество секунд до целой минуты, обычно в диапазоне от 0 до 59; но для того, чтобы установить високосную секунду, используются числа до 60.
tm_min
Количество минут до целого часа, от 0 до 59.
tm_hour
Количество часов прошедших после полуночи, от 0 до 23.
tm_mday
День месяца, от 1 до 31.
tm_mon
Количество месяцев, прошедших с января, от 0 до 11.
tm_year
Количество лет, прошедших с 1900 года.
tm_wday
Количество дней, прошедших с воскресенья, от 0 до 6.
tm_yday
Количество дней, прошедших с 1 января, от 0 до 365.
tm_isdst
Этот флаг показывает, учтено ли летнее время в описываемой дате. Значение флага положительно, если летнее время учитывается, 0, если нет, и отрицательно, если информация недоступна.

Вызов ctime(t) эквивалентен asctime(localtime(t)). Он преобразует календарное время t в строку (с null в конце) вида

"Wed Jun 30 21:49:08 1993\n"

Аббревиатуры дней недели: «Sun», «Mon», «Tue», «Wed», «Thu», «Fri» и «Sat». Аббревиатуры месяцев: «Jan», «Feb», «Mar», «Apr», «May», «Jun», «Jul», «Aug», «Sep», «Oct», «Nov» и «Dec». Возвращаемое значение указывает на статически размещённую строку, которая может быть перезаписана последующими вызовами любых функций даты и времени. Функция также устанавливает в внешних переменных tzname, timezone и daylight (смотрите tzset(3)) текущий часовой пояс. Реентерабельная версия ctime_r() делает то же самое, но заносит строку в буфер, предоставляемый пользователем. Длина буфера должна быть не менее 26 байт. Ей не нужно устанавливать tzname, timezone и daylight.

Функция gmtime() преобразует календарное время timep в компонентное представление, выраженное в виде всеобщего скоординированного времени (UTC). Она может вернуть значение NULL, если год не может быть описан типом integer. Возвращаемое значение указывает на статически выделенную структуру, содержимое которой может быть перезаписано последующими вызовами любых функций, работающих с датой и временем. Функция gmtime_r() делает то же самое, но помещает данные в структуру, предоставленную пользователем.

Функция localtime() преобразует календарное время timep в компонентное представление, выраженное относительно часового пояса, заданного пользователем. Функция работает так, как-будто она вызывает tzset(3), и устанавливает внешние переменные: tzname в значение текущего часового пояса, timezone в значение разницы в секундах между всеобщим скоординированным временем (UTC) и локальным стандартом времени, и daylight в ненулевое значение, если действуют стандартные правила летнего времени. Возвращаемое значение указывает на статически выделенную структуру, содержимое которой может быть перезаписано последующими вызовами любых функций, работающих с датой и временем. Функция localtime_r() делает то же самое, но помещает данные в структуру, предоставленную пользователем. Она не нуждается в установке tzname, timezone и daylight.

Функция asctime() преобразует компонентное значение времени tm в строку (с null в конце) того же формата, что и функция ctime(). Возвращаемое значение указывает на статическую строку, которая может быть перезаписана последовательностью вызовов любых функций даты и времени. Функция asctime_r() делает то же самое, но заносит строку в буфер, предоставленный пользователем. Длина буфера должна быть не менее 26 байт.

Функция mktime() преобразует компонентное структурированное значение локального времени в календарное представление. Функция игнорирует содержимое полей структуры tm_wday и tm_yday, заданные вызывающим. Значение, указанное в поле tm_isdst, информирует mktime() о действии летнего время (DST) в времени в структуре tm: положительно значение показывает, что действует; 0 означает, что не действует и отрицательное значение означает, что mktime() должна попытаться определить самостоятельно, действует ли летнее время (используя информацию о часовом поясе и базы данных системы).

Функция mktime() изменяет поля структуры tm следующим образом: в tm_wday и tm_yday записываются значения, определённые на основе содержимого других полей; если члены структуры вне своих допустимых интервалов, то они будут нормализованы (так, например, 40 октября превращается в 9 ноября); в tm_isdst записывается положительное значение или 0, соответственно, для указания действия летнего времени (независимо от его начального значения). Вызов mktime() также присваивает внешней переменной tzname значение текущего часового пояса.

Если компонентное значение времени не может быть представлено как календарное (число секунд с начала эпохи), то mktime() возвращает значение (time_t) -1 и не изменяет значения полей структуры компонентного значения времени.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Все вышеперечисленные функции возвращают описанное значение или NULL (-1 в случае mktime()) при возникновении ошибки.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).
ИнтерфейсАтрибутЗначение
asctime() безвредность в нитяхнебезопасно (MT-Unsafe race:asctime locale)
asctime_r() безвредность в нитяхбезвредно (MT-Safe locale)
ctime() безвредность в нитях MT-Unsafe race:tmbuf
race:asctime env locale
ctime_r(), gmtime_r(), localtime_r(), mktime() безвредность в нитяхбезвредно (MT-Safe env locale)
gmtime(), localtime() безвредность в нитяхнебезопасно (MT-Unsafe race:tmbuf env locale)

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001. В C89 и C99 определены функции asctime(), ctime(), gmtime(), localtime() и mktime(). В POSIX.1-2008 функции asctime(), asctime_r(), ctime() и ctime_r() помечены как устаревшие. Вместо них рекомендуется использовать strftime(3).

ЗАМЕЧАНИЯ

Функции asctime(), ctime(), gmtime() и localtime() возвращают указатель на статические данные и небезопасны при использовании в нитях. Безопасными являются их аналоги asctime_r(), ctime_r(), gmtime_r() и localtime_r(), введённые в SUSv2.

В POSIX.1-2001 сказано: «Функции asctime(), ctime(), gmtime() и localtime() должны возвращать значения в одном из двух статических объектов: структуре компонентного значения времени и массиве типа char. Выполнение любой функции может перезаписать данные, возвращённые ранее любой другой функцией в любом из этих объектов.» Это может происходить в реализации glibc.

Во многих реализациях, включая glibc, 0 в tm_mday означает последний день предыдущего месяца.

Структура struct tm версии glibc имеет дополнительные поля 

long tm_gmtoff;           /* Секунды восточнее UTC */
const char *tm_zone;      /* Аббревиатура часового пояса */

определяемые в случае, если макрос _BSD_SOURCE был определён до включения <time.h>. Это расширение BSD, существует в 4.3BSD-Reno.

Согласно POSIX.1-2004, для localtime() требуется повторить поведение как если бы была вызвана tzset(3), хотя для localtime_r() такого требования не выдвигается. В целях переносимости в коде нужно вызывать tzset(3) перед localtime_r().

ПЕРЕВОДЫ

СМОТРИТЕ ТАКЖЕ

ПОСЛЕДНИЕ ЗАПРОСЫ