ctime(3)

ИМЯ
asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r - преобразует дату и время в раздельном представлении или ASCII

LIBRARY
Standard C library (libc, -lc)

СИНТАКСИС
#include <time.h>

char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *restrict tm,
                    char buf[restrict 26]);

char *ctime(const time_t *timep);
char *ctime_r(const time_t *restrict timep,
                    char buf[restrict 26]);

struct tm *gmtime(const time_t *timep);
struct tm *gmtime_r(const time_t *restrict timep,
                    struct tm *restrict result);

struct tm *localtime(const time_t *timep);
struct tm *localtime_r(const time_t *restrict timep,
                    struct tm *restrict result);

time_t mktime(struct tm *tm);

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

asctime_r(), ctime_r(), gmtime_r(), localtime_r():
    _POSIX_C_SOURCE
        || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

ОПИСАНИЕ
The ctime(), gmtime(), and localtime() functions all take an argument of data type time_t, which represents calendar time. When interpreted as an absolute time value, it represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

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

Broken-down time is stored in the structure tm, described in tm(3type).

Вызов 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 и не изменяет значения полей структуры компонентного значения времени.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении функции gmtime() и localtime() возвращают указатель на struct tm.

При успешном выполнении функции gmtime_r() и localtime_r() возвращают адрес структуры, на которую указывает result.

При успешном выполнении функции asctime() и ctime() возвращают указатель на строку.

При успешном выполнении функции asctime_r() и ctime_r() возвращают указатель на строку, на которую указывает buf.

При успешном выполнении функция mktime() возвращает календарное время (секунды с начала эпохи), выраженное значением с типом time_t.

On error, mktime() returns the value (time_t) -1. The remaining functions return NULL on error. On error, errno is set to indicate the error.

ОШИБКИ

EOVERFLOW
    Результат не может быть представлен.

АТРИБУТЫ
Описание терминов данного раздела смотрите в 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).

POSIX doesn't specify the parameters of ctime_r() to be restrict; that is specific to glibc.

ЗАМЕЧАНИЯ
The four functions asctime(), ctime(), gmtime(), and localtime() return a pointer to static data and hence are not thread-safe. The thread-safe versions, asctime_r(), ctime_r(), gmtime_r(), and localtime_r(), are specified by SUSv2.

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

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

According to POSIX.1-2001, localtime() is required to behave as though tzset(3) was called, while localtime_r() does not have this requirement. For portable code, tzset(3) should be called before localtime_r().

СМ. ТАКЖЕ
date(1), gettimeofday(2), time(2), utime(2), clock(3), difftime(3), strftime(3), strptime(3), timegm(3), tzset(3), time(7)

ПЕРЕВОД
Русский перевод этой страницы руководства был сделан Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Katrin Kutepova <blackkatelv@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 (https://www.gnu.org/licenses/gpl-3.0.html) или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.