| 1 |
.\" Copyright 2007, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH timeradd 3 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <sys/time.h> |
| 15 |
.P |
| 16 |
.BI "void timeradd(struct timeval *" a ", struct timeval *" b , |
| 17 |
.BI " struct timeval *" res ); |
| 18 |
.BI "void timersub(struct timeval *" a ", struct timeval *" b , |
| 19 |
.BI " struct timeval *" res ); |
| 20 |
.P |
| 21 |
.BI "void timerclear(struct timeval *" tvp ); |
| 22 |
.BI "int timerisset(struct timeval *" tvp ); |
| 23 |
.P |
| 24 |
.BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP ); |
| 25 |
.fi |
| 26 |
.P |
| 27 |
.RS -4 |
| 28 |
Feature Test Macro Requirements for glibc (see |
| 29 |
.BR feature_test_macros (7)): |
| 30 |
.RE |
| 31 |
.P |
| 32 |
All functions shown above: |
| 33 |
.nf |
| 34 |
Since glibc 2.19: |
| 35 |
_DEFAULT_SOURCE |
| 36 |
glibc 2.19 and earlier: |
| 37 |
_BSD_SOURCE |
| 38 |
.fi |
| 39 |
.SH DESCRIPTION |
| 40 |
The macros are provided to operate on |
| 41 |
.I timeval |
| 42 |
structures, defined in |
| 43 |
.I <sys/time.h> |
| 44 |
as: |
| 45 |
.P |
| 46 |
.in +4n |
| 47 |
.EX |
| 48 |
struct timeval { |
| 49 |
time_t tv_sec; /* seconds */ |
| 50 |
suseconds_t tv_usec; /* microseconds */ |
| 51 |
}; |
| 52 |
.EE |
| 53 |
.in |
| 54 |
.P |
| 55 |
.BR timeradd () |
| 56 |
adds the time values in |
| 57 |
.I a |
| 58 |
and |
| 59 |
.IR b , |
| 60 |
and places the sum in the |
| 61 |
.I timeval |
| 62 |
pointed to by |
| 63 |
.IR res . |
| 64 |
The result is normalized such that |
| 65 |
.I res\->tv_usec |
| 66 |
has a value in the range 0 to 999,999. |
| 67 |
.P |
| 68 |
.BR timersub () |
| 69 |
subtracts the time value in |
| 70 |
.I b |
| 71 |
from the time value in |
| 72 |
.IR a , |
| 73 |
and places the result in the |
| 74 |
.I timeval |
| 75 |
pointed to by |
| 76 |
.IR res . |
| 77 |
The result is normalized such that |
| 78 |
.I res\->tv_usec |
| 79 |
has a value in the range 0 to 999,999. |
| 80 |
.P |
| 81 |
.BR timerclear () |
| 82 |
zeros out the |
| 83 |
.I timeval |
| 84 |
structure pointed to by |
| 85 |
.IR tvp , |
| 86 |
so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC). |
| 87 |
.P |
| 88 |
.BR timerisset () |
| 89 |
returns true (nonzero) if either field of the |
| 90 |
.I timeval |
| 91 |
structure pointed to by |
| 92 |
.I tvp |
| 93 |
contains a nonzero value. |
| 94 |
.P |
| 95 |
.BR timercmp () |
| 96 |
compares the timer values in |
| 97 |
.I a |
| 98 |
and |
| 99 |
.I b |
| 100 |
using the comparison operator |
| 101 |
.IR CMP , |
| 102 |
and returns true (nonzero) or false (0) depending on |
| 103 |
the result of the comparison. |
| 104 |
Some systems (but not Linux/glibc), |
| 105 |
have a broken |
| 106 |
.BR timercmp () |
| 107 |
implementation, |
| 108 |
.\" HP-UX, Tru64, Irix have a definition like: |
| 109 |
.\"#define timercmp(tvp, uvp, cmp) \ |
| 110 |
.\" ((tvp)->tv_sec cmp (uvp)->tv_sec || \ |
| 111 |
.\" (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec) |
| 112 |
in which |
| 113 |
.I CMP |
| 114 |
of |
| 115 |
.IR >= , |
| 116 |
.IR <= , |
| 117 |
and |
| 118 |
.I == |
| 119 |
do not work; |
| 120 |
portable applications can instead use |
| 121 |
.P |
| 122 |
.in +4n |
| 123 |
.EX |
| 124 |
!timercmp(..., <) |
| 125 |
!timercmp(..., >) |
| 126 |
!timercmp(..., !=) |
| 127 |
.EE |
| 128 |
.in |
| 129 |
.SH RETURN VALUE |
| 130 |
.BR timerisset () |
| 131 |
and |
| 132 |
.BR timercmp () |
| 133 |
return true (nonzero) or false (0). |
| 134 |
.SH ERRORS |
| 135 |
No errors are defined. |
| 136 |
.SH STANDARDS |
| 137 |
None. |
| 138 |
.SH HISTORY |
| 139 |
BSD. |
| 140 |
.SH SEE ALSO |
| 141 |
.BR gettimeofday (2), |
| 142 |
.BR time (7) |