Time

Classes
struct	TimeZoneRecord
	Time zone record strucure. Provides an array of over 75 time zones in the TimeZoneRecord structure format. Time zones are described in \nburn\nbrtos\source\timezones.cpp. 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
	Pointer to provided system time zone records array.

Detailed Description

#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>

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