Time constants

Time structure

Time library provides structure called time_struct, which holds wall clock time value without date.

C/C++struct time_struct
{
    uint8_t hour;
    uint8_t min;
    uint8_t sec;
};

It has following fields:

• hour - hours [0-23]
• min - minutes [0-59]
• sec - seconds [0-59]

Date structure

Date structure date_struct holds calendar date in natural format, instead of Unix time format.

C/C++struct date_struct
{
    sint32_t year;
    uint8_t  mon;
    uint8_t  day;
    uint8_t  wday;
    uint8_t  hour;
    uint8_t  min;
    uint8_t  sec;
};

This structure has following members:

• year - year from beginning of Gregorian calendar
• mon - month of year [1-12]
• day - day of month [1-31]
• wday - day of week (0 - Sunday) [0-6]
• hour - hours [0-23]
• min - minutes [0-59]
• sec - seconds [0-59]

Note:Be aware that month range is 1-12 instead of range 0-11, which is used by standard C library. And year is full year number. Not since 1900.

Constructor

Cvoid Time_InitTime (struct Time *tzone);

C++Time::Time (void);

Description: Constructor which init Time object with default values (cleans time zone). In C++ code it is called automatically when Time class object is created. In C code you should manually call appropriate function.

Parameters:

• tzone - a pointer to time zone structure

Return value: None.

Loading time zone data from tzfile

Cerror_t Time_LoadTimeZone (struct Time *tzone, const char8_t tzfile[]);

C++error_t Time::LoadTimeZone (const char8_t tzfile[]);

Description: Loads time zone data from specified tzfile into time zone structure. Time zone information may be used to convert system time to local time for selected time zone.

Parameters:

• tzone - a pointer to a time zone structure, where time zone data will be placed
• tzfile - path to tzfile, which describes required time zone

Return value:

• 0 (zero) if no errors.
• ERRNO if an error occurred during reading or analyzing tzfile.

Time conversion

Ctime_t Time_ConvertTime (uint8_t hour, uint8_t min, uint8_t sec);

C++time_t Time::ConvertTime (uint8_t hour, uint8_t min, uint8_t sec);

Description: Converts wall clock time (HH:MM:SS) into Unix time format and skips date value (equal to set date to 1-st of January 0000 year).

Parameters:

• hour - hours [0-23]
• min - minutes [0-59]
• sec - seconds [0-59]

Return value:

• Unix time value without date.
• TIME_ERROR in case of hours or minutes or seconds are out of range.

Date conversion

Ctime_t Time_ConvertDate (uint8_t day, uint8_t mon, sint32_t year, uint8_t hour, uint8_t min, uint8_t sec);

C++time_t Time::ConvertDate (uint8_t day, uint8_t mon, sint32_t year, uint8_t hour, uint8_t min, uint8_t sec);

Description: Converts calendar date and wall clock time into Unix time format.

Parameters:

• day - day of month [1-31] depends of month
• mon - month of year [1-12]
• year - year from beginning of Gregorian calendar
• hour - hours [0-23]
• min - minutes [0-59]
• sec - seconds [0-59]

Return value:

• Unix time value.
• TIME_ERROR in case of any of parameters is out of range.

Note:Be aware that month range is 1-12 instead of range 0-11, which is used by standard C library. And year is full year number. Not since 1900.

Time extraction

Ctime_struct Time_ExtractTime (time_t time);

C++time_struct Time::ExtractTime (time_t time);

Description: Extracts wall clock time from specified Unix time value.

Parameters:

• time - Unix time value from which wall clock time value should be extracted

Return value:

• Time value in human readable format "HH:MM:SS".
• "24:00:00" if Unix time is set to TIME_ERROR. Be aware that hour field is set to 24, which is out of hours range and indicates an error.

Date extraction

Cdate_struct Time_ExtractDate (time_t time);

C++date_struct Time::ExtractDate (time_t time);

Description: Converts time from Unix format to human readable calendar date format.

Parameters:

• time - Unix time to convert

Return value:

• Calendar date and time value in human readable format "YYYY-MM-DD HH:MM:SS".
• "0000-00-00 00:00:00" if Unix time is set to TIME_ERROR. Be aware that all fields are set to 0, which indicates an error.

Week day extraction

Cuint8_t Time_WeekDay (time_t time);

C++uint8_t Time::WeekDay (time_t time);

Description: Extracts day of week from Unix time value.

Parameters:

• time - Unix time value from which day of week should be extracted

Return value:

• 0 - Sunday.
• 1 - Monday.
• 2 - Tuesday.
• 3 - Wednesday.
• 4 - Thursday.
• 5 - Friday.
• 6 - Saturday.
• 7 if Unix time is set to TIME_ERROR. Be aware that returned value is out of week day range and indicates an error.

Current system time

Ctime_t Time_SystemTime (void);

C++time_t Time::SystemTime (void);

Description: Returns system's clock time value (current UTC time) from Linux kernel.

Parameters: None.

Return value:

• Current UTC time value.
• TIME_ERROR if system call returned an error value.

Local time

Ctime_t Time_LocalTime (const struct Time *tzone, time_t UTC);

C++time_t Time::LocalTime (time_t UTC) const;

Description: Converts UTC time to local time, using time zone data, previously loaded by "LoadTimeZone" function.

Parameters:

• tzone - a pointer to time zone structure, which holds time correction data for selected time zone
• UTC - UTC Unix time value which should be converted to local time

Return value:

• Local time value in Unix time format, which corresponds to UTC time.
• TIME_ERROR if UTC time is equal to TIME_ERROR or Time object was not initialized or has wrong data.