settimeofday(2) получает/устанавливает время

Other Alias

gettimeofday

ОБЗОР

#include <sys/time.h>
int gettimeofday(struct timeval *tv, struct timezone *tz);
int settimeofday(const struct timeval *tv, const struct timezone *tz);

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

settimeofday(): _BSD_SOURCE

ОПИСАНИЕ

Функция gettimeofday() и settimeofday() позволяют получить и задать время, а также часовой пояс. Аргумент tv имеет тип struct timeval (определён в <sys/time.h>):

struct timeval {
    time_t      tv_sec;     /* секунды */
    suseconds_t tv_usec;    /* микросекунды */
};

и задаёт количество секунд и микросекунд, прошедших с начала эпохи (см. time(2)). Аргумент tz имеет тип struct timezone:

struct timezone {
    int tz_minuteswest;     /* количество минут западнее Гринвича */
    int tz_dsttime;         /* тип корректировки DST */
};

Если tv или tz имеют значение NULL, то соответствующая структура не задана и не будет возвращена (однако при компиляции будут выдаваться предупреждения, если tv равно NULL).

Пользоваться структурой timezone не рекомендуется; значением аргумента tz в большинстве случаев должен быть NULL (см. ЗАМЕЧАНИЯ далее).

В Linux существует специфическое понятие «временной сдвиг» (warp clock), связанное с системным вызовом settimeofday(), который образуется при самом первом вызове (после загрузки), если аргумент tz не равен NULL, аргумент tv равен NULL и поле tz_minuteswest не равно нулю (в этом случае значение поля tz_dsttime должно быть равно нулю). В этом случае предполагается, что время аппаратных часов (CMOS clock) местное и к нему должен быть добавлен этот параметр для того, чтобы получилось время UTC. Но, как мы и говорили, использовать этот метод не рекомендуется.

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

При успешном выполнении gettimeofday() и settimeofday() возвращают 0, или -1 в случае ошибки (errno устанавливается в соответствующее значение).

ОШИБКИ

EFAULT
Одно из значений в tv или tz находится вне доступного адресного пространства.
EINVAL
Неправильный часовой пояс (или что-то ещё).
EPERM
У вызывающего процесса недостаточно прав для вызова settimeofday(); в Linux для этого требуется мандат CAP_SYS_TIME.

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

SVr4, 4.3BSD. В POSIX.1-2001 описан gettimeofday(), но нет settimeofday(). В POSIX.1-2008 вызов gettimeofday() помечен как устаревший, вместо него рекомендуется использовать clock_gettime(2).

ЗАМЕЧАНИЯ

На время, возвращаемое gettimeofday(), влияют скачки в системном времени (например, если системный администратор вручную изменил системное время). Если вам требуются однообразно увеличивающееся время, смотрите clock_gettime(2).

Для работы со структурой timeval существуют макросы, описанные в timeradd(3).

Обычно, поля struct timeval имеют тип long.

Поле tz_dsttime

В системах с не ядрами Linux, но с glibc, полю tz_dsttime из struct timezone вызов gettimeofday() присвоит ненулевое значение, если в текущем часовом поясе уже применялось или будет применяться правило перехода на летнее время. В этом смысле это зеркально отражает назначение daylight(3) для текущего пояса. В Linux с glibc значение поля tz_dsttime из struct timezone никогда не используется в settimeofday() или gettimeofday(). Таким образом, следующий абзац представляет только исторический интерес.

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


DST_NONE     /* без коррекции (без DST) */

DST_USA /* коррекция для США */
DST_AUST /* коррекция для Австралии */
DST_WET /* коррекция для Западной Европы */
DST_MET /* коррекция для Центральной Европы */
DST_EET /* коррекция для Восточной Европы */
DST_CAN /* коррекция для Канады */
DST_GB /* коррекция для Великобритании и Ирландии */
DST_RUM /* коррекция для Румынии */
DST_TUR /* коррекция для Турции */
DST_AUSTALT /* коррекция для Австралии начиная с 1986 года */

Разумеется, коррекцию для каждой страны нельзя описать простым алгоритмом, так как этот фактор может зависеть даже от непредсказуемых политических решений. Поэтому этот метод представления часовых поясов больше не используется.