Cosm API - Time Functions

[Cosm Logo]

Time and Random Functions

v3Time
v3TimeSet
v3TimeUnitsGregorian
v3TimeDigestGregorian

v3Time

Syntax

#include "cosmtime.h"
s32 v3Time( v3_time * dest,
  const v3_TIME_CORRECTION * const corrections );

Description

Get the current time, already synchronized with network time. Compensate for system clock drift and correct accordingly.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

dest or corrections is NULL.
corrections is not properly initialized.
Could not get the system time.
corrections was set in the future.
Could not get a mutex lock. See v3MutexLock in cosmtask.h.

Example

v3TimeSet

Syntax

#include "cosmtime.h"
s32 v3TimeSet( v3_TIME_CORRECTION * corrections,
  u32 * ip_list, u32 ip_count );

Description

Synchronize with network time. Don't attempt to set the system clock even though that would be nice. Set the value of time_offset and related values relative to the system clock instead. Use the ip_list as the list of time servers to sync with.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

None.

Example

v3TimeUnitsGregorian

Syntax

#include "cosmtime.h"
s32 v3TimeUnitsGregorian( v3_TIME_UNITS * units, v3_time time );

Description

Fill in the units structure with the time in Gregorian format.

The structure of v3_TIME_UNITS is as follows:

typedef struct
{
  /* all values are zero based */
  s64 year;   /* year */
  u32 month;  /* month */
  u32 day;    /* day of month */
  u32 wday;   /* day of week */
  u32 yday;   /* day of year */
  u32 hour;   /* hours */
  u32 min;    /* minutes */
  u32 sec;    /* seconds */
  u64 subsec; /* sub-seconds, note: unsigned unlike v3_time */
} v3_TIME_UNITS;

Users will probably find the predefined arrays V3_TIME_MONTHS, V3_TIME_MONTHS3, V3_TIME_DAYS, and V3_TIME_DAYS3 useful, see example.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

units is NULL.

Example

  v3_time mytime;
  v3_TIME_UNITS myunits;
  const ascii * days[7] = V3_TIME_DAYS3;
  const ascii * months[12] = V3_TIME_MONTHS;
  u64 milli;

  _V3_SET64( milli, 00418937, 4BC6A7EF );
    if ( v3SystemClock( &mytime ) == V3_PASS )
  {
    if ( v3TimeUnitsGregorian( &myunits, mytime ) == V3_PASS )
    {
      v3PrintA( (ascii *)
        "%.9s %.9s %u, %j %02u:%02u:%02u.%03v UTC, d%u\n",
        days[myunits.wday], months[myunits.month], myunits.day + 1,
        myunits.year, myunits.hour, myunits.min, myunits.sec,
        v3u64Div( myunits.subsec, milli ), myunits.yday + 1 );
    }
  }

v3TimeDigestGregorian

Syntax

#include "cosmtime.h"
s32 v3TimeDigestGregorian( v3_time * time,
  const v3_TIME_UNITS * const units );

Description

Convert back to a v3_time value from Gregorian, sanity check the values.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

time or units is NULL.
Invalid month or number of days in units.
An overflow or underflow.