Data Structures¶

Macros¶

Typedefs¶

Enumerations¶

Functions¶

Introduction to the Time functions¶

The implementation aspires to conform with ISO/IEC 9899 (C90). However, due to limitations of the target processor and the nature of its development environment, a practical implementation must of necessity deviate from the standard.

Section 7.23.2.1 clock() The type clock_t, the macro CLOCKS_PER_SEC, and the function clock() are not implemented. We consider these items belong to operating system code, or to application code when no operating system is present.

Section 7.23.2.3 mktime() The standard specifies that mktime() should return (time_t) -1, if the time cannot be represented. This implementation always returns a 'best effort' representation.

Section 7.23.2.4 time() The standard specifies that time() should return (time_t) -1, if the time is not available. Since the application must initialize the time system, this functionality is not implemented.

Section 7.23.2.2, difftime() Due to the lack of a 64 bit double, the function difftime() returns a long integer. In most cases this change will be invisible to the user, handled automatically by the compiler.

Section 7.23.1.4 struct tm Per the standard, struct tm->tm_isdst is greater than zero when Daylight Saving time is in effect. This implementation further specifies that, when positive, the value of tm_isdst represents the amount time is advanced during Daylight Saving time.

Section 7.23.3.5 strftime() Only the 'C' locale is supported, therefore the modifiers 'E' and 'O' are ignored. The 'Z' conversion is also ignored, due to the lack of time zone name.

In addition to the above departures from the standard, there are some behaviors which are different from what is often expected, though allowed under the standard.

There is no 'platform standard' method to obtain the current time, time zone, or daylight savings 'rules' in the AVR environment. Therefore the application must initialize the time system with this information. The functions set_zone(), set_dst(), and set_system_time() are provided for initialization. Once initialized, system time is maintained by calling the function system_tick() at one second intervals.

Though not specified in the standard, it is often expected that time_t is a signed integer representing an offset in seconds from Midnight Jan 1 1970... i.e. 'Unix time'. This implementation uses an unsigned 32 bit integer offset from Midnight Jan 1 2000. The use of this 'epoch' helps to simplify the conversion functions, while the 32 bit value allows time to be properly represented until Tue Feb 7 06:28:15 2136 UTC. The macros UNIX_OFFSET and NTP_OFFSET are defined to assist in converting to and from Unix and NTP time stamps.

Unlike desktop counterparts, it is impractical to implement or maintain the 'zoneinfo' database. Therefore no attempt is made to account for time zone, daylight saving, or leap seconds in past dates. All calculations are made according to the currently configured time zone and daylight saving 'rule'.

In addition to C standard functions, re-entrant versions of ctime(), asctime(), gmtime() and localtime() are provided which, in addition to being re-entrant, have the property of claiming less permanent storage in RAM. An additional time conversion, isotime() and its re-entrant version, uses far less storage than either ctime() or asctime().

Along with the usual smattering of utility functions, such as is_leap_year(), this library includes a set of functions related the sun and moon, as well as sidereal time functions.

#define NTP_OFFSET 3155673600¶

unsigned long ntp;
time_t y2k;
y2k = time(NULL);
ntp = y2k + NTP_OFFSET;

#define ONE_DAY 86400¶

#define ONE_DEGREE 3600¶

#define ONE_HOUR 3600¶

#define UNIX_OFFSET 946684800¶

long unix;
time_t y2k;
y2k = time(NULL);
unix = y2k + UNIX_OFFSET;

typedef uint32_t time_t¶

enum _MONTHS_¶

enum _WEEK_DAYS_¶

char* asctime (const struct tm * timeptr)¶

Sun Mar 23 01:03:52 2013

void asctime_r (const struct tm * timeptr, char * buf)¶

char* ctime (const time_t * timer)¶

void ctime_r (const time_t * timer, char * buf)¶

int32_t daylight_seconds (const time_t * timer)¶

NOTE: At observer locations inside a polar circle, this value can be zero during the winter, and can exceed ONE_DAY during the summer.

The returned value is in seconds.

int32_t difftime (time_t time1, time_t time0)¶

int16_t equation_of_time (const time_t * timer)¶

uint32_t fatfs_time (const struct tm * timeptr)¶

unsigned long gm_sidereal (const time_t * timer)¶

struct tm* gmtime (const time_t * timer)¶

void gmtime_r (const time_t * timer, struct tm * timeptr)¶

uint8_t is_leap_year (int16_t year)¶

struct week_date* iso_week_date (int year, int yday)¶

void iso_week_date_r (int year, int yday, struct week_date *)¶

char* isotime (const struct tm * tmptr)¶

2013-03-23 01:03:52

void isotime_r (const struct tm *, char *)¶

unsigned long lm_sidereal (const time_t * timer)¶

struct tm* localtime (const time_t * timer)¶

void localtime_r (const time_t * timer, struct tm * timeptr)¶

time_t mk_gmtime (const struct tm * timeptr)¶

The original values of the tm_wday and tm_yday elements of the structure are ignored, and the original values of the other elements are not restricted to the ranges stated for struct tm.

Unlike mktime(), this function DOES NOT modify the elements of timeptr.

time_t mktime (struct tm * timeptr)¶

The original values of the tm_wday and tm_yday elements of the structure are ignored, and the original values of the other elements are not restricted to the ranges stated for struct tm.

On successful completion, the values of all elements of timeptr are set to the appropriate range.

uint8_t month_length (int16_t year, uint8_t month)¶

int8_t moon_phase (const time_t * timer)¶

void set_dst (int(*)(const time_t *, int32_t *))¶

The Daylight Saving function should examine its parameters to determine whether Daylight Saving is in effect, and return a value appropriate for tm_isdst.

Working examples for the USA and the EU are available..

#include <util/eu_dst.h>

for the European Union, and

#include <util/usa_dst.h>

for the United States

If a Daylight Saving function is not specified, the system will ignore Daylight Saving.

void set_position (int32_t latitude, int32_t longitude)¶

For New York City...

set_position( 40.7142 * ONE_DEGREE, -74.0064 * ONE_DEGREE); 

void set_system_time (time_t timestamp)¶

From a Clock / Calendar type RTC:

struct tm rtc_time;
read_rtc(&rtc_time);
rtc_time.tm_isdst = 0;
set_system_time( mktime(&rtc_time) );

From a Network Time Protocol time stamp:

set_system_time(ntp_timestamp - NTP_OFFSET);

From a UNIX time stamp:

set_system_time(unix_timestamp - UNIX_OFFSET);

void set_zone (int32_t)¶

set_zone(-5 * ONE_HOUR);

If the time zone is not set, the time system will operate in UTC only.

double solar_declination (const time_t * timer)¶

time_t solar_noon (const time_t * timer)¶

size_t strftime (char * s, size_t maxsize, const char * format, const struct tm * timeptr)¶

All conversions are made using the 'C Locale', ignoring the E or O modifiers. Due to the lack of a time zone 'name', the 'Z' conversion is also ignored.

time_t sun_rise (const time_t * timer)¶

time_t sun_set (const time_t * timer)¶

void system_tick (void)¶

It is anticipated that this function will typically be called from within an Interrupt Service Routine, (though that is not required). It therefore includes code which makes it simple to use from within a 'Naked' ISR, avoiding the cost of saving and restoring all the cpu registers.

Such an ISR may resemble the following example...

ISR(RTC_OVF_vect, ISR_NAKED)
{
    system_tick();
    reti();
}

time_t time (time_t * timer)¶

uint8_t week_of_month (const struct tm * timeptr, uint8_t start)¶

uint8_t week_of_year (const struct tm * timeptr, uint8_t start)¶