b6b9d458 |
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> |