Mostly looks good. A few quick questions:
lint will complain about a constant conditional for timeradd() and
timersub(). Use of the /* LINTED */ comment before timeradd() or
timersub() is recommended.
Can't this be rectified in the header by use of #ifdef lint and some
special lint-only version of the macros? I particularly dislike the
cases where system headers (or system-supplied macros) make lint harder
to use.
Are macros the best way to add these? As opposed to inline functions or
somesuch? (In particular, do we know if the other systems -- Linux and
FreeBSD -- all implement these as macros?) The various caveats with
macros tend to make me want to shy away from their use in system
headers, particularly where the intended consumers are the larger
audience of general programmers. But if that's the way they are
implemented everywhere else, then I suppose it won't hurt too badly to
have them implemented as such as here.
Are there any #define's to conditionally enable or disable these being
added to the namespace? (I'm thinking along the lines of dialect
options that the C compiler exports, e.g. __STDC__, _POSIX_C_SOURCE, and
__EXTENSIONS__.)
The other question (and this is just general, not architectural in
nature) is, given that these functions seem to be widely useful and
popular, are you aware of any movement in any of the standards bodies
(POSIX) to standardize on these?
-- Garrett
Don Cragun wrote:
> Template Version: @(#)sac_nextcase 1.66 04/17/08 SMI
> This information is Copyright 2008 Sun Microsystems
> 1. Introduction
> 1.1. Project/Component Working Name:
> Add timeradd() and timersub() to <sys/time.h>.
> 1.2. Name of Document Author/Supplier:
> Author: Dan McDonald
> 1.3 Date of This Document:
> 09 June, 2008
> 4. Technical Description
> We propose the addition of two macros in sys/time.h commonly found in
> BSD and Linux systems -- timeradd() and timersub() -- and the
> documentation of both these AND the existing timerisset(),
> timerclear(), and timercmp() functions.
>
> The proposed interface taxonomy is "Committed", and the proposed
> release binding is Micro/Patch.
>
> A draft man page for these functions is in the case's materials
> directory and is included here:
>
> Standard C Library Functions timeradd(3C)
>
> NAME
> timeradd, timersub, timerclear, timerisset, timercmp -- operations on
> timeval structures
>
> SYNOPSIS
> #include <sys/time.h>
>
> void
> timeradd(struct timeval *a, struct timeval *b, struct timeval *res);
>
> void
> timerclear(struct timeval *tvp);
>
> int
> timercmp(struct timeval *a, struct timeval *b, CMP);
>
> int
> timerisset(struct timeval *tvp);
>
> void
> timersub(struct timeval *a, struct timeval *b, struct timeval *res);
>
> DESCRIPTION
> These macros are provided for manipulating timeval structures for use
> with gettimeofday() and settimeofday() operands. The structure is
> defined in <sys/time.h> as:
>
> struct timeval {
> long tv_sec; /* seconds since Jan. 1, 1970 */
> long tv_usec; /* and microseconds */
> };
>
> timeradd() adds the time information stored in a to b and stores the
> resulting timeval in res. The results are simplified such that
> the value
> of res->tv_usec is always less than 1,000,000 (1 second).
>
> timersub() subtracts the time information stored in b from a and stores
> the resulting timeval in res.
>
> timerclear() initializes tvp to midnight (0 hour) January 1st, 1970 (the
> Epoch).
>
> timerisset() returns true if tvp is set to any time value other than the
> Epoch.
>
> timercmp() compares a to b using the form a CMP b, where CMP is one of
> <, <=, ==, !=, >=, or >.
>
> SEE ALSO
> gettimeofday(3C)
>
> USAGE
>
> These macros are not available in function form. All of these macros
> evaulate their arguments more than once. If parameters passed to these
> macros are expressions with side effects, the results are undefined.
>
> lint will complain about a constant conditional for timeradd() and
> timersub(). Use of the /* LINTED */ comment before timeradd() or
> timersub() is recommended.
>
> ATTRIBUTES
>
> ____________________________________________________________
> | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
> |_____________________________|_____________________________|
> | Interface Stability | These macros are Committed. |
> |_____________________________|_____________________________|
> | MT-Level | MT-Safe with Exceptions |
> | | (See USAGE about arguments) |
> |_____________________________|_____________________________|
>
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> ON
> 6.5. ARC review type: FastTrack
> 6.6. ARC Exposure: open
>
>
