AVR-LibC  2.2.0
Standard C library for AVR-GCC
 

AVR-LibC Documentation

Logo

AVR-LibC Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

File List

Loading...
Searching...
No Matches
time.h
Go to the documentation of this file.
1/*
2 * (C)2012 Michael Duane Rice All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
6 * met:
7 *
8 * Redistributions of source code must retain the above copyright notice, this
9 * list of conditions and the following disclaimer. Redistributions in binary
10 * form must reproduce the above copyright notice, this list of conditions
11 * and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution. Neither the name of the copyright holders
13 * nor the names of contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/* $Id$ */
30
31#ifndef TIME_H
32#define TIME_H
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38#include <stdint.h>
39#include <stdlib.h>
40
41/** \file */
42
43/** \defgroup avr_time <time.h>: Time
44 \code #include <time.h> \endcode
45 <h3>Introduction to the Time functions</h3>
46 This file declares the time functions implemented in AVR-LibC.
47
48 The implementation aspires to conform with ISO/IEC 9899 (C90). However, due to limitations of the
49 target processor and the nature of its development environment, a practical implementation must
50 of necessity deviate from the standard.
51
52 Section 7.23.2.1 clock()
53 The type clock_t, the macro CLOCKS_PER_SEC, and the function clock() are not implemented. We
54 consider these items belong to operating system code, or to application code when no operating
55 system is present.
56
57 Section 7.23.2.3 mktime()
58 The standard specifies that mktime() should return (time_t) -1, if the time cannot be represented.
59 This implementation always returns a 'best effort' representation.
60
61 Section 7.23.2.4 time()
62 The standard specifies that time() should return (time_t) -1, if the time is not available.
63 Since the application must initialize the time system, this functionality is not implemented.
64
65 Section 7.23.2.2, difftime()
66 Due to the lack of a 64 bit double, the function difftime() returns a long integer. In most cases
67 this change will be invisible to the user, handled automatically by the compiler.
68
69 Section 7.23.1.4 struct tm
70 Per the standard, struct tm->tm_isdst is greater than zero when Daylight Saving time is in effect.
71 This implementation further specifies that, when positive, the value of tm_isdst represents
72 the amount time is advanced during Daylight Saving time.
73
74 Section 7.23.3.5 strftime()
75 Only the 'C' locale is supported, therefore the modifiers 'E' and 'O' are ignored.
76 The 'Z' conversion is also ignored, due to the lack of time zone name.
77
78 In addition to the above departures from the standard, there are some behaviors which are different
79 from what is often expected, though allowed under the standard.
80
81 There is no 'platform standard' method to obtain the current time, time zone, or
82 daylight savings 'rules' in the AVR environment. Therefore the application must initialize
83 the time system with this information. The functions set_zone(), set_dst(), and
84 set_system_time() are provided for initialization. Once initialized, system time is maintained by
85 calling the function system_tick() at one second intervals.
86
87 Though not specified in the standard, it is often expected that time_t is a signed integer
88 representing an offset in seconds from Midnight Jan 1 1970... i.e. 'Unix time'. This implementation
89 uses an unsigned 32 bit integer offset from Midnight Jan 1 2000. The use of this 'epoch' helps to
90 simplify the conversion functions, while the 32 bit value allows time to be properly represented
91 until Tue Feb 7 06:28:15 2136 UTC. The macros UNIX_OFFSET and NTP_OFFSET are defined to assist in
92 converting to and from Unix and NTP time stamps.
93
94 Unlike desktop counterparts, it is impractical to implement or maintain the 'zoneinfo' database.
95 Therefore no attempt is made to account for time zone, daylight saving, or leap seconds in past dates.
96 All calculations are made according to the currently configured time zone and daylight saving 'rule'.
97
98 In addition to C standard functions, re-entrant versions of ctime(), asctime(), gmtime() and
99 localtime() are provided which, in addition to being re-entrant, have the property of claiming
100 less permanent storage in RAM. An additional time conversion, isotime() and its re-entrant version,
101 uses far less storage than either ctime() or asctime().
102
103 Along with the usual smattering of utility functions, such as is_leap_year(), this library includes
104 a set of functions related the sun and moon, as well as sidereal time functions.
105*/
106
107/** \ingroup avr_time */
108/**@{*/
109
110/**
111 time_t represents seconds elapsed from Midnight, Jan 1 2000 UTC (the Y2K 'epoch').
112 Its range allows this implementation to represent time up to Tue Feb 7 06:28:15 2136 UTC.
113*/
115
116/**
117 The time function returns the systems current time stamp.
118 If timer is not a null pointer, the return value is also assigned to the object it points to.
119*/
120time_t time(time_t *timer);
121
122/**
123 The difftime function returns the difference between two binary time stamps,
124 time1 - time0.
125*/
126int32_t difftime(time_t time1, time_t time0);
127
128
129/**
130 The tm structure contains a representation of time 'broken down' into components of the
131 Gregorian calendar.
132
133 The value of tm_isdst is zero if Daylight Saving Time is not in effect, and is negative if
134 the information is not available.
135
136 When Daylight Saving Time is in effect, the value represents the number of
137 seconds the clock is advanced.
138
139 See the set_dst() function for more information about Daylight Saving.
140*/
141struct tm {
142 int8_t tm_sec; /**< seconds after the minute - [ 0 to 59 ] */
143 int8_t tm_min; /**< minutes after the hour - [ 0 to 59 ] */
144 int8_t tm_hour; /**< hours since midnight - [ 0 to 23 ] */
145 int8_t tm_mday; /**< day of the month - [ 1 to 31 ] */
146 int8_t tm_wday; /**< days since Sunday - [ 0 to 6 ] */
147 int8_t tm_mon; /**< months since January - [ 0 to 11 ] */
148 int16_t tm_year; /**< years since 1900 */
149 int16_t tm_yday; /**< days since January 1 - [ 0 to 365 ] */
150 int16_t tm_isdst; /**< Daylight Saving Time flag */
151};
152
153#ifndef __DOXYGEN__
154/* We have to provide clock_t / CLOCKS_PER_SEC so that libstdc++-v3 can
155 be built. We define CLOCKS_PER_SEC via a symbol _CLOCKS_PER_SEC_
156 so that the user can provide the value on the link line, which should
157 result in little or no run-time overhead compared with a constant. */
158typedef unsigned long clock_t;
159extern char *_CLOCKS_PER_SEC_;
160#define CLOCKS_PER_SEC ((clock_t) _CLOCKS_PER_SEC_)
161extern clock_t clock(void);
162#endif /* !__DOXYGEN__ */
163
164/**
165 This function 'compiles' the elements of a broken-down time structure, returning a binary time stamp.
166 The elements of timeptr are interpreted as representing Local Time.
167
168 The original values of the tm_wday and tm_yday elements of the structure are ignored,
169 and the original values of the other elements are not restricted to the ranges stated for struct tm.
170
171 The element tm_isdst is used for input and output. If set to 0 or a positive value on input, this
172 requests calculation for Daylight Savings Time being off or on, respectively. If set to a negative
173 value on input, it requests calculation to return whether Daylight Savings Time is in effect or
174 not according to the other values.
175
176 On successful completion, the values of all elements of timeptr are set to the appropriate range.
177*/
178time_t mktime(struct tm * timeptr);
179
180/**
181 This function 'compiles' the elements of a broken-down time structure, returning a binary time stamp.
182 The elements of timeptr are interpreted as representing UTC.
183
184 The original values of the tm_wday and tm_yday elements of the structure are ignored,
185 and the original values of the other elements are not restricted to the ranges stated for struct tm.
186
187 Unlike mktime(), this function DOES NOT modify the elements of timeptr.
188*/
189time_t mk_gmtime(const struct tm * timeptr);
190
191/**
192 The gmtime function converts the time stamp pointed to by timer into broken-down time,
193 expressed as UTC.
194*/
195struct tm *gmtime(const time_t * timer);
196
197/**
198 Re entrant version of gmtime().
199*/
200void gmtime_r(const time_t * timer, struct tm * timeptr);
201
202/**
203 The localtime function converts the time stamp pointed to by timer into broken-down time,
204 expressed as Local time.
205*/
206struct tm *localtime(const time_t * timer);
207
208/**
209 Re entrant version of localtime().
210*/
211void localtime_r(const time_t * timer, struct tm * timeptr);
212
213/**
214 The asctime function converts the broken-down time of timeptr, into an ascii string in the form
215
216 Sun Mar 23 01:03:52 2013
217*/
218char *asctime(const struct tm * timeptr);
219
220/**
221 Re entrant version of asctime().
222*/
223void asctime_r(const struct tm * timeptr, char *buf);
224
225/**
226 The ctime function is equivalent to asctime(localtime(timer))
227*/
228char *ctime(const time_t * timer);
229
230/**
231 Re entrant version of ctime().
232*/
233void ctime_r(const time_t * timer, char *buf);
234
235/**
236The isotime function constructs an ascii string in the form
237 \code2013-03-23 01:03:52\endcode
238*/
239char *isotime(const struct tm * tmptr);
240
241/**
242 Re entrant version of isotime()
243*/
244void isotime_r(const struct tm *, char *);
245
246/**
247 A complete description of strftime() is beyond the pale of this document.
248 Refer to ISO/IEC document 9899 for details.
249
250 All conversions are made using the 'C Locale', ignoring the E or O modifiers. Due to the lack of
251 a time zone 'name', the 'Z' conversion is also ignored.
252*/
253size_t strftime(char *s, size_t maxsize, const char *format, const struct tm * timeptr);
254
255/**
256 Specify the Daylight Saving function.
257
258 The Daylight Saving function should examine its parameters to determine whether
259 Daylight Saving is in effect, and return a value appropriate for tm_isdst.
260
261 Working examples for the USA and the EU are available..
262
263 \code #include <util/eu_dst.h>\endcode
264 for the European Union, and
265 \code #include <util/usa_dst.h>\endcode
266 for the United States
267
268 If a Daylight Saving function is not specified, the system will ignore Daylight Saving.
269*/
270void set_dst(int (*) (const time_t *, int32_t *));
271
272/**
273 Set the 'time zone'. The parameter is given in seconds East of the Prime Meridian.
274 Example for New York City:
275 \code set_zone(-5 * ONE_HOUR);\endcode
276
277 If the time zone is not set, the time system will operate in UTC only.
278*/
280
281/**
282 Initialize the system time. Examples are...
283
284 From a Clock / Calendar type RTC:
285 \code
286 struct tm rtc_time;
287
288 read_rtc(&rtc_time);
289 rtc_time.tm_isdst = 0;
290 set_system_time( mktime(&rtc_time) );
291 \endcode
292
293 From a Network Time Protocol time stamp:
294 \code
295 set_system_time(ntp_timestamp - NTP_OFFSET);
296 \endcode
297
298 From a UNIX time stamp:
299 \code
300 set_system_time(unix_timestamp - UNIX_OFFSET);
301 \endcode
302
303*/
304void set_system_time(time_t timestamp);
305
306/**
307 Maintain the system time by calling this function at a rate of 1 Hertz.
308
309 It is anticipated that this function will typically be called from within an
310 Interrupt Service Routine, (though that is not required). It therefore includes code which
311 makes it simple to use from within a 'Naked' ISR, avoiding the cost of saving and restoring
312 all the cpu registers.
313
314 Such an ISR may resemble the following example...
315 \code
316 ISR(RTC_OVF_vect, ISR_NAKED)
317 {
318 system_tick();
319 reti();
320 }
321 \endcode
322*/
323void system_tick(void);
324
325/**
326 Enumerated labels for the days of the week.
327*/
329 SUNDAY,
330 MONDAY,
331 TUESDAY,
332 WEDNESDAY,
333 THURSDAY,
334 FRIDAY,
335 SATURDAY
336};
337
338/**
339 Enumerated labels for the months.
340*/
342 JANUARY,
343 FEBRUARY,
344 MARCH,
345 APRIL,
346 MAY,
347 JUNE,
348 JULY,
349 AUGUST,
350 SEPTEMBER,
351 OCTOBER,
352 NOVEMBER,
353 DECEMBER
354};
355
356/**
357 Return 1 if year is a leap year, zero if it is not.
358*/
360
361/**
362 Return the length of month, given the year and month, where month is in the range 1 to 12.
363*/
365
366/**
367 Return the calendar week of year, where week 1 is considered to begin on the
368 day of week specified by 'start'. The returned value may range from zero to 52.
369*/
370uint8_t week_of_year(const struct tm * timeptr, uint8_t start);
371
372/**
373 Return the calendar week of month, where the first week is considered to begin on the
374 day of week specified by 'start'. The returned value may range from zero to 5.
375*/
376uint8_t week_of_month(const struct tm * timeptr, uint8_t start);
377
378/**
379 Structure which represents a date as a year, week number of that year, and day of week.
380 See http://en.wikipedia.org/wiki/ISO_week_date for more information.
381*/
382struct week_date {
383 int year; /**< year number (Gregorian calendar) */
384 int week; /**< week number (#1 is where first Thursday is in) */
385 int day; /**< day within week */
386};
387
388/**
389 Return a week_date structure with the ISO_8601 week based date corresponding to the given
390 year and day of year. See http://en.wikipedia.org/wiki/ISO_week_date for more
391 information.
392*/
393struct week_date * iso_week_date( int year, int yday);
394
395/**
396 Re-entrant version of iso-week_date.
397*/
398void iso_week_date_r( int year, int yday, struct week_date *);
399
400/**
401 Convert a Y2K time stamp into a FAT file system time stamp.
402*/
403uint32_t fatfs_time(const struct tm * timeptr);
404
405/** One hour, expressed in seconds */
406#define ONE_HOUR 3600
407
408/** Angular degree, expressed in arc seconds */
409#define ONE_DEGREE 3600
410
411/** One day, expressed in seconds */
412#define ONE_DAY 86400
413
414/** Difference between the Y2K and the UNIX epochs, in seconds. To convert a Y2K
415 timestamp to UNIX...
416 \code
417 long unix;
418 time_t y2k;
419
420 y2k = time(NULL);
421 unix = y2k + UNIX_OFFSET;
422 \endcode
423*/
424#define UNIX_OFFSET 946684800
425
426/** Difference between the Y2K and the NTP epochs, in seconds. To convert a Y2K
427 timestamp to NTP...
428 \code
429 unsigned long ntp;
430 time_t y2k;
431
432 y2k = time(NULL);
433 ntp = y2k + NTP_OFFSET;
434 \endcode
435*/
436#define NTP_OFFSET 3155673600
437
438/*
439 * ===================================================================
440 * Ephemera
441 */
442
443/**
444 Set the geographic coordinates of the 'observer', for use with several of the
445 following functions. Parameters are passed as seconds of North Latitude, and seconds
446 of East Longitude.
447
448 For New York City...
449 \code set_position( 40.7142 * ONE_DEGREE, -74.0064 * ONE_DEGREE); \endcode
450*/
451void set_position(int32_t latitude, int32_t longitude);
452
453/**
454 Computes the difference between apparent solar time and mean solar time.
455 The returned value is in seconds.
456*/
457int16_t equation_of_time(const time_t * timer);
458
459/**
460 Computes the amount of time the sun is above the horizon, at the location of the observer.
461
462 NOTE: At observer locations inside a polar circle, this value can be zero during the winter,
463 and can exceed ONE_DAY during the summer.
464
465 The returned value is in seconds.
466*/
467int32_t daylight_seconds(const time_t * timer);
468
469/**
470 Computes the time of solar noon, at the location of the observer.
471*/
472time_t solar_noon(const time_t * timer);
473
474/**
475 Return the time of sunrise, at the location of the observer. See the note about daylight_seconds().
476*/
477time_t sun_rise(const time_t * timer);
478
479/**
480 Return the time of sunset, at the location of the observer. See the note about daylight_seconds().
481*/
482time_t sun_set(const time_t * timer);
483
484/**
485 Returns the declination of the sun in radians.
486*/
487float solar_declinationf(const time_t * timer);
488
489/**
490 Returns the declination of the sun in radians.
491
492 This implementation is only available when \c double is a 32-bit type.
493*/
494double solar_declination(const time_t * timer);
495
496/**
497 Returns the declination of the sun in radians.
498
499 This implementation is only available when <tt>long double</tt> is
500 a 32-bit type.
501*/
502long double solar_declinationl(const time_t * timer);
503
504/**
505 Returns an approximation to the phase of the moon.
506 The sign of the returned value indicates a waning or waxing phase.
507 The magnitude of the returned value indicates the percentage illumination.
508*/
509int8_t moon_phase(const time_t * timer);
510
511/**
512 Returns Greenwich Mean Sidereal Time, as seconds into the sidereal day.
513 The returned value will range from 0 through 86399 seconds.
514*/
515unsigned long gm_sidereal(const time_t * timer);
516
517/**
518 Returns Local Mean Sidereal Time, as seconds into the sidereal day.
519 The returned value will range from 0 through 86399 seconds.
520*/
521unsigned long lm_sidereal(const time_t * timer);
522
523/**@}*/
524#ifdef __cplusplus
525}
526#endif
527
528#endif /* TIME_H */
unsigned long int uint32_t
Definition: stdint.h:103
signed int int16_t
Definition: stdint.h:88
unsigned char uint8_t
Definition: stdint.h:83
signed long int int32_t
Definition: stdint.h:98
signed char int8_t
Definition: stdint.h:78
void set_system_time(time_t timestamp)
Definition: set_system_time.c:45
char * asctime(const struct tm *timeptr)
Definition: asctime.c:43
time_t sun_set(const time_t *timer)
Definition: sun_set.c:41
char * isotime(const struct tm *tmptr)
Definition: isotime.c:43
uint32_t fatfs_time(const struct tm *timeptr)
void system_tick(void)
int32_t difftime(time_t time1, time_t time0)
Definition: difftime.c:41
time_t sun_rise(const time_t *timer)
Definition: sun_rise.c:41
struct week_date * iso_week_date(int year, int yday)
Definition: iso_week_date.c:47
time_t time(time_t *timer)
Definition: time.c:44
uint32_t time_t
Definition: time.h:114
double solar_declination(const time_t *timer)
void ctime_r(const time_t *timer, char *buf)
Definition: ctime_r.c:40
time_t solar_noon(const time_t *timer)
Definition: solar_noon.c:43
void set_dst(int(*)(const time_t *, int32_t *))
Definition: set_dst.c:44
struct tm * localtime(const time_t *timer)
Definition: localtime.c:43
uint8_t week_of_month(const struct tm *timeptr, uint8_t start)
Definition: week_of_month.c:45
int16_t equation_of_time(const time_t *timer)
Definition: equation_of_time.c:57
struct tm * gmtime(const time_t *timer)
Definition: gmtime.c:44
int8_t moon_phase(const time_t *timer)
Definition: moon_phase.c:42
uint8_t week_of_year(const struct tm *timeptr, uint8_t start)
Definition: week_of_year.c:45
uint8_t is_leap_year(int16_t year)
int32_t daylight_seconds(const time_t *timer)
Definition: daylight_seconds.c:46
long double solar_declinationl(const time_t *timer)
void gmtime_r(const time_t *timer, struct tm *timeptr)
Definition: gmtime_r.c:41
void iso_week_date_r(int year, int yday, struct week_date *)
Definition: iso_week_date_r.c:52
void set_position(int32_t latitude, int32_t longitude)
unsigned long lm_sidereal(const time_t *timer)
Definition: lm_sidereal.c:42
_MONTHS_
Definition: time.h:341
size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr)
Definition: strftime.c:80
void asctime_r(const struct tm *timeptr, char *buf)
Definition: asctime_r.c:52
uint8_t month_length(int16_t year, uint8_t month)
unsigned long gm_sidereal(const time_t *timer)
Definition: gm_sidereal.c:52
void set_zone(int32_t)
time_t mk_gmtime(const struct tm *timeptr)
Definition: mk_gmtime.c:43
float solar_declinationf(const time_t *timer)
Definition: solar_declination.c:52
void localtime_r(const time_t *timer, struct tm *timeptr)
Definition: localtime_r.c:45
char * ctime(const time_t *timer)
Definition: ctime.c:43
time_t mktime(struct tm *timeptr)
Definition: mktime.c:46
void isotime_r(const struct tm *, char *)
Definition: isotime_r.c:43
_WEEK_DAYS_
Definition: time.h:328
Definition: time.h:141
int8_t tm_wday
Definition: time.h:146
int8_t tm_mday
Definition: time.h:145
int8_t tm_mon
Definition: time.h:147
int16_t tm_isdst
Definition: time.h:150
int16_t tm_year
Definition: time.h:148
int8_t tm_hour
Definition: time.h:144
int8_t tm_min
Definition: time.h:143
int8_t tm_sec
Definition: time.h:142
int16_t tm_yday
Definition: time.h:149
Definition: time.h:382
int year
Definition: time.h:383
int week
Definition: time.h:384
int day
Definition: time.h:385