TIMEVAL(3)Library Functions ManualTIMEVAL(3)
NAME
timeval, timespec, itimerval, itimerspec, bintime — time structures
SYNOPSIS
#include <sys/time.h>
void TIMEVAL_TO_TIMESPEC(struct timeval *tv, struct timespec *ts);
void TIMESPEC_TO_TIMEVAL(struct timeval *tv, struct timespec *ts);
DESCRIPTION
The <sys/time.h> header, included by <time.h>, defines various structures related to time and timers.
- The following structure is used by
gettimeofday(2)
, among others: struct timeval { time_t tv_sec; suseconds_t tv_usec; }; The tv_sec member represents the elapsed time, in whole seconds. The tv_usec member captures rest of the elapsed time, represented as the number of microseconds. - The following structure is used by
nanosleep(2)
, among others: struct timespec { time_t tv_sec; long tv_nsec; }; The tv_sec member is again the elapsed time in whole seconds. The tv_nsec member represents the rest of the elapsed time in nanoseconds. A microsecond is equal to one millionth of a second, 1000 nanoseconds, or 1/1000 milliseconds. To ease the conversions, the macros TIMEVAL_TO_TIMESPEC() and TIMESPEC_TO_TIMEVAL() can be used to convert between struct timeval and struct timespec. - The following structure is used by
setitimer(2)
, among others: struct itimerval { struct timeval it_interval; struct timeval it_value; }; - The following structure is used by
timer_settime(2)
, among others: struct itimerspec { struct timespec it_interval; struct timespec it_value; }; Both struct itimerval and struct itimerspec are used to specify when a timer expires. Generally, it_interval specifies the period between successive timer expirations. A value zero implies that the alarm will fire only once. If it_value is non-zero, it indicates the time left to the next timer expiration. A value zero implies that the timer is disabled. - The following structure is used by
bintime(9)
, among others: struct bintime { time_t sec; uint64_t frac; }; The sec member specifies the time in seconds and frac represents a 64-bit fraction of seconds. The structbintime is meant to be used in the kernel only. It is further described intimecounter(9)
.
EXAMPLES
It can be stressed that the traditional UNIX timeval and timespec structures represent elapsed time, measured by the system clock (see hz(9)
). The following sketch implements a function suitable for use in a context where the timespec structure is required for a conditional timeout:
static void example(struct timespec *spec, time_t minutes) { struct timeval elapsed; (void)gettimeofday(&elapsed, NULL); _DIAGASSERT(spec != NULL); TIMEVAL_TO_TIMESPEC(&elapsed, spec); /* Add the offset for timeout in minutes. */ spec->tv_sec = spec->tv_sec + minutes * 60; }
A better alternative would use the more precise clock_gettime(2)
.
SEE ALSO
NetBSDApril 12, 2011NetBSD