@@@ much mess, mostly manpages

[mLib] / sys / tv.3.in

.\" -*-nroff-*-
.\"
.\" Manual for timeval arithmetic
.\"
.\" (c) 1999, 2001, 2005, 2009, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tv 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @tv_add
.\" @tv_addl
.\" @tv_sub
.\" @tv_subl
.\" @tv_cmp
.
.\" @TV_ADD
.\" @TV_ADDL
.\" @TV_SUB
.\" @TV_SUBL
.\" @TV_CMP
.
.\"--------------------------------------------------------------------------
.SH NAME
tv \- arithmetic on \fBstruct timeval\fR objects
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/tv.h>"
.PP
.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 );
.PP
.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>
.
.\"----- That's all, folks --------------------------------------------------