xref: /openbsd/share/man/man3/timeradd.3 (revision 76d0caae) 
1.\"	$OpenBSD: timeradd.3,v 1.3 2019/05/10 19:14:12 cheloha Exp $
2.\"	$NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc Exp $
3.\"
4.\" Copyright (c) 1983, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"     @(#)getitimer.2	8.2 (Berkeley) 12/11/93
32.\"
33.Dd $Mdocdate: May 10 2019 $
34.Dt TIMERADD 3
35.Os
36.Sh NAME
37.Nm timerclear ,
38.Nm timerisset ,
39.Nm timerisvalid ,
40.Nm timercmp ,
41.Nm timersub ,
42.Nm timeradd ,
43.Nm timespecclear ,
44.Nm timespecisset ,
45.Nm timespecisvalid ,
46.Nm timespeccmp ,
47.Nm timespecsub ,
48.Nm timespecadd ,
49.Nm TIMEVAL_TO_TIMESPEC ,
50.Nm TIMESPEC_TO_TIMEVAL
51.Nd manipulate time structures
52.Sh SYNOPSIS
53.In sys/time.h
54.Ft void
55.Fn timerclear "struct timeval *a"
56.Ft int
57.Fn timerisset "struct timeval *a"
58.Ft int
59.Fn timerisvalid "struct timeval *a"
60.Ft int
61.Fn timercmp "struct timeval *a" "struct timeval *b" operator
62.Ft void
63.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *c"
64.Ft void
65.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *c"
66.Ft void
67.Fn timespecclear "struct timespec *a"
68.Ft int
69.Fn timespecisset "struct timespec *a"
70.Ft int
71.Fn timespecisvalid "struct timespec *a"
72.Ft int
73.Fn timespeccmp "struct timespec *a" "struct timespec *b" operator
74.Ft void
75.Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *c"
76.Ft void
77.Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *c"
78.Ft void
79.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts"
80.Ft void
81.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts"
82.Sh DESCRIPTION
83The
84.Fn timer*
85and
86.Fn timespec*
87macros defined in
88.In sys/time.h
89simplify the use of
90.Vt timeval
91and
92.Vt timespec
93structures,
94respectively.
95.Pp
96The following macros are available:
97.Bl -tag -width Ds
98.It Fn timerclear a , Fn timespecclear a
99Set the time value in
100.Fa a
101to zero.
102.It Fn timerisset a , Fn timespecisset a
103Test if the time value in
104.Fa a
105is non-zero.
106.It Fn timerisvalid a
107Test if the microsecond value in
108.Fa a
109is greater than or equal to zero and less than one million.
110.It Fn timespecisvalid a
111Test if the nanosecond value in
112.Fa a
113is greater than or equal to zero and less than one billion.
114.It Fn timercmp a b operator , Fn timespeccmp a b operator
115Test if the expression
116.Fa a operator b
117is true,
118where
119.Fa operator
120is one of
121.Cm < ,
122.Cm <= ,
123.Cm == ,
124.Cm != ,
125.Cm >= ,
126or
127.Cm > .
128.It Fn timersub a b c , Fn timespecsub a b c
129Subtract
130.Fa b
131from
132.Fa a
133and store the result in
134.Fa c .
135.It Fn timeradd a b c , Fn timespecadd a b c
136Add
137.Fa b
138to
139.Fa a
140and store the result in
141.Fa c .
142.It Fn TIMEVAL_TO_TIMESPEC tv ts
143Convert
144.Fa tv
145to a
146.Vt struct timespec
147and store the result in
148.Fa ts .
149.It Fn TIMESPEC_TO_TIMEVAL tv ts
150Convert
151.Fa ts
152to a
153.Vt struct timeval
154and store the result in
155.Fa tv .
156.El
157.Sh RETURN VALUES
158The macros returning
159.Vt int
160return 1 if the tested condition holds or 0 otherwise.
161.Sh SEE ALSO
162.Xr adjtime 2 ,
163.Xr clock_gettime 2 ,
164.Xr futex 2 ,
165.Xr futimens 2 ,
166.Xr futimes 2 ,
167.Xr getitimer 2 ,
168.Xr gettimeofday 2 ,
169.Xr kevent 2 ,
170.Xr nanosleep 2 ,
171.Xr ppoll 2 ,
172.Xr pselect 2
173.Sh STANDARDS
174These macros are non-standard,
175though many systems offer them.
176Similar interfaces are often available in their absence.
177.Sh HISTORY
178The macros
179.Fn timerclear ,
180.Fn timerisset ,
181and
182.Fn timercmp
183first appeared in
184.Bx 4.1c ,
185.Fn TIMEVAL_TO_TIMESPEC
186and
187.Fn TIMESPEC_TO_TIMEVAL
188in
189.Bx 4.4 ,
190.Fn timersub
191and
192.Fn timeradd
193in
194.Nx 1.1 ,
195and
196.Fn timerisvalid
197in
198.Ox 6.5 .
199.Sh CAVEATS
200The argument ordering for
201.Fn TIMESPEC_TO_TIMEVAL
202is unintuitive.
203