timeval

Timeval is a data structure used in Unix-like operating systems to represent a time value or interval with second and microsecond precision. It is commonly defined as a struct containing two fields: tv_sec and tv_usec. The tv_sec field stores the number of seconds since the Unix epoch (midnight UTC on 1 January 1970), while tv_usec holds the microsecond portion within the current second. The exact underlying types can vary by platform (for example, time_t for tv_sec and suseconds_t or long for tv_usec).

Timeval is defined in the system header <sys/time.h> and is used by several interfaces. The gettimeofday function fills a timeval with the current time of day. The setitimer function uses a timeval to specify intervals. The select and pselect system calls accept a timeout specified as a timeval to determine how long they should wait for I/O events. Some systems also provide macros for arithmetic on timevals, such as adding or subtracting two values.

Relation to other time representations: Timespec is a related structure that stores time as tv_sec and tv_nsec (nanoseconds) for higher precision. Converting between timeval and timespec is common when higher resolution timing is required or when interfacing with APIs that use different representations.

Portability and notes: Timeval has a long-standing POSIX heritage and is available on most Unix-like systems. Windows provides similar functionality in the Winsock API for socket timeouts; standard C libraries on Windows may not expose gettimeofday, though equivalents exist in some environments. For modern high-resolution timing, timespec and clock_gettime are often preferred, with timeval used in legacy code and certain BSD-derived interfaces.