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

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