Add a slew of manual pages.

[mLib] / man / tv.3

diff --git a/man/tv.3 b/man/tv.3
new file mode 100644 (file)
index 0000000..71f33f4
--- /dev/null
+++ b/man/tv.3
@@ -0,0 +1,160 @@
+.\" -*-nroff-*-
+.TH tv 3mLib "22 May 1999" mLib
+.SH NAME
+tv \- arithmetic on \fBstruct timeval\fR objects
+.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.  I don't know whether this macro is a GNU
+original, but it certainly doesn't seem to be portable.  The
+.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 AUTHOR
+Mark Wooding, <mdw@nsict.org>