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 .Dd July 30, 2018
  29 .Dt TIMERADD 3
  30 .Os
  31 .Sh NAME
  32 .Nm timeradd ,
  33 .Nm timersub ,
  34 .Nm timerclear ,
  35 .Nm timerisset ,
  36 .Nm timercmp ,
  37 .Nm timespecadd ,
  38 .Nm timespecsub ,
  39 .Nm timespecclear ,
  40 .Nm timespecisset ,
  41 .Nm timespeccmp
  42 .Nd operations on timevals and timespecs
  43 .Sh SYNOPSIS
  44 .In sys/time.h
  45 .Ft void
  46 .Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res"
  47 .Ft void
  48 .Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res"
  49 .Ft void
  50 .Fn timerclear "struct timeval *tvp"
  51 .Ft int
  52 .Fn timerisset "struct timeval *tvp"
  53 .Ft int
  54 .Fn timercmp "struct timeval *a" "struct timeval *b" CMP
  55 .Ft void
  56 .Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res"
  57 .Ft void
  58 .Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res"
  59 .Ft void
  60 .Fn timespecclear "struct timespec *ts"
  61 .Ft int
  62 .Fn timespecisset "struct timespec *ts"
  63 .Ft int
  64 .Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP
  65 .Sh DESCRIPTION
  66 These macros are provided for manipulating
  67 .Fa timeval
  68 and
  69 .Fa timespec
  70 structures for use with the
  71 .Xr clock_gettime 2 ,
  72 .Xr clock_settime 2 ,
  73 .Xr gettimeofday 2
  74 and
  75 .Xr settimeofday 2
  76 calls.
  77 The
  78 .Fa timeval
  79 structure is defined in
  80 .In sys/time.h
  81 as:
  82 .Bd -literal
  83 struct timeval {
  84         long    tv_sec;         /* seconds since Jan. 1, 1970 */
  85         long    tv_usec;        /* and microseconds */
  86 };
  87 .Ed
  88 And the
  89 .Fa timespec
  90 structure is defined in
  91 .In time.h
  92 as:
  93 .Bd -literal
  94 struct timespec {
  95         time_t tv_sec;          /* seconds */
  96         long   tv_nsec;         /* and nanoseconds */
  97 };
  98 .Ed
  99 .Pp
 100 .Fn timeradd
 101 and
 102 .Fn timespecadd
 103 add the time information stored in
 104 .Fa a
 105 to
 106 .Fa b
 107 and store the result in
 108 .Fa res .
 109 The results are simplified such that the value of
 110 .Fa res->tv_usec
 111 or
 112 .Fa res->tv_nsec
 113 is always less than 1 second.
 114 .Pp
 115 .Fn timersub
 116 and
 117 .Fn timespecsub
 118 subtract the time information stored in
 119 .Fa b
 120 from
 121 .Fa a
 122 and store the result
 123 in
 124 .Fa res .
 125 .Pp
 126 .Fn timerclear
 127 and
 128 .Fn timespecclear
 129 initialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch).
 130 .Pp
 131 .Fn timerisset
 132 and
 133 .Fn timespecisset
 134 return true if their argument is set to any time value other than the Epoch.
 135 .Pp
 136 .Fn timercmp
 137 and
 138 .Fn timespeccmp
 139 compare
 140 .Fa a
 141 to
 142 .Fa b
 143 using the comparison operator given in
 144 .Fa CMP ,
 145 and return the result of that comparison.
 146 .Sh SEE ALSO
 147 .Xr clock_gettime 2 ,
 148 .Xr gettimeofday 2
 149 .Sh HISTORY
 150 The
 151 .Fn timeradd
 152 family of macros were imported from
 153 .Nx 1.1 ,
 154 and appeared in
 155 .Fx 2.2.6 .
 156 The
 157 .Fn timespecadd
 158 family of macros were imported from
 159 .Nx 1.3
 160 into
 161 .Fx 3.0 ,
 162 though they were not exposed to userland until
 163 .Fx 12.0 .