Time Types (The GNU C Library)

### 22.2 Time Types ¶

ISO C and POSIX define several data types for representing elapsed times, simple calendar times, and broken-down times.

Data Type: clock_t ¶

  `clock_t` is used to measure processor and CPU time. It may be an integer or a floating-point type. Its values are counts of clock ticks since some arbitrary event in the past. The number of clock ticks per second is system-specific. See Processor And CPU Time, for further detail.

Data Type: time_t ¶

  `time_t` is the simplest data type used to represent simple calendar time.

  In ISO C, `time_t` can be either an integer or a real floating type, and the meaning of `time_t` values is not specified. The only things a strictly conforming program can do with `time_t` values are: pass them to `difftime` to get the elapsed time between two simple calendar times (see Calculating Elapsed Time), and pass them to the functions that convert them to broken-down time (see Broken-down Time).

  On POSIX-conformant systems, `time_t` is an integer type and its values represent the number of seconds elapsed since the POSIX Epoch, which is January 1, 1970, at 00:00:00 Coordinated Universal Time (UTC). The count of seconds ignores leap seconds. Additionally, POSIX.1-2024 added the requirement that `time_t` be at least 64 bits wide.

  The GNU C Library additionally guarantees that `time_t` is a signed type, and that all of its functions operate correctly on negative `time_t` values, which are interpreted as times before the POSIX Epoch. Functions like `localtime` assume the Gregorian calendar and UTC even though this is historically inaccurate for dates before 1582, for times before 1960, and for timestamps after the Gregorian calendar and UTC will become obsolete. The GNU C Library also supports leap seconds as an option, in which case `time_t` counts leap seconds instead of ignoring them. Currently the `time_t` type is 64 bits wide on all platforms supported by the GNU C Library, except that it is 32 bits wide on a few older platforms unless you define `_TIME_BITS` to 64. See Feature Test Macros.

Data Type: struct timespec ¶

  `struct timespec` represents a simple calendar time, or an elapsed time, with sub-second resolution. It is declared in `time.h` and has the following members:

  `time_t tv_sec`

    The number of whole seconds elapsed since the epoch (for a simple calendar time) or since some other starting point (for an elapsed time).

  `long int tv_nsec`

    The number of nanoseconds elapsed since the time given by the `tv_sec` member.

    When `struct timespec` values are produced by GNU C Library functions, the value in this field will always be greater than or equal to zero, and less than 1,000,000,000. When `struct timespec` values are supplied to GNU C Library functions, the value in this field must be in the same range.

Data Type: struct timeval ¶

  `struct timeval` is an older type for representing a simple calendar time, or an elapsed time, with sub-second resolution. It is almost the same as `struct timespec`, but provides only microsecond resolution. It is declared in `sys/time.h` and has the following members:

  `time_t tv_sec`

    The number of whole seconds elapsed since the epoch (for a simple calendar time) or since some other starting point (for an elapsed time).

  `long int tv_usec`

    The number of microseconds elapsed since the time given by the `tv_sec` member.

    When `struct timeval` values are produced by GNU C Library functions, the value in this field will always be greater than or equal to zero, and less than 1,000,000. When `struct timeval` values are supplied to GNU C Library functions, the value in this field must be in the same range.

Data Type: struct tm ¶

  This is the data type used to represent a broken-down time. It has separate fields for year, month, day, and so on. See Broken-down Time, for further details.