Name

utc_cmpmidtime - Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies

Synopsis

#include <dce/utc.h> int utc_cmpmidtime(
enum utc_cmptype ∗relation,
utc_t ∗utc1,
utc_t ∗utc2);

Parameters

Input

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

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

Output

relationResult of the comparison of utc1:utc2 where the result is an enumerated type with one of the following values:

       •utc_equalTo

       •utc_lessThan

       •utc_greaterThan

Description

The utc_cmpmidtime() routine compares two binary timestamps and returns a flag indicating that the first timestamp is greater than, less than, or equal to the second timestamp.  Inaccuracy information is ignored for this comparison; the input values are therefore equivalent to the midpoints of the time intervals described by the input binary timestamps. 

The input binary timestamps express two absolute or two relative times.  Do not compare relative binary timestamps to absolute binary timestamps.  If you do, no meaningful results and no errors are returned. 

The following routine does a lexical ordering on the time interval midpoints. 

utc1 is utc_lessThan utc2 iff
        utc1.time < utc2.time
 utc1 is utc_greaterThan utc2 iff
        utc1.time > utc2.time
 utc1 is utc_equalTo utc2 iff
        utc1.time == utc2.time

Return Values

 0Indicates that the routine executed successfully. 

-1Indicates an invalid time argument. 

Examples

The following example checks if the current time (ignoring inaccuracies) is after 13:00 local time. 

struct tm           tmtime, tmzero;
enum utc_cmptype    relation;
utc_t               testtime;
 /∗   Zero the tm structure for inaccuracy...
 ∗/
memset(&tmzero, 0, sizeof(tmzero));
 /∗   Get the current time, mapped to a tm structure...
 ∗
 ∗        NOTE:  The NULL argument is used to get the current time.
 ∗/
utc_localtime(&tmtime,        /∗ Out: Current local time in tm struct ∗/
             (long ∗)0,       /∗ Out: Nanoseconds of time             ∗/
             (struct tm ∗)0,  /∗ Out: Current inacc in tm struct      ∗/
             (long ∗)0,       /∗ Out: Nanoseconds of inaccuracy       ∗/
             (utc_t ∗)0);     /∗ In:  Current timestamp               ∗/
  /∗   Alter the tm structure to correspond to 13:00 local time.
  ∗/
tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;
  /∗   Convert to a binary timestamp...
  ∗/
utc_mklocaltime(&testtime,    /∗ Out: Binary timestamp of 13:00       ∗/
                &tmtime,      /∗ In:  13:00 in tm struct              ∗/
                0,            /∗ In:  Nanoseconds of time             ∗/
                &tmzero,      /∗ In:  Zero inaccuracy in tm struct    ∗/
                0);           /∗ In:  Nanoseconds of inaccuracy       ∗/
  /∗   Compare to the current time.  Note the use of the NULL argument
  ∗/
utc_cmpmidtime(&relation,     /∗ Out: Comparison relation             ∗/
               (utc_t ∗)0,    /∗ In:  Current timestamp               ∗/
               &testtime);    /∗ In:  13:00 local time timestamp      ∗/
  /∗   If the time is not later - wait, print a message, etc.
  ∗/
if (relation != utc_greaterThan) {
  /∗          It is not later then 13:00 local time.  Note that
  ∗          this depends on the setting of the user’s environment.
  ∗/
}

Related Information

Functions: utc_cmpintervaltime(3dts).