chiark - git - mdw - mLib/blob - sys/tv.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for timeval arithmetic
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH tv 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @tv_add
  33 .\" @tv_addl
  34 .\" @tv_sub
  35 .\" @tv_subl
  36 .\" @tv_cmp
  37 .
  38 .\" @TV_ADD
  39 .\" @TV_ADDL
  40 .\" @TV_SUB
  41 .\" @TV_SUBL
  42 .\" @TV_CMP
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .SH NAME
  46 tv \- arithmetic on \fBstruct timeval\fR objects
  47 .
  48 .\"--------------------------------------------------------------------------
  49 .SH SYNOPSIS
  50 .
  51 .nf
  52 .B "#include <mLib/tv.h>"
  53 .PP
  54 .BI "void tv_add(struct timeval *" dst ,
  55 .BI "            const struct timeval *" a ,
  56 .BI "            const struct timeval *" b );
  57 .BI "void tv_addl(struct timeval *" dst ,
  58 .BI "             const struct timeval *" a ,
  59 .BI "             time_t " sec ", unsigned long " usec );
  60 .BI "void tv_sub(struct timeval *" dst ,
  61 .BI "            const struct timeval *" a ,
  62 .BI "            const struct timeval *" b );
  63 .BI "void tv_subl(struct timeval *" dst ,
  64 .BI "             const struct timeval *" a ,
  65 .BI "             time_t " sec ", unsigned long " usec );
  66 .BI "int tv_cmp(const struct timeval *" a ,
  67 .BI "           const struct timeval *" b );
  68 .PP
  69 .B "int MILLION;"
  70 .BI "void TV_ADD(struct timeval *" dst ,
  71 .BI "            const struct timeval *" a ,
  72 .BI "            const struct timeval *" b );
  73 .BI "void TV_ADDL(struct timeval *" dst ,
  74 .BI "             const struct timeval *" a ,
  75 .BI "             time_t " sec ", unsigned long " usec );
  76 .BI "void TV_SUB(struct timeval *" dst ,
  77 .BI "            const struct timeval *" a ,
  78 .BI "            const struct timeval *" b );
  79 .BI "void TV_SUBL(struct timeval *" dst ,
  80 .BI "             const struct timeval *" a ,
  81 .BI "             time_t " sec ", unsigned long " usec );
  82 .BI "int TV_CMP(const struct timeval *" a ", " op ,
  83 .BI "           const struct timeval *" b );
  84 .fi
  85 .
  86 .\"--------------------------------------------------------------------------
  87 .SH DESCRIPTION
  88 .
  89 The
  90 .B <mLib/tv.h>
  91 header file provides functions and macros which perform simple
  92 arithmetic on objects of type
  93 .BR "struct timeval" ,
  94 which is capable of representing times to microsecond precision.
  95 See your
  96 .BR gettimeofday (2)
  97 or
  98 .BR select (2)
  99 manpages for details of this structure.
 100 .PP
 101 The macros are the recommended interface to
 102 .BR tv 's
 103 facilities.  The function interface is provided for compatibility
 104 reasons, and for bizarre cases when macros won't do the job.
 105 .PP
 106 The main arithmetic functions are in three-address form: they accept two
 107 source arguments and a separate destination argument (which may be the
 108 same as one or even both of the source arguments).  The destination is
 109 written before the sources.  All the arguments are pointers to the
 110 actual structures.
 111 .PP
 112 .BI TV_ADD( d ", " x ", " y )
 113 adds
 114 .BR timeval s
 115 .I x
 116 and
 117 .I y
 118 storing the result in
 119 .IR d .
 120 Similarly,
 121 .BI TV_SUB( d ", " x ", " y )
 122 subtracts
 123 .I y
 124 from
 125 .I x
 126 storing the result in
 127 .IR d .
 128 .PP
 129 The macros
 130 .B TV_ADDL
 131 and
 132 .B TV_SUBL
 133 work the same way as
 134 .B TV_ADD
 135 and
 136 .B TV_SUB
 137 respectively, except their second source operand is expressed
 138 immediately as two integers arguments expressing a time in seconds and
 139 microseconds respectively.  Hence,
 140 .BI TV_ADDL( d ", " s ", 3, 250000)"
 141 adds 3.25 seconds to
 142 .I s
 143 and puts the result in
 144 .IR d .
 145 Similarly,
 146 .BI TV_SUBL( d ", " s ", 3, 250000)"
 147 subtracts 3.25 seconds from
 148 .I s
 149 and puts the answer in
 150 .IR d .
 151 .PP
 152 The function equivalents for the above arithmetic macros work in exactly
 153 the same way (and indeed have trivial implementations in terms of the
 154 macros).  The name of the function corresponding to a macro is simply
 155 the macro name in lower-case.
 156 .PP
 157 Two
 158 .B timeval
 159 objects can be compared using the
 160 .B TV_CMP
 161 macro.  If
 162 .I op
 163 is a relational operator (e.g.,
 164 .RB ` == ',
 165 .RB ` < ',
 166 or
 167 .RB ` >= ')
 168 then
 169 .BI TV_CMP( x ", " op ", " y )
 170 is one when
 171 .I "x op y"
 172 is true and zero otherwise.
 173 .PP
 174 The function
 175 .B tv_cmp
 176 works differently.  Given two arguments
 177 .I x
 178 and
 179 .IR y ,
 180 it returns -1 if
 181 .IR x "\ <\ " y ,
 182 zero if
 183 .IR x "\ =\ " y ,
 184 or 1 if
 185 .IR x "\ >\ " y .
 186 Hence, the result can be compared against zero in a relatively intuitive
 187 way (as for
 188 .BR strcmp (3),
 189 except that because the results are defined more tightly, it's possible
 190 to use a
 191 .B switch
 192 on the result).
 193 .SH ACKNOWLEDGEMENT
 194 The idea of passing a relational operator to
 195 .B TV_CMP
 196 is stolen from the
 197 .B timercmp
 198 macro in the GNU C library.  This doesn't look like a GNU original,
 199 however; whatever, it doesn't seem to be very portable.  The GNU
 200 .B timercmp
 201 macro had a warning attached to it that it wouldn't work for operators
 202 like
 203 .RB ` <= ',
 204 although I can't see why there'd be a problem.  (If there is one, then
 205 my implementation has it too, because they're the same.  I don't
 206 document the restriction because I don't think it exists.)
 207 .
 208 .\"--------------------------------------------------------------------------
 209 .SH "SEE ALSO"
 210 .
 211 .BR mLib (3).
 212 .
 213 .\"--------------------------------------------------------------------------
 214 .SH AUTHOR
 215 .
 216 Mark Wooding, <mdw@distorted.org.uk>
 217 .
 218 .\"----- That's all, folks --------------------------------------------------