Computes the sum of two binary timestamps; the timestamps can be
    two relative times or a relative time and an absolute time.

    Format

      #include <utc.h>

      int utc_addtime(result, *utc1, *utc2)

         utc_t result;
         const utc_t *utc1;
         const utc_t *utc2;

1 - Parameters

    Input

 utc1

    Binary timestamp or relative binary timestamp.

 utc2

    Binary timestamp or relative binary timestamp.

    Output

 result

    Resulting binary timestamp or relative binary timestamp,
    depending on the operation performed:

    o  relative time + relative time = relative time

    o  absolute time + relative time = absolute time

    o  relative time + absolute time = absolute time

    o  absolute time + absolute time is undefined. See NOTES.

2 - Description

    The Add Time routine adds two binary timestamps, producing a
    third binary timestamp whose inaccuracy is the sum of the two
    input inaccuracies. One or both of the input timestamps typically
    represent a relative (delta) time. The TDF in the first input
    timestamp is copied to the output.

3 - Notes

    Although no error is returned, do not use the combination
    absolute time + absolute time.

4 - Returns

     0   Indicates that the routine executed successfully.
    -1   Indicates an invalid time parameter or invalid results.

5 - Example

    The following example shows how to compute a timestamp that
    represents a time at least 5 seconds in the future.

    utc_t               now, future, fivesec;
    reltimespec_t       tfivesec;
    timespec_t          tzero;

    /*
     *   Construct a timestamp that represents 5 seconds...
     */
    tfivesec.tv_sec = 5;
    tfivesec.tv_nsec = 0;
    tzero.tv_sec = 0;
    tzero.tv_nsec = 0;
    utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */
                    &tfivesec, /* In:  5 secs in timespec         */
                    &tzero);   /* In:  0 secs inaccuracy in timespec */

    /*
     *  Get the maximum possible current time...
     *  (NULL input parameter is used to specify the current time.)
     */
    utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */
                 (utc_t *)0, /* Out: Midpoint of current time       */
                 &now,       /* Out: Latest possible current time   */
                 (utc_t *)0);/* In:  Use current time               */

    /*
     *   Add 5 seconds to get future timestamp...
     */
    utc_addtime(&future,     /* Out: Future binary timestamp        */
                &now,        /* In:  Latest possible time now       */
                &fivesec);   /* In:  5 secs                         */

6 - Related Functions

    utc_subtime