Linux API. Исчерпывающее руководство

10.2. Функции преобразования представлений времени

На рис. 10.1 показаны функции, используемые для преобразования между значениями типа time_t и другими форматами времени, включая его представления для устройств вывода информации. Эти функции ограждают нас от сложностей, привносимых в такие преобразования часовыми поясами, режимами летнего времени и тонкостями локализации. (Часовые пояса будут рассмотрены в разделе 10.3, а вопросы локали — в разделе 10.4.)

Рис. 10.1.Функции для извлечения календарного времени и работы с ним

10.2.1. Преобразование значений типа time_t к виду, подходящему для устройств вывода информации

Функция ctime() предоставляет простой метод преобразования значения типа time_t к виду, подходящему для устройств вывода информации.

#include

char *ctime(const time_t *timep);

Возвращает при успешном завершении указатель на статически размещенную строку, которая оканчивается символом новой строки и \0, или NULL при ошибке

При предоставлении в timep указателя в виде значения типа time_t функция ctime() возвращает 26-байтовую строку, содержащую, как показано в следующем примере, дату и время в стандартной форме:

Wed Jun 8 14:22:34 2011

Строка включает в себя завершающие элементы: символ новой строки и нулевой байт. При осуществлении преобразования функция ctime() автоматически учитывает местный часовой пояс и режим летнего времени. (Порядок определения этих настроек рассматривается в разделе 10.3.) Возвращаемая строка будет статически размещенной; последующие вызовы ctime() станут ее перезаписывать.

В SUSv3 утверждается, что вызовы любой из функций — ctime(), gmtime(), localtime() или asctime() — могут перезаписать статически размещенную структуру значениями, возвращенными другими функциями. Иными словами, эти функции могут совместно использовать копии возвращенных массивов из символов и структуру tm, что и делается в некоторых версиях glibc. Если нужно работать с возвращенной информацией в ходе нескольких вызовов этих функций, следует сохранять локальные копии.

Реентерабельная версия ctime() предоставляется в виде ctime_r(). (Реентерабельность рассматривается в подразделе 21.1.2.) Эта функция позволяет вызывающему коду задать дополнительный аргумент — указатель на предоставляемый этим кодом буфер для возвращения строки с данными времени. Другие реентерабельные версии функций, упоминаемые в данной главе, ведут себя точно так же.

10.2.2. Преобразования между time_t и разделенным календарным временем

Функции gmtime() и localtime() преобразуют значение типа time_t в так называемое broken-down time, разделенное календарное время (или время, разбитое на компоненты). Это время помещается в статически размещаемую структуру, чей адрес возвращается в качестве результата выполнения функции.

#include

struct tm *gmtime(const time_t *timep);

struct tm *localtime(const time_t *timep);

Обе функции при успешном завершении возвращают указатель на статически размещаемую структуру разделенного календарного времени, а при ошибке — NULL

Функция gmtime() выполняет преобразование календарного времени в разделенное время, соответствующее UTC. (Буквы gm происходят от понятия Greenwich Mean Time.) Напротив, функция localtime() учитывает настройки часового пояса и режима летнего времени, чтобы возвратить разбитое на компоненты время, соответствующее местному системному времени.

Реентерабельные версии этих функций предоставляются в виде gmtime_r() и localtime_r().

Структура tm, возвращаемая этими функциями, содержит поля даты и времени, разбитые на отдельные части. Она имеет следующий вид:

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)*/

int tm_yday; /* День в году (0–365; 1 января = 0)*/

int tm_isdst; /* Флаг летнего времени

> 0: летнее время действует;

= 0: летнее время не действует;

< 0: информация о летнем времени недоступна */

};

Поле tm_sec может быть расширено до 60 (а не до 59), чтобы учитывать корректировочные секунды, применяемые для правки актуального для человечества календаря под астрономически точный (так называемый тропический) год.