+++ /dev/null
-.\" -*-nroff-*-
-.TH tv 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tv \- arithmetic on \fBstruct timeval\fR objects
-.\" @tv_add
-.\" @tv_addl
-.\" @tv_sub
-.\" @tv_subl
-.\" @tv_cmp
-.\"
-.\" @TV_ADD
-.\" @TV_ADDL
-.\" @TV_SUB
-.\" @TV_SUBL
-.\" @TV_CMP
-.\"
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/tv.h>"
-
-.BI "void tv_add(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " const struct timeval *" b );
-.BI "void tv_addl(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " time_t " sec ", unsigned long " usec );
-.BI "void tv_sub(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " const struct timeval *" b );
-.BI "void tv_subl(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " time_t " sec ", unsigned long " usec );
-.BI "int tv_cmp(const struct timeval *" a ,
-.BI " const struct timeval *" b );
-
-.B "int MILLION;"
-.BI "void TV_ADD(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " const struct timeval *" b );
-.BI "void TV_ADDL(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " time_t " sec ", unsigned long " usec );
-.BI "void TV_SUB(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " const struct timeval *" b );
-.BI "void TV_SUBL(struct timeval *" dst ,
-.BI " const struct timeval *" a ,
-.BI " time_t " sec ", unsigned long " usec );
-.BI "int TV_CMP(const struct timeval *" a ", " op ,
-.BI " const struct timeval *" b );
-.fi
-.SH DESCRIPTION
-The
-.B <mLib/tv.h>
-header file provides functions and macros which perform simple
-arithmetic on objects of type
-.BR "struct timeval" ,
-which is capable of representing times to microsecond precision.
-See your
-.BR gettimeofday (2)
-or
-.BR select (2)
-manpages for details of this structure.
-.PP
-The macros are the recommended interface to
-.BR tv 's
-facilities. The function interface is provided for compatibility
-reasons, and for bizarre cases when macros won't do the job.
-.PP
-The main arithmetic functions are in three-address form: they accept two
-source arguments and a separate destination argument (which may be the
-same as one or even both of the source arguments). The destination is
-written before the sources. All the arguments are pointers to the
-actual structures.
-.PP
-.BI TV_ADD( d ", " x ", " y )
-adds
-.BR timeval s
-.I x
-and
-.I y
-storing the result in
-.IR d .
-Similarly,
-.BI TV_SUB( d ", " x ", " y )
-subtracts
-.I y
-from
-.I x
-storing the result in
-.IR d .
-.PP
-The macros
-.B TV_ADDL
-and
-.B TV_SUBL
-work the same way as
-.B TV_ADD
-and
-.B TV_SUB
-respectively, except their second source operand is expressed
-immediately as two integers arguments expressing a time in seconds and
-microseconds respectively. Hence,
-.BI TV_ADDL( d ", " s ", 3, 250000)"
-adds 3.25 seconds to
-.I s
-and puts the result in
-.IR d .
-Similarly,
-.BI TV_SUBL( d ", " s ", 3, 250000)"
-subtracts 3.25 seconds from
-.I s
-and puts the answer in
-.IR d .
-.PP
-The function equivalents for the above arithmetic macros work in exactly
-the same way (and indeed have trivial implementations in terms of the
-macros). The name of the function corresponding to a macro is simply
-the macro name in lower-case.
-.PP
-Two
-.B timeval
-objects can be compared using the
-.B TV_CMP
-macro. If
-.I op
-is a relational operator (e.g.,
-.RB ` == ',
-.RB ` < ',
-or
-.RB ` >= ')
-then
-.BI TV_CMP( x ", " op ", " y )
-is one when
-.I "x op y"
-is true and zero otherwise.
-.PP
-The function
-.B tv_cmp
-works differently. Given two arguments
-.I x
-and
-.IR y ,
-it returns -1 if
-.IR x " < " y ,
-zero if
-.IR x " == " y ,
-or 1 if
-.IR x " > " y .
-Hence, the result can be compared against zero in a relatively intuitive
-way (as for
-.BR strcmp (3),
-except that because the results are defined more tightly, it's possible
-to use a
-.B switch
-on the result).
-.SH ACKNOWLEDGEMENT
-The idea of passing a relational operator to
-.B TV_CMP
-is stolen from the
-.B timercmp
-macro in the GNU C library. This doesn't look like a GNU original,
-however; whatever, it doesn't seem to be very portable. The GNU
-.B timercmp
-macro had a warning attached to it that it wouldn't work for operators
-like
-.RB ` <= ',
-although I can't see why there'd be a problem. (If there is one, then
-my implementation has it too, because they're the same. I don't
-document the restriction because I don't think it exists.)
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff