b6b9d458 |
1 | .\" -*-nroff-*- |
fbf20b5b |
2 | .TH tv 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library" |
b6b9d458 |
3 | .SH NAME |
4 | tv \- arithmetic on \fBstruct timeval\fR objects |
08da152e |
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 | .\" |
b6b9d458 |
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 |
ff76c38f |
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 |
b6b9d458 |
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.) |
08da152e |
171 | .SH "SEE ALSO" |
172 | .BR mLib (3). |
b6b9d458 |
173 | .SH AUTHOR |
9b5ac6ff |
174 | Mark Wooding, <mdw@distorted.org.uk> |