Debian Codegraph @

upstream/debian-unstable/man3/timeradd.3

raw
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)