NAME

   utc_binreltime - Converts a relative binary timestamp to two timespec
                    structures that express relative time and inaccuracy

 SYNOPSIS

   #include <dce/utc.h>

   int utc_binreltime( reltimespec_t *timesp,
                       timespec_t *inaccsp,
                       utc_t *utc );

 PARAMETERS

   Input

   utc
       Relative binary timestamp. Use NULL if you want this routine to
       use the current time for this parameter.

   Output

   timesp
       Time component of the relative binary timestamp, in the
       form of seconds and nanoseconds since the base time
       (1970-01-01:00:00:00.0+00:00I0).

   inaccsp
       Inaccuracy component of the relative binary timestamp, in the
       form of seconds and nanoseconds.

 DESCRIPTION

   The utc_binreltime() routine converts a relative binary timestamp to
   two timespec structures that express relative time and inaccuracy.
   These timespec structures describe a time interval.

 RETURN VALUES

    0    Indicates that the routine executed successfully.

   -1    Indicates an invalid time argument or invalid results.

 EXAMPLES

   The following example measures the duration of a process, then prints
   the resulting relative time and inaccuracy.

        utc_t               before, duration;
        reltimespec_t       tduration;
        timespec_t          iduration;

      /*   Get the time before the start of the operation...          */
      utc_gettime(&before);           /* Out: Before binary timestamp */

      /*    ...Later...
       *    Subtract, getting the duration as a relative time.
       *
       *    NOTE: The NULL argument is used to obtain the current time.
       */

      utc_subtime(&duration,       /* Out: Duration rel bin timestamp */
                  (utc_t *)0,      /* In:  After binary timestamp     */
                  &before);        /* In:  Before binary timestamp    */

      /*   Convert the relative times to timespec structures...       */

      utc_binreltime(&tduration,   /* Out: Duration time timespec     */
                     &iduration,   /* Out: Duration inacc timespec    */
                     &duration);   /* In:  Duration rel bin timestamp */

      /*   Print the duration...        */
      printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000));

      if ((long)iduration.tv_sec == -1)
          printf("Iinf\n");
      else
          printf( "I%d.%04d\n",
                  iduration.tv_sec,
                  (iduration.tv_nsec/100000) );

 RELATED INFORMATION

   Functions:  utc_mkbinreltime