Cosm API - Time Functions

[Cosm Logo]

Time and Random Functions

CosmTime
CosmTimeSet
CosmTimeUnitsGregorian
CosmTimeDigestGregorian

CosmTime

Syntax

#include "cosm/time.h"
s32 CosmTime( cosmtime * dest, cosm_TIME_CORRECTION * corrections );

Description

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

Return Values

COSM_PASS on success, or COSM_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 CosmMutexLock in os_task.h.

Example

CosmTimeSet

Syntax

#include "cosm/time.h"
s32 CosmTimeSet( cosm_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

COSM_PASS on success, or COSM_FAIL on failure.

Errors

None.

Example

CosmTimeUnitsGregorian

Syntax

#include "cosm/time.h"
s32 CosmTimeUnitsGregorian( cosm_TIME_UNITS * units, cosmtime time );

Description

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

The structure of cosm_TIME_UNITS is as follows:

typedef struct cosm_TIME_UNITS
{
  /* 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 cosmtime */
} cosm_TIME_UNITS;

Users will probably find the predefined arrays COSM_TIME_MONTHS, COSM_TIME_MONTHS3, COSM_TIME_DAYS, and COSM_TIME_DAYS3 useful, see example.

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of failure:

units is NULL.

Example

  cosmtime mytime;
  cosm_TIME_UNITS myunits;
  const ascii * days[7] = COSM_TIME_DAYS3;
  const ascii * months[12] = COSM_TIME_MONTHS;
  u64 milli;

  milli = 0x004189374BC6A7EFLL;
    if ( CosmSystemClock( &mytime ) == COSM_PASS )
  {
    if ( CosmTimeUnitsGregorian( &myunits, mytime ) == COSM_PASS )
    {
      CosmPrint(
        "%.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,
        ( myunits.subsec / milli ), myunits.yday + 1 );
    }
  }

CosmTimeDigestGregorian

Syntax

#include "cosm/time.h"
s32 CosmTimeDigestGregorian( cosmtime * time,
  const cosm_TIME_UNITS * const units );

Description

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

Return Values

COSM_PASS on success, or COSM_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.