AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page User Manual Reference FAQ Example Projects

time.h

Go to the documentation of this file. 
011/*
022* (C)2012 Michael Duane Rice All rights reserved. 033* 044* Redistribution and use in source and binary forms, with or without 055* modification, are permitted provided that the following conditions are 066* met: 077* 088* Redistributions of source code must retain the above copyright notice, this 099* list of conditions and the following disclaimer. Redistributions in binary 1010* form must reproduce the above copyright notice, this list of conditions 1111* and the following disclaimer in the documentation and/or other materials 1212* provided with the distribution. Neither the name of the copyright holders 1313* nor the names of contributors may be used to endorse or promote products 1414* derived from this software without specific prior written permission. 1515* 1616* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 1717* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1818* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1919* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 2020* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 2121* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 2222* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 2323* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 2424* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 2525* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 2626* POSSIBILITY OF SUCH DAMAGE. 2727*/ 2828 2929/* $Id: time.h 2503 2016-02-07 22:59:47Z joerg_wunsch $ */ 3030 3131/** \file */ 3232 3333/** \defgroup avr_time <time.h>: Time 3434\code #include <time.h> \endcode 3535<h3>Introduction to the Time functions</h3> 3636This file declares the time functions implemented in \c avr-libc. 3737 3838The implementation aspires to conform with ISO/IEC 9899 (C90). However, due to limitations of the 3939target processor and the nature of its development environment, a practical implementation must 4040of necessity deviate from the standard. 4141 4242 4343 4444Section 7.23.2.1 clock() 4545The type clock_t, the macro CLOCKS_PER_SEC, and the function clock() are not implemented. We 4646consider these items belong to operating system code, or to application code when no operating 4747system is present. 4848 4949Section 7.23.2.3 mktime() 5050The standard specifies that mktime() should return (time_t) -1, if the time cannot be represented. 5151This implementation always returns a 'best effort' representation. 5252 5353Section 7.23.2.4 time() 5454The standard specifies that time() should return (time_t) -1, if the time is not available. 5555Since the application must initialize the time system, this functionality is not implemented. 5656 5757Section 7.23.2.2, difftime() 5858Due to the lack of a 64 bit double, the function difftime() returns a long integer. In most cases 5959this change will be invisible to the user, handled automatically by the compiler. 6060 6161Section 7.23.1.4 struct tm 6262Per the standard, struct tm->tm_isdst is greater than zero when Daylight Saving time is in effect. 6363This implementation further specifies that, when positive, the value of tm_isdst represents 6464the amount time is advanced during Daylight Saving time. 6565 6666Section 7.23.3.5 strftime() 6767Only the 'C' locale is supported, therefore the modifiers 'E' and 'O' are ignored. 6868The 'Z' conversion is also ignored, due to the lack of time zone name. 6969 7070In addition to the above departures from the standard, there are some behaviors which are different 7171from what is often expected, though allowed under the standard. 7272 7373There is no 'platform standard' method to obtain the current time, time zone, or 7474daylight savings 'rules' in the AVR environment. Therefore the application must initialize 7575the time system with this information. The functions set_zone(), set_dst(), and 7676set_system_time() are provided for initialization. Once initialized, system time is maintained by 7777calling the function system_tick() at one second intervals. 7878 7979Though not specified in the standard, it is often expected that time_t is a signed integer 8080representing an offset in seconds from Midnight Jan 1 1970... i.e. 'Unix time'. This implementation 8181uses an unsigned 32 bit integer offset from Midnight Jan 1 2000. The use of this 'epoch' helps to 8282simplify the conversion functions, while the 32 bit value allows time to be properly represented 8383until Tue Feb 7 06:28:15 2136 UTC. The macros UNIX_OFFSET and NTP_OFFSET are defined to assist in 8484converting to and from Unix and NTP time stamps. 8585 8686Unlike desktop counterparts, it is impractical to implement or maintain the 'zoneinfo' database. 8787Therefore no attempt is made to account for time zone, daylight saving, or leap seconds in past dates. 8888All calculations are made according to the currently configured time zone and daylight saving 'rule'. 8989 9090In addition to C standard functions, re-entrant versions of ctime(), asctime(), gmtime() and 9191localtime() are provided which, in addition to being re-entrant, have the property of claiming 9292less permanent storage in RAM. An additional time conversion, isotime() and its re-entrant version, 9393uses far less storage than either ctime() or asctime(). 9494 9595Along with the usual smattering of utility functions, such as is_leap_year(), this library includes 9696a set of functions related the sun and moon, as well as sidereal time functions. 9797*/ 9898 9999#ifndef TIME_H 100100#define TIME_H 101101 102102#ifdef __cplusplus 103103extern "C" { 104104#endif 105105 106106#include <inttypes.h> 107107#include <stdlib.h> 108108 109109/** \ingroup avr_time */ 110110/* @{ */ 111111 112112/** 113113time_t represents seconds elapsed from Midnight, Jan 1 2000 UTC (the Y2K 'epoch'). 114114Its range allows this implementation to represent time up to Tue Feb 7 06:28:15 2136 UTC. 115115*/ 116 116 typedef uint32_t time_t; 117117 118118/** 119119The time function returns the systems current time stamp. 120120If timer is not a null pointer, the return value is also assigned to the object it points to. 121121*/ 122122time_t time(time_t *timer); 123123 124124/** 125125The difftime function returns the difference between two binary time stamps, 126126time1 - time0. 127127*/ 128128int32_t difftime(time_t time1, time_t time0); 129129 130130 131131/** 132132The tm structure contains a representation of time 'broken down' into components of the 133133Gregorian calendar. 134134 135135The value of tm_isdst is zero if Daylight Saving Time is not in effect, and is negative if 136136the information is not available. 137137 138138When Daylight Saving Time is in effect, the value represents the number of 139139seconds the clock is advanced. 140140 141141See the set_dst() function for more information about Daylight Saving. 142142 143143*/ 144 144 struct tm { 145 145 int8_t tm_sec; /**< seconds after the minute - [ 0 to 59 ] */ 146 146 int8_t tm_min; /**< minutes after the hour - [ 0 to 59 ] */ 147 147 int8_t tm_hour; /**< hours since midnight - [ 0 to 23 ] */ 148 148 int8_t tm_mday; /**< day of the month - [ 1 to 31 ] */ 149 149 int8_t tm_wday; /**< days since Sunday - [ 0 to 6 ] */ 150 150 int8_t tm_mon; /**< months since January - [ 0 to 11 ] */ 151 151 int16_t tm_year; /**< years since 1900 */ 152 152 int16_t tm_yday; /**< days since January 1 - [ 0 to 365 ] */ 153 153 int16_t tm_isdst; /**< Daylight Saving Time flag */ 154154}; 155155 156156#ifndef __DOXYGEN__ 157157/* We have to provide clock_t / CLOCKS_PER_SEC so that libstdc++-v3 can 158158be built. We define CLOCKS_PER_SEC via a symbol _CLOCKS_PER_SEC_ 159159so that the user can provide the value on the link line, which should 160160result in little or no run-time overhead compared with a constant. */ 161161typedef unsigned long clock_t; 162162extern char *_CLOCKS_PER_SEC_; 163163#define CLOCKS_PER_SEC ((clock_t) _CLOCKS_PER_SEC_) 164164extern clock_t clock(void); 165165#endif /* !__DOXYGEN__ */ 166166 167167/** 168168This function 'compiles' the elements of a broken-down time structure, returning a binary time stamp. 169169The elements of timeptr are interpreted as representing Local Time. 170170 171171The original values of the tm_wday and tm_yday elements of the structure are ignored, 172172and the original values of the other elements are not restricted to the ranges stated for struct tm. 173173 174174On successful completion, the values of all elements of timeptr are set to the appropriate range. 175175*/ 176176time_t mktime(struct tm * timeptr); 177177 178178/** 179179This function 'compiles' the elements of a broken-down time structure, returning a binary time stamp. 180180The elements of timeptr are interpreted as representing UTC. 181181 182182The original values of the tm_wday and tm_yday elements of the structure are ignored, 183183and the original values of the other elements are not restricted to the ranges stated for struct tm. 184184 185185Unlike mktime(), this function DOES NOT modify the elements of timeptr. 186186*/ 187187time_t mk_gmtime(const struct tm * timeptr); 188188 189189/** 190190The gmtime function converts the time stamp pointed to by timer into broken-down time, 191191expressed as UTC. 192192*/ 193193struct tm *gmtime(const time_t * timer); 194194 195195/** 196196Re entrant version of gmtime(). 197197*/ 198198void gmtime_r(const time_t * timer, struct tm * timeptr); 199199 200200/** 201201The localtime function converts the time stamp pointed to by timer into broken-down time, 202202expressed as Local time. 203203*/ 204204struct tm *localtime(const time_t * timer); 205205 206206/** 207207Re entrant version of localtime(). 208208*/ 209209void localtime_r(const time_t * timer, struct tm * timeptr); 210210 211211/** 212212The asctime function converts the broken-down time of timeptr, into an ascii string in the form 213213 214214Sun Mar 23 01:03:52 2013 215215*/ 216216char *asctime(const struct tm * timeptr); 217217 218218/** 219219Re entrant version of asctime(). 220220*/ 221221void asctime_r(const struct tm * timeptr, char *buf); 222222 223223/** 224224The ctime function is equivalent to asctime(localtime(timer)) 225225*/ 226226char *ctime(const time_t * timer); 227227 228228/** 229229Re entrant version of ctime(). 230230*/ 231231void ctime_r(const time_t * timer, char *buf); 232232 233233/** 234234The isotime function constructs an ascii string in the form 235235\code2013-03-23 01:03:52\endcode 236236*/ 237237char *isotime(const struct tm * tmptr); 238238 239239/** 240240Re entrant version of isotime() 241241*/ 242242void isotime_r(const struct tm *, char *); 243243 244244/** 245245A complete description of strftime() is beyond the pale of this document. 246246Refer to ISO/IEC document 9899 for details. 247247 248248All conversions are made using the 'C Locale', ignoring the E or O modifiers. Due to the lack of 249249a time zone 'name', the 'Z' conversion is also ignored. 250250*/ 251251size_t strftime(char *s, size_t maxsize, const char *format, const struct tm * timeptr); 252252 253253/** 254254Specify the Daylight Saving function. 255255 256256The Daylight Saving function should examine its parameters to determine whether 257257Daylight Saving is in effect, and return a value appropriate for tm_isdst. 258258 259259Working examples for the USA and the EU are available.. 260260 261261\code #include <util/eu_dst.h>\endcode 262262for the European Union, and 263263\code #include <util/usa_dst.h>\endcode 264264for the United States 265265 266266If a Daylight Saving function is not specified, the system will ignore Daylight Saving. 267267*/ 268268void set_dst(int (*) (const time_t *, int32_t *)); 269269 270270/** 271271Set the 'time zone'. The parameter is given in seconds East of the Prime Meridian. 272272Example for New York City: 273273\code set_zone(-5 * ONE_HOUR);\endcode 274274 275275If the time zone is not set, the time system will operate in UTC only. 276276*/ 277277void set_zone(int32_t); 278278 279279/** 280280Initialize the system time. Examples are... 281281 282282From a Clock / Calendar type RTC: 283283\code 284284struct tm rtc_time; 285285 286286read_rtc(&rtc_time); 287287rtc_time.tm_isdst = 0; 288288set_system_time( mktime(&rtc_time) ); 289289\endcode 290290 291291From a Network Time Protocol time stamp: 292292\code 293293set_system_time(ntp_timestamp - NTP_OFFSET); 294294\endcode 295295 296296From a UNIX time stamp: 297297\code 298298set_system_time(unix_timestamp - UNIX_OFFSET); 299299\endcode 300300 301301*/ 302302void set_system_time(time_t timestamp); 303303 304304/** 305305Maintain the system time by calling this function at a rate of 1 Hertz. 306306 307307It is anticipated that this function will typically be called from within an 308308Interrupt Service Routine, (though that is not required). It therefore includes code which 309309makes it simple to use from within a 'Naked' ISR, avoiding the cost of saving and restoring 310310all the cpu registers. 311311 312312Such an ISR may resemble the following example... 313313\code 314314ISR(RTC_OVF_vect, ISR_NAKED) 315315{ 316316system_tick(); 317317reti(); 318318} 319319\endcode 320320*/ 321321void system_tick(void); 322322 323323/** 324324Enumerated labels for the days of the week. 325325*/ 326 326 enum _WEEK_DAYS_ { 327327SUNDAY, 328328MONDAY, 329329TUESDAY, 330330WEDNESDAY, 331331THURSDAY, 332332FRIDAY, 333333SATURDAY 334334}; 335335 336336/** 337337Enumerated labels for the months. 338338*/ 339 339 enum _MONTHS_ { 340340JANUARY, 341341FEBRUARY, 342342MARCH, 343343APRIL, 344344MAY, 345345JUNE, 346346JULY, 347347AUGUST, 348348SEPTEMBER, 349349OCTOBER, 350350NOVEMBER, 351351DECEMBER 352352}; 353353 354354/** 355355Return 1 if year is a leap year, zero if it is not. 356356*/ 357357uint8_t is_leap_year(int16_t year); 358358 359359/** 360360Return the length of month, given the year and month, where month is in the range 1 to 12. 361361*/ 362362uint8_t month_length(int16_t year, uint8_t month); 363363 364364/** 365365Return the calendar week of year, where week 1 is considered to begin on the 366366day of week specified by 'start'. The returned value may range from zero to 52. 367367*/ 368368uint8_t week_of_year(const struct tm * timeptr, uint8_t start); 369369 370370/** 371371Return the calendar week of month, where the first week is considered to begin on the 372372day of week specified by 'start'. The returned value may range from zero to 5. 373373*/ 374374uint8_t week_of_month(const struct tm * timeptr, uint8_t start); 375375 376376/** 377377Structure which represents a date as a year, week number of that year, and day of week. 378378See http://en.wikipedia.org/wiki/ISO_week_date for more information. 379379*/ 380 380 struct week_date { 381 381 int year; /**< year number (Gregorian calendar) */ 382 382 int week; /**< week number (#1 is where first Thursday is in) */ 383 383 int day; /**< day within week */ 384384}; 385385 386386/** 387387Return a week_date structure with the ISO_8601 week based date corresponding to the given 388388year and day of year. See http://en.wikipedia.org/wiki/ISO_week_date for more 389389information. 390390*/ 391391struct week_date * iso_week_date( int year, int yday); 392392 393393/** 394394Re-entrant version of iso-week_date. 395395*/ 396396void iso_week_date_r( int year, int yday, struct week_date *); 397397 398398/** 399399Convert a Y2K time stamp into a FAT file system time stamp. 400400*/ 401401uint32_t fatfs_time(const struct tm * timeptr); 402402 403403/** One hour, expressed in seconds */ 404 404#define ONE_HOUR 3600 405405 406406/** Angular degree, expressed in arc seconds */ 407 407#define ONE_DEGREE 3600 408408 409409/** One day, expressed in seconds */ 410 410#define ONE_DAY 86400 411411 412412/** Difference between the Y2K and the UNIX epochs, in seconds. To convert a Y2K 413413timestamp to UNIX... 414414\code 415415long unix; 416416time_t y2k; 417417 418418y2k = time(NULL); 419419unix = y2k + UNIX_OFFSET; 420420\endcode 421421*/ 422 422#define UNIX_OFFSET 946684800 423423 424424/** Difference between the Y2K and the NTP epochs, in seconds. To convert a Y2K 425425timestamp to NTP... 426426\code 427427unsigned long ntp; 428428time_t y2k; 429429 430430y2k = time(NULL); 431431ntp = y2k + NTP_OFFSET; 432432\endcode 433433*/ 434 434#define NTP_OFFSET 3155673600 435435 436436/* 437437* =================================================================== 438438* Ephemera 439439*/ 440440 441441/** 442442Set the geographic coordinates of the 'observer', for use with several of the 443443following functions. Parameters are passed as seconds of North Latitude, and seconds 444444of East Longitude. 445445 446446For New York City... 447447\code set_position( 40.7142 * ONE_DEGREE, -74.0064 * ONE_DEGREE); \endcode 448448*/ 449449void set_position(int32_t latitude, int32_t longitude); 450450 451451/** 452452Computes the difference between apparent solar time and mean solar time. 453453The returned value is in seconds. 454454*/ 455455int16_t equation_of_time(const time_t * timer); 456456 457457/** 458458Computes the amount of time the sun is above the horizon, at the location of the observer. 459459 460460NOTE: At observer locations inside a polar circle, this value can be zero during the winter, 461461and can exceed ONE_DAY during the summer. 462462 463463The returned value is in seconds. 464464*/ 465465int32_t daylight_seconds(const time_t * timer); 466466 467467/** 468468Computes the time of solar noon, at the location of the observer. 469469*/ 470470time_t solar_noon(const time_t * timer); 471471 472472/** 473473Return the time of sunrise, at the location of the observer. See the note about daylight_seconds(). 474474*/ 475475time_t sun_rise(const time_t * timer); 476476 477477/** 478478Return the time of sunset, at the location of the observer. See the note about daylight_seconds(). 479479*/ 480480time_t sun_set(const time_t * timer); 481481 482482/** Returns the declination of the sun in radians. */ 483483double solar_declination(const time_t * timer); 484484 485485/** 486486Returns an approximation to the phase of the moon. 487487The sign of the returned value indicates a waning or waxing phase. 488488The magnitude of the returned value indicates the percentage illumination. 489489*/ 490490int8_t moon_phase(const time_t * timer); 491491 492492/** 493493Returns Greenwich Mean Sidereal Time, as seconds into the sidereal day. 494494The returned value will range from 0 through 86399 seconds. 495495*/ 496496unsigned long gm_sidereal(const time_t * timer); 497497 498498/** 499499Returns Local Mean Sidereal Time, as seconds into the sidereal day. 500500The returned value will range from 0 through 86399 seconds. 501501*/ 502502unsigned long lm_sidereal(const time_t * timer); 503503 504504/* @} */ 505505#ifdef __cplusplus 506506} 507507#endif 508508 509509#endif /* TIME_H */

tm::tm_mday int8_t tm_mday

Definition: time.h:148

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

Definition: isotime_r.c:41

set_zone void set_zone(int32_t)

ctime char * ctime(const time_t *timer)

Definition: ctime.c:40

_MONTHS_ _MONTHS_

Definition: time.h:339

tm::tm_min int8_t tm_min

Definition: time.h:146

difftime int32_t difftime(time_t time1, time_t time0)

Definition: difftime.c:38

moon_phase int8_t moon_phase(const time_t *timer)

Definition: moon_phase.c:40

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

Definition: iso_week_date.c:44

tm::tm_yday int16_t tm_yday

Definition: time.h:152

tm::tm_isdst int16_t tm_isdst

Definition: time.h:153

gm_sidereal unsigned long gm_sidereal(const time_t *timer)

Definition: gm_sidereal.c:49

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

Definition: asctime_r.c:49

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

Definition: week_of_month.c:42

lm_sidereal unsigned long lm_sidereal(const time_t *timer)

Definition: lm_sidereal.c:39

week_date::week int week

Definition: time.h:382

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

Definition: ctime_r.c:37

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

Definition: iso_week_date_r.c:49

mk_gmtime time_t mk_gmtime(const struct tm *timeptr)

Definition: mk_gmtime.c:40

int16_t signed int int16_t

Definition: stdint.h:88

int8_t signed char int8_t

Definition: stdint.h:78

week_date::day int day

Definition: time.h:383

solar_noon time_t solar_noon(const time_t *timer)

Definition: solar_noon.c:40

sun_set time_t sun_set(const time_t *timer)

Definition: sun_set.c:38

solar_declination double solar_declination(const time_t *timer)

Definition: solar_declination.c:50

tm::tm_year int16_t tm_year

Definition: time.h:151

tm::tm_sec int8_t tm_sec

Definition: time.h:145

int32_t signed long int int32_t

Definition: stdint.h:98

tm::tm_hour int8_t tm_hour

Definition: time.h:147

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

Definition: week_of_year.c:42

isotime char * isotime(const struct tm *tmptr)

Definition: isotime.c:40

equation_of_time int16_t equation_of_time(const time_t *timer)

Definition: equation_of_time.c:54

uint8_t unsigned char uint8_t

Definition: stdint.h:83

week_date> Definition: time.h:380

tm::tm_wday int8_t tm_wday

Definition: time.h:149

uint32_t unsigned long int uint32_t

Definition: stdint.h:103

inttypes.h

tm> Definition: time.h:144

sun_rise time_t sun_rise(const time_t *timer)

Definition: sun_rise.c:38

_WEEK_DAYS_ _WEEK_DAYS_

Definition: time.h:326

set_position void set_position(int32_t latitude, int32_t longitude)

mktime time_t mktime(struct tm *timeptr)

Definition: mktime.c:43

is_leap_year uint8_t is_leap_year(int16_t year)

month_length uint8_t month_length(int16_t year, uint8_t month)

tm::tm_mon int8_t tm_mon

Definition: time.h:150

time time_t time(time_t *timer)

Definition: time.c:41

time_t uint32_t time_t

Definition: time.h:116

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

Definition: set_dst.c:41

asctime char * asctime(const struct tm *timeptr)

Definition: asctime.c:40

week_date::year int year

Definition: time.h:381

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

Definition: gmtime_r.c:38

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

Definition: strftime.c:87

set_system_time void set_system_time(time_t timestamp)

Definition: set_system_time.c:42

fatfs_time uint32_t fatfs_time(const struct tm *timeptr)

stdlib.h

daylight_seconds int32_t daylight_seconds(const time_t *timer)

Definition: daylight_seconds.c:43

localtime struct tm * localtime(const time_t *timer)

Definition: localtime.c:40

gmtime struct tm * gmtime(const time_t *timer)

Definition: gmtime.c:41

system_tick void system_tick(void)

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

Definition: localtime_r.c:43