Time

Time management functions including time zones, NTP, and system clock. More...

Classes
struct	TimeZoneRecord
	Time zone record structure containing complete time zone information. More...

Functions
time_t	time (time_t *pt)
	Gets the current system GMT time.
time_t	set_time (time_t time_to_set, uint32_t fraction=0)
	Set the system time to the value passed in the time_t parameter.
time_t	timegm (struct tm *bts)
	Converts a tm structure to time_t in GMT.
void	tzsetchar (const char *tzenv)
	Set the system local time.

Variables
const TimeZoneRecord *	TZRecords
	Global array of time zone records.

Detailed Description

Time management functions including time zones, NTP, and system clock.

#include< nbtime.h>

The NBTime library provides methods to set and read the system time. The system time will reset whenever power is lost or the system is reset. On power-up, system time can be set:

• With a NTP server (most common)
• From a real time clock (RTC)j
• Manually

Examples are provided in the example section for each of these methods.

Time is always stored as GMT. If you are using an internal or external real-time clock, it should also be set to GMT. Example application function calls are shown below. Refer to the examples for your specific NetBurner platform for RTC functions. Functions with an "_r" are reentrant.

A partial list of common standard Time library functions include:

• time_t time(time_t* timeT) Returns current system GMT time as a time_t, either as an argument or return value. (Provide NULL as an argument to just return a time_t)
• time_t mktime(tm* time) Converts local given time in struct tm format to GMT time as a time_t. Also validates and modifies the time struct to their proper ranges.
• size_t strftime(char* str, size_t count, const char* format, const tm* tp) Creates a formatted time string from the tm struct tp and stores it in a buffer str.
• tm* gmtime(time_t &timeT) Converts given time since epoch (a time_t value pointed to by timeT) to calendar time, expressed in Coordinated Universal Time (UTC) in the struct tm format.
• tm* gmtime_r(time_t &timeT, tm &stmUTC) Converts given time since epoch (a time_t value pointed to by timeT) to calendar time, expressed in Coordinated Universal Time (UTC) in the struct tm format. The result is stored in the struct tm pointed to by stmUTC.
• tm* localtime(time_t &tv) Converts given time since epoch (time_t) to calendar time, expressed in local time, in the struct tm format.
• tm* localtime_r(time_t &tv, tm &tm_struct) Converts given time since epoch (time_t) to calendar time, expressed in local time, in the struct tm format. The result is stored in the tm struct.
• size_t strftime(char* str, size_t count, const char* format, const struct tm* tp) Creates a formatted time string and stores it in a buffer.
• double difftime(time_t t1, time_t t2) Returns the difference between two time_t values.

For example, to get local time:

char buf[80];
time_t RawTime;
struct tm *TimeInfo;
 
time(&RawTime);                   // Get system time in time_t format
TimeInfo = localtime(&RawTime);   // Convert to struct tm format
strftime(buf, 79, "%l:%M:%S %p", TimeInfo);
printf("Formatted time string: %s\r\n", buf);

#include< timezones.h>

The NBTime module provides comprehensive time management capabilities:

• Time zone database with daylight saving time support
• NTP client for network time synchronization
• System clock management and conversions
• Local time calculations with automatic DST adjustments

Function Documentation

set_time()

time_t set_time	(	time_t	time_to_set,
		uint32_t	fraction = 0 )

#include <nbtime.h>

Set the system time to the value passed in the time_t parameter.

Parameters

time_to_set	time_t value to set the system time.
fraction	the fraction (in 1/(2^32) of the second)

Returns

The system time time_t value

time()

time_t time

(

time_t *

pt

)

#include <nbtime.h>

Gets the current system GMT time.

Parameters

pt	Optional pointer to a time_t to fill with the current time (may be NULL)

Returns

The system time time_t value

timegm()

time_t timegm

(

struct tm *

bts

)

#include <nbtime.h>

Converts a tm structure to time_t in GMT.

Performs the reverse translation that is done by gmtime(). This is not to be confused with the mktime() function, which performs the reverse conversion of the localtime() function.

Parameters

bts	Pointer to a tm structure

Returns

time_t value of tm

tzsetchar()

void tzsetchar

(

const char *

tzenv

)

#include <nbtime.h>

Set the system local time.

This function initializes the TZ environment variable to contain the local time zone offset information from the standard time (UTC) and, if applicable, daylight saving time (DST). This does not overwrite the system time to the local time. The TZ environment variable is used by the ctime(), localtime(), mktime(), and strftime() functions of the standard time.h library to calculate the local time.

Once the TZ variable is set, the time library functions use it to determine when DST is in effect, when type conversions are made, or what time zone string is provided in the case of the strftime() function.

The system provides time zones around the world that can be referenced in the TZRecords variable in timezones.h. The time zone strings are located in timezones.cpp. Please refer to the timezones and RTC example programs for methods on utilizing these time zone settings.

Parameters

tzenv

The time zone string. For example: tzsetchar( "EST5EDT4,M3.2.0/02:00:00,M11.1.0/02:00:00" ); Eastern

Variable Documentation

TZRecords

const TimeZoneRecord* TZRecords

extern

#include <timezones.h>

Global array of time zone records.

This constant array contains over 75 time zone definitions covering all major regions worldwide. The array is NULL-terminated (the last record has Posix = NULL) to allow iteration through all available time zones.

The array is defined in nbrtos/source/timezones.cpp and includes time zones sorted by GMT offset and then alphabetically by region.

Accessing Time Zones:

Time zones can be accessed by:

• Iterating through the array until Posix == NULL
• Searching by description string
• Filtering by bUsCanada flag
• Matching against known POSIX strings

Complete Usage Example:

#include <timezones.h>
#include <ntp.h>
#include <string.h>
 
// List all available time zones
void ListTimeZones() {
    iprintf("Available Time Zones:\r\n");
    const TimeZoneRecord *tz = TZRecords;
    int index = 0;
    
    while (tz->Posix != NULL) {
        iprintf("%3d: %s\r\n", index, tz->Description);
        tz++;
        index++;
    }
}
 
// Find and set a specific time zone
bool SetTimeZoneByDescription(const char *searchStr) {
    const TimeZoneRecord *tz = TZRecords;
    
    while (tz->Posix != NULL) {
        if (strstr(tz->Description, searchStr) != NULL) {
            // Found matching time zone
            tzset(tz->Posix);
            iprintf("Time zone set to: %s\r\n", tz->Description);
            return true;
        }
        tz++;
    }
    
    iprintf("Time zone not found: %s\r\n", searchStr);
    return false;
}
 
// Get only US/Canada time zones
void ListUSTimeZones() {
    iprintf("US/Canada Time Zones:\r\n");
    const TimeZoneRecord *tz = TZRecords;
    
    while (tz->Posix != NULL) {
        if (tz->bUsCanada) {
            iprintf("  %s (%s)\r\n", tz->Short_name, tz->Description);
        }
        tz++;
    }
}
 
// Complete NTP + Time Zone setup
void SetupNetworkTime() {
    // Start NTP client
    if (SetTimeNTPServer("pool.ntp.org")) {
        iprintf("NTP synchronization started\r\n");
        
        // Wait for time sync
        while (!GetTimeNTPStatus()) {
            OSTimeDly(TICKS_PER_SECOND);
        }
        
        // Set time zone
        SetTimeZoneByDescription("Pacific Time");
        
        // Display current local time
        time_t now = time(NULL);
        struct tm *local = localtime(&now);
        iprintf("Current time: %02d:%02d:%02d\r\n", 
                local->tm_hour, local->tm_min, local->tm_sec);
    }
}

Note

The array is const and should not be modified at runtime

Always check for NULL termination when iterating

Time zone data is stored in flash/ROM and does not consume RAM