xref: /freebsd/share/man/man3/timeradd.3 (revision 91c6231246b587209e585376c15553f574b17463)
1e5606f14SDoug White.\" Copyright (c) 1999 Kelly Yancey <kbyanc@posi.net>
2e5606f14SDoug White.\" All rights reserved.
3e5606f14SDoug White.\"
4e5606f14SDoug White.\" Redistribution and use in source and binary forms, with or without
5e5606f14SDoug White.\" modification, are permitted provided that the following conditions
6e5606f14SDoug White.\" are met:
7e5606f14SDoug White.\" 1. Redistributions of source code must retain the above copyright
8e5606f14SDoug White.\"    notice, this list of conditions and the following disclaimer.
9e5606f14SDoug White.\" 2. Redistributions in binary form must reproduce the above copyright
10e5606f14SDoug White.\"    notice, this list of conditions and the following disclaimer in the
11e5606f14SDoug White.\"    documentation and/or other materials provided with the distribution.
12e5606f14SDoug White.\" 3. Neither the name of the author nor the names of any co-contributors
13e5606f14SDoug White.\"    may be used to endorse or promote products derived from this software
14e5606f14SDoug White.\"    without specific prior written permission.
15e5606f14SDoug White.\"
16e5606f14SDoug White.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
17e5606f14SDoug White.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18e5606f14SDoug White.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19e5606f14SDoug White.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20e5606f14SDoug White.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21e5606f14SDoug White.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22e5606f14SDoug White.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23e5606f14SDoug White.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24e5606f14SDoug White.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25e5606f14SDoug White.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26e5606f14SDoug White.\" SUCH DAMAGE.
27e5606f14SDoug White.\"
286040822cSAlan Somers.Dd July 30, 2018
29e5606f14SDoug White.Dt TIMERADD 3
30241c7610SRuslan Ermilov.Os
31e5606f14SDoug White.Sh NAME
32e5606f14SDoug White.Nm timeradd ,
33e5606f14SDoug White.Nm timersub ,
34e5606f14SDoug White.Nm timerclear ,
35e5606f14SDoug White.Nm timerisset ,
366040822cSAlan Somers.Nm timercmp ,
376040822cSAlan Somers.Nm timespecadd ,
386040822cSAlan Somers.Nm timespecsub ,
396040822cSAlan Somers.Nm timespecclear ,
406040822cSAlan Somers.Nm timespecisset ,
416040822cSAlan Somers.Nm timespeccmp
426040822cSAlan Somers.Nd operations on timevals and timespecs
43e5606f14SDoug White.Sh SYNOPSIS
44241c7610SRuslan Ermilov.In sys/time.h
45241c7610SRuslan Ermilov.Ft void
46241c7610SRuslan Ermilov.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res"
47241c7610SRuslan Ermilov.Ft void
48241c7610SRuslan Ermilov.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res"
49241c7610SRuslan Ermilov.Ft void
50241c7610SRuslan Ermilov.Fn timerclear "struct timeval *tvp"
51241c7610SRuslan Ermilov.Ft int
52241c7610SRuslan Ermilov.Fn timerisset "struct timeval *tvp"
53241c7610SRuslan Ermilov.Ft int
54241c7610SRuslan Ermilov.Fn timercmp "struct timeval *a" "struct timeval *b" CMP
556040822cSAlan Somers.Ft void
566040822cSAlan Somers.Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res"
576040822cSAlan Somers.Ft void
586040822cSAlan Somers.Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res"
596040822cSAlan Somers.Ft void
606040822cSAlan Somers.Fn timespecclear "struct timespec *ts"
616040822cSAlan Somers.Ft int
626040822cSAlan Somers.Fn timespecisset "struct timespec *ts"
636040822cSAlan Somers.Ft int
646040822cSAlan Somers.Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP
65e5606f14SDoug White.Sh DESCRIPTION
66e5606f14SDoug WhiteThese macros are provided for manipulating
67e5606f14SDoug White.Fa timeval
686040822cSAlan Somersand
696040822cSAlan Somers.Fa timespec
70e5606f14SDoug Whitestructures for use with the
716040822cSAlan Somers.Xr clock_gettime 2 ,
726040822cSAlan Somers.Xr clock_settime 2 ,
73241c7610SRuslan Ermilov.Xr gettimeofday 2
74e5606f14SDoug Whiteand
75241c7610SRuslan Ermilov.Xr settimeofday 2
76e5606f14SDoug Whitecalls.
776040822cSAlan SomersThe
786040822cSAlan Somers.Fa timeval
796040822cSAlan Somersstructure is defined in
80fe08efe6SRuslan Ermilov.In sys/time.h
81e5606f14SDoug Whiteas:
82e5606f14SDoug White.Bd -literal
83e5606f14SDoug Whitestruct timeval {
84e5606f14SDoug White	long	tv_sec;		/* seconds since Jan. 1, 1970 */
85e5606f14SDoug White	long	tv_usec;	/* and microseconds */
86e5606f14SDoug White};
87e5606f14SDoug White.Ed
88*91c62312SJohn Baldwin.Pp
896040822cSAlan SomersAnd the
906040822cSAlan Somers.Fa timespec
916040822cSAlan Somersstructure is defined in
926040822cSAlan Somers.In time.h
936040822cSAlan Somersas:
946040822cSAlan Somers.Bd -literal
956040822cSAlan Somersstruct timespec {
96a51c7dc5SMark Johnston	time_t tv_sec;		/* seconds */
976040822cSAlan Somers	long   tv_nsec;		/* and nanoseconds */
986040822cSAlan Somers};
996040822cSAlan Somers.Ed
100e5606f14SDoug White.Pp
101e5606f14SDoug White.Fn timeradd
1026040822cSAlan Somersand
1036040822cSAlan Somers.Fn timespecadd
1046040822cSAlan Somersadd the time information stored in
105241c7610SRuslan Ermilov.Fa a
106e5606f14SDoug Whiteto
107241c7610SRuslan Ermilov.Fa b
1086040822cSAlan Somersand store the result in
109241c7610SRuslan Ermilov.Fa res .
110e5606f14SDoug WhiteThe results are simplified such that the value of
111241c7610SRuslan Ermilov.Fa res->tv_usec
1126040822cSAlan Somersor
1136040822cSAlan Somers.Fa res->tv_nsec
1146040822cSAlan Somersis always less than 1 second.
115e5606f14SDoug White.Pp
116e5606f14SDoug White.Fn timersub
1176040822cSAlan Somersand
1186040822cSAlan Somers.Fn timespecsub
1196040822cSAlan Somerssubtract the time information stored in
120241c7610SRuslan Ermilov.Fa b
121e5606f14SDoug Whitefrom
122241c7610SRuslan Ermilov.Fa a
1236040822cSAlan Somersand store the result
124e5606f14SDoug Whitein
125241c7610SRuslan Ermilov.Fa res .
126e5606f14SDoug White.Pp
127e5606f14SDoug White.Fn timerclear
1286040822cSAlan Somersand
1296040822cSAlan Somers.Fn timespecclear
1306040822cSAlan Somersinitialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch).
131e5606f14SDoug White.Pp
132e5606f14SDoug White.Fn timerisset
1336040822cSAlan Somersand
1346040822cSAlan Somers.Fn timespecisset
1356040822cSAlan Somersreturn true if their argument is set to any time value other than the Epoch.
136e5606f14SDoug White.Pp
137e5606f14SDoug White.Fn timercmp
1386040822cSAlan Somersand
1396040822cSAlan Somers.Fn timespeccmp
1406040822cSAlan Somerscompare
141241c7610SRuslan Ermilov.Fa a
142e5606f14SDoug Whiteto
143241c7610SRuslan Ermilov.Fa b
144e5606f14SDoug Whiteusing the comparison operator given in
145241c7610SRuslan Ermilov.Fa CMP ,
1466040822cSAlan Somersand return the result of that comparison.
147e5606f14SDoug White.Sh SEE ALSO
14855ed6718SBenedict Reuschling.Xr clock_gettime 2 ,
14955ed6718SBenedict Reuschling.Xr gettimeofday 2
150e5606f14SDoug White.Sh HISTORY
151e5606f14SDoug WhiteThe
152e5606f14SDoug White.Fn timeradd
153e5606f14SDoug Whitefamily of macros were imported from
154e5606f14SDoug White.Nx 1.1 ,
155e5606f14SDoug Whiteand appeared in
156e5606f14SDoug White.Fx 2.2.6 .
1576040822cSAlan SomersThe
1586040822cSAlan Somers.Fn timespecadd
1596040822cSAlan Somersfamily of macros were imported from
1606040822cSAlan Somers.Nx 1.3
1616040822cSAlan Somersinto
1626040822cSAlan Somers.Fx 3.0 ,
1636040822cSAlan Somersthough they were not exposed to userland until
1646040822cSAlan Somers.Fx 12.0 .
165