share/man/man3/timeradd.3

   1 .\" Copyright (c) 1999 Kelly Yancey <kbyanc@posi.net>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the author nor the names of any co-contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd July 30, 2018
  31 .Dt TIMERADD 3
  32 .Os
  33 .Sh NAME
  34 .Nm timeradd ,
  35 .Nm timersub ,
  36 .Nm timerclear ,
  37 .Nm timerisset ,
  38 .Nm timercmp ,
  39 .Nm timespecadd ,
  40 .Nm timespecsub ,
  41 .Nm timespecclear ,
  42 .Nm timespecisset ,
  43 .Nm timespeccmp
  44 .Nd operations on timevals and timespecs
  45 .Sh SYNOPSIS
  46 .In sys/time.h
  47 .Ft void
  48 .Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res"
  49 .Ft void
  50 .Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res"
  51 .Ft void
  52 .Fn timerclear "struct timeval *tvp"
  53 .Ft int
  54 .Fn timerisset "struct timeval *tvp"
  55 .Ft int
  56 .Fn timercmp "struct timeval *a" "struct timeval *b" CMP
  57 .Ft void
  58 .Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res"
  59 .Ft void
  60 .Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res"
  61 .Ft void
  62 .Fn timespecclear "struct timespec *ts"
  63 .Ft int
  64 .Fn timespecisset "struct timespec *ts"
  65 .Ft int
  66 .Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP
  67 .Sh DESCRIPTION
  68 These macros are provided for manipulating
  69 .Fa timeval
  70 and
  71 .Fa timespec
  72 structures for use with the
  73 .Xr clock_gettime 2 ,
  74 .Xr clock_settime 2 ,
  75 .Xr gettimeofday 2
  76 and
  77 .Xr settimeofday 2
  78 calls.
  79 The
  80 .Fa timeval
  81 structure is defined in
  82 .In sys/time.h
  83 as:
  84 .Bd -literal
  85 struct timeval {
  86         long    tv_sec;         /* seconds since Jan. 1, 1970 */
  87         long    tv_usec;        /* and microseconds */
  88 };
  89 .Ed
  90 And the
  91 .Fa timespec
  92 structure is defined in
  93 .In time.h
  94 as:
  95 .Bd -literal
  96 struct timespec {
  97         time_t tv_sec;          /* seconds */
  98         long   tv_nsec;         /* and nanoseconds */
  99 };
 100 .Ed
 101 .Pp
 102 .Fn timeradd
 103 and
 104 .Fn timespecadd
 105 add the time information stored in
 106 .Fa a
 107 to
 108 .Fa b
 109 and store the result in
 110 .Fa res .
 111 The results are simplified such that the value of
 112 .Fa res->tv_usec
 113 or
 114 .Fa res->tv_nsec
 115 is always less than 1 second.
 116 .Pp
 117 .Fn timersub
 118 and
 119 .Fn timespecsub
 120 subtract the time information stored in
 121 .Fa b
 122 from
 123 .Fa a
 124 and store the result
 125 in
 126 .Fa res .
 127 .Pp
 128 .Fn timerclear
 129 and
 130 .Fn timespecclear
 131 initialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch).
 132 .Pp
 133 .Fn timerisset
 134 and
 135 .Fn timespecisset
 136 return true if their argument is set to any time value other than the Epoch.
 137 .Pp
 138 .Fn timercmp
 139 and
 140 .Fn timespeccmp
 141 compare
 142 .Fa a
 143 to
 144 .Fa b
 145 using the comparison operator given in
 146 .Fa CMP ,
 147 and return the result of that comparison.
 148 .Sh SEE ALSO
 149 .Xr clock_gettime 2 ,
 150 .Xr gettimeofday 2
 151 .Sh HISTORY
 152 The
 153 .Fn timeradd
 154 family of macros were imported from
 155 .Nx 1.1 ,
 156 and appeared in
 157 .Fx 2.2.6 .
 158 The
 159 .Fn timespecadd
 160 family of macros were imported from
 161 .Nx 1.3
 162 into
 163 .Fx 3.0 ,
 164 though they were not exposed to userland until
 165 .Fx 12.0 .