NAME

   utc_addtime - Computes the sum of two binary timestamps

 SYNOPSIS

   #include <dce/utc.h>

   int utc_addtime( utc_t* result,
                    utc_t *utc1,
                    utc_t *utc2 );

 PARAMETERS

   Input

   utc1
       Binary timestamp or relative binary timestamp. Use NULL if you
       want this routine to use the current time for this parameter.

   utc2
       Binary timestamp or relative binary timestamp. Use NULL if you
       want this routine to use the current time for this parameter.

   Output

   result
       Resulting binary timestamp or relative binary timestamp, depending
       upon the operation performed:

         + relative time+relative time=relative time

         + absolute time+relative time=absolute time

         + relative time+absolute time=absolute time

         + absolute time+absolute time is undefined.  (See the note later
           in this reference page.)

 DESCRIPTION

   The utc_addtime() 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
   represents a relative (delta) time. The TDF in the first input time-
   stamp is copied to the output.  The timestamps can be two relative
   times or a relative time and an absolute time.

 NOTES

   Although no error is returned, the combination absolute time+absolute
   time should not be used.

 RETURN VALUES

    0    Indicates that the routine executed successfully.

   -1    Indicates an invalid time parameter or invalid results.

 EXAMPLES

   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...
      *  (The 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                        */

 RELATED INFORMATION

   Functions: utc_subtime