chiark / gitweb /
Makefile: Use check_PROGRAMS target.
[mLib] / man / 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>