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

   1 .\" -*-nroff-*-
   2 .TH tv 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 tv \- arithmetic on \fBstruct timeval\fR objects
   5 .\" @tv_add
   6 .\" @tv_addl
   7 .\" @tv_sub
   8 .\" @tv_subl
   9 .\" @tv_cmp
  10 .\"
  11 .\" @TV_ADD
  12 .\" @TV_ADDL
  13 .\" @TV_SUB
  14 .\" @TV_SUBL
  15 .\" @TV_CMP
  16 .\"
  17 .SH SYNOPSIS
  18 .nf
  19 .B "#include <mLib/tv.h>"
  20
  21 .BI "void tv_add(struct timeval *" dst ,
  22 .BI "            const struct timeval *" a ,
  23 .BI "            const struct timeval *" b );
  24 .BI "void tv_addl(struct timeval *" dst ,
  25 .BI "             const struct timeval *" a ,
  26 .BI "             time_t " sec ", unsigned long " usec );
  27 .BI "void tv_sub(struct timeval *" dst ,
  28 .BI "            const struct timeval *" a ,
  29 .BI "            const struct timeval *" b );
  30 .BI "void tv_subl(struct timeval *" dst ,
  31 .BI "             const struct timeval *" a ,
  32 .BI "             time_t " sec ", unsigned long " usec );
  33 .BI "int tv_cmp(const struct timeval *" a ,
  34 .BI "           const struct timeval *" b );
  35
  36 .B "int MILLION;"
  37 .BI "void TV_ADD(struct timeval *" dst ,
  38 .BI "            const struct timeval *" a ,
  39 .BI "            const struct timeval *" b );
  40 .BI "void TV_ADDL(struct timeval *" dst ,
  41 .BI "             const struct timeval *" a ,
  42 .BI "             time_t " sec ", unsigned long " usec );
  43 .BI "void TV_SUB(struct timeval *" dst ,
  44 .BI "            const struct timeval *" a ,
  45 .BI "            const struct timeval *" b );
  46 .BI "void TV_SUBL(struct timeval *" dst ,
  47 .BI "             const struct timeval *" a ,
  48 .BI "             time_t " sec ", unsigned long " usec );
  49 .BI "int TV_CMP(const struct timeval *" a ", " op ,
  50 .BI "           const struct timeval *" b );
  51 .fi
  52 .SH DESCRIPTION
  53 The
  54 .B <mLib/tv.h>
  55 header file provides functions and macros which perform simple
  56 arithmetic on objects of type
  57 .BR "struct timeval" ,
  58 which is capable of representing times to microsecond precision.
  59 See your
  60 .BR gettimeofday (2)
  61 or
  62 .BR select (2)
  63 manpages for details of this structure.
  64 .PP
  65 The macros are the recommended interface to
  66 .BR tv 's
  67 facilities.  The function interface is provided for compatibility
  68 reasons, and for bizarre cases when macros won't do the job.
  69 .PP
  70 The main arithmetic functions are in three-address form: they accept two
  71 source arguments and a separate destination argument (which may be the
  72 same as one or even both of the source arguments).  The destination is
  73 written before the sources.  All the arguments are pointers to the
  74 actual structures.
  75 .PP
  76 .BI TV_ADD( d ", " x ", " y )
  77 adds
  78 .BR timeval s
  79 .I x
  80 and
  81 .I y
  82 storing the result in
  83 .IR d .
  84 Similarly,
  85 .BI TV_SUB( d ", " x ", " y )
  86 subtracts
  87 .I y
  88 from
  89 .I x
  90 storing the result in
  91 .IR d .
  92 .PP
  93 The macros
  94 .B TV_ADDL
  95 and
  96 .B TV_SUBL
  97 work the same way as
  98 .B TV_ADD
  99 and
 100 .B TV_SUB
 101 respectively, except their second source operand is expressed
 102 immediately as two integers arguments expressing a time in seconds and
 103 microseconds respectively.  Hence,
 104 .BI TV_ADDL( d ", " s ", 3, 250000)"
 105 adds 3.25 seconds to
 106 .I s
 107 and puts the result in
 108 .IR d .
 109 Similarly,
 110 .BI TV_SUBL( d ", " s ", 3, 250000)"
 111 subtracts 3.25 seconds from
 112 .I s
 113 and puts the answer in
 114 .IR d .
 115 .PP
 116 The function equivalents for the above arithmetic macros work in exactly
 117 the same way (and indeed have trivial implementations in terms of the
 118 macros).  The name of the function corresponding to a macro is simply
 119 the macro name in lower-case.
 120 .PP
 121 Two
 122 .B timeval
 123 objects can be compared using the
 124 .B TV_CMP
 125 macro.  If
 126 .I op
 127 is a relational operator (e.g.,
 128 .RB ` == ',
 129 .RB ` < ',
 130 or
 131 .RB ` >= ')
 132 then
 133 .BI TV_CMP( x ", " op ", " y )
 134 is one when
 135 .I "x op y"
 136 is true and zero otherwise.
 137 .PP
 138 The function
 139 .B tv_cmp
 140 works differently.  Given two arguments
 141 .I x
 142 and
 143 .IR y ,
 144 it returns -1 if
 145 .IR x " < " y ,
 146 zero if
 147 .IR x " == " y ,
 148 or 1 if
 149 .IR x " > " y .
 150 Hence, the result can be compared against zero in a relatively intuitive
 151 way (as for
 152 .BR strcmp (3),
 153 except that because the results are defined more tightly, it's possible
 154 to use a
 155 .B switch
 156 on the result).
 157 .SH ACKNOWLEDGEMENT
 158 The idea of passing a relational operator to
 159 .B TV_CMP
 160 is stolen from the
 161 .B timercmp
 162 macro in the GNU C library.  This doesn't look like a GNU original,
 163 however; whatever, it doesn't seem to be very portable.  The GNU
 164 .B timercmp
 165 macro had a warning attached to it that it wouldn't work for operators
 166 like
 167 .RB ` <= ',
 168 although I can't see why there'd be a problem.  (If there is one, then
 169 my implementation has it too, because they're the same.  I don't
 170 document the restriction because I don't think it exists.)
 171 .SH "SEE ALSO"
 172 .BR mLib (3).
 173 .SH AUTHOR
 174 Mark Wooding, <mdw@distorted.org.uk>