| 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@nsict.org> |