asctime, ctime, gmtime, localtime, mktime - преобразует дату и время в формат ASCII или в календарное представление

НАЗВАНИЕ
asctime, ctime, gmtime, localtime, mktime - преобразует
дату и время в формат ASCII или в календарное
представление

СИНТАКСИС
#include

char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *tm, char *buf);
char *ctime_r(const time_t *timep, char *buf);

char *ctime(const time_t *timep);

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);

ОПИСАНИЕ
Функции ctime(), gmtime() и localtime() в качестве
агрумента используют тип данных time_t , представляющий
собой календарное время. Функции интерпретируют его как
абсолютное время, содержащее количество секунд, прошедших
с 00:00:00 1 января 1970 года времени UTC.

Функции asctime() и mktime() используют в качестве
аргумента локальное время в календарном представлении, то
есть разделеное на год, месяц, день и т.д. Время в
календарном представлении хранится в структуре tm, которая
определена в файле следующим образом:

struct tm {
int tm_sec; /* секунды */
int tm_min; /* минуты */
int tm_hour; /* часы */
int tm_mday; /* день месяца */
int tm_mon; /* месяц */
int tm_year; /* год */
int tm_wday; /* день недели */
int tm_yday; /* день года */
int tm_isdst; /* летнее время */
};

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

tm_sec Число секунд, прошедших после минуты, обычно в
диапазоне от нуля до 59-и; но для того, чтобы
установить високосную секунду, используются числа
до 61-ого.

tm_min Число минут, прошедших после часа, от нуля до 59-и.

tm_hour
Количество прошедших часов после полуночи, от нуля
до 23-х.

tm_mday
День месяца, от единицы до 31-ого.

tm_mon Число месяцев, прошедших с января, от нуля до 11-и.

tm_year
Число лет, прошедших с 1900.

tm_wday
Число дней, прошедших с воскресенья, от нуля до
6-и.

tm_yday
Количество дней, прошедших с 1 января, от нуля до
365-и.

tm_isdst
Этот флаг показывает, в действительности ли
"летнее" время учтено в этой структуре. Значение
флага положительно, если "летнее" время
учитывается, 0, если нет, и отрицательно, если
информация недоступна.

Функция ctime(t) является эквивалентом asctime(local-
time(t)). Она преобразует календарное время t в строку
формата

"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 (см. tzset(3)) равным
значению текущей временной зоны. Реентрантная версия
ctime_r() делает то же самое, но заносит строку в буфер,
предоставляемый пользователем. Длина буфера должна быть не
менее 26 байт. Устанавливать tzname необязательно.

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

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

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

Функция mktime() преобразует время в календарном
представлении в абсолютное время. Функция игнорирует
содержимое полей структуры tm_wday и tm_yday и
пересчитывает их значения в соответствии с другими
элементами структуры. Если значения элементов структуры
выходят за пределы допустимых значений, то они
"нормализуются" (так, например, 40 октября превращается в
9 ноября). Вызов mktime() также присваивает внешней
переменной tzname значение текущей временной зоны. Если
локальное время не может быть представлено как календарное
(число секунд с начала века), то mktime() возвращает
значение (time_t)(-1) и не изменяет значения членов
структуры локального времени tm_wday и tm_yday.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Все вышеперечисленные функции возвращают описанное
значение или NULL (-1 в случае mktime()) при возникновении
ошибки.

ЗАМЕЧАНИЯ
Функции asctime(), ctime(), gmtime() и localtime()
возвращают указатели на статические данные и небезопасны с
точки зрения подпроцессов (threads). Безопасными являются
их аналоги asctime_r(), ctime_r(), gmtime_r() и local-
time_r(), введенные в SUSv2 и повившееся в libc 5.2.5.

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

long tm_gmtoff; /* Секунды восточнее UTC */
const char *tm_tm_zone; /* Аббревиатура временной зоны */

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

СООТВЕТСТВИЕ СТАНДАРТАМ
SVID 3, POSIX, BSD 4.3, ISO 9899