ИМЯ

gettimeofday, settimeofday - получает/устанавливает время

ОБЗОР

#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(): начиная с glibc 2.19: _DEFAULT_SOURCE в glibc 2.19 и старее: _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: (settimeofday()): неверное значение timezone.
EINVAL: (settimeofday()): tv.tv_sec отрицательно или tv.tv_usec вне диапазона [0..999,999].
EINVAL (начиная с Linux 4.3): (settimeofday()): выполнялась попытка установки времени в значение меньше текущего значения часов CLOCK_MONOTONIC (смотрите clock_gettime(2)).
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.

Отличия между библиотекой C и ядром

На некоторых архитектурах реализация gettimeofday() находится в vdso(7).

Поле 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 */
DST_AUST     /* австралийский DST */
DST_WET      /* западноевропейский DST */
DST_MET      /* средневосточный DST */
DST_EET      /* восточноевропейский DST */
DST_CAN      /* Канада */
DST_GB       /* Великобритания и Ирландия */
DST_RUM      /* Румыния */
DST_TUR      /* Турция */
DST_AUSTALT  /* австралийский со сдвигом на 1986 год */

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

ИМЯ