time

avr_time(3avr)                     avr-libc                     avr_time(3avr)



NAME
       avr_time

SYNOPSIS
   Data Structures
       struct tm
       struct week_date

   Macros
       #define ONE_HOUR   3600
       #define ONE_DEGREE   3600
       #define ONE_DAY   86400
       #define UNIX_OFFSET   946684800
       #define NTP_OFFSET   3155673600

   Typedefs
       typedef uint32_t time_t

   Enumerations
       enum _WEEK_DAYS_ { SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
           FRIDAY, SATURDAY }
       enum _MONTHS_ { JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY,
           AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER }

   Functions
       time_t time (time_t *timer)
       int32_t difftime (time_t time1, time_t time0)
       time_t mktime (struct tm *timeptr)
       time_t mk_gmtime (const struct tm *timeptr)
       struct tm * gmtime (const time_t *timer)
       void gmtime_r (const time_t *timer, struct tm *timeptr)
       struct tm * localtime (const time_t *timer)
       void localtime_r (const time_t *timer, struct tm *timeptr)
       char * asctime (const struct tm *timeptr)
       void asctime_r (const struct tm *timeptr, char *buf)
       char * ctime (const time_t *timer)
       void ctime_r (const time_t *timer, char *buf)
       char * isotime (const struct tm *tmptr)
       void isotime_r (const struct tm *, char *)
       size_t strftime (char *s, size_t maxsize, const char *format, const
           struct tm *timeptr)
       void set_dst (int(*)(const time_t *, int32_t *))
       void set_zone (int32_t)
       void set_system_time (time_t timestamp)
       void system_tick (void)
       uint8_t is_leap_year (int16_t year)
       uint8_t month_length (int16_t year, uint8_t month)
       uint8_t week_of_year (const struct tm *timeptr, uint8_t start)
       uint8_t week_of_month (const struct tm *timeptr, uint8_t start)
       struct week_date * iso_week_date (int year, int yday)
       void iso_week_date_r (int year, int yday, struct week_date *)
       uint32_t fatfs_time (const struct tm *timeptr)
       void set_position (int32_t latitude, int32_t longitude)
       int16_t equation_of_time (const time_t *timer)
       int32_t daylight_seconds (const time_t *timer)
       time_t solar_noon (const time_t *timer)
       time_t sun_rise (const time_t *timer)
       time_t sun_set (const time_t *timer)
       double solar_declination (const time_t *timer)
       int8_t moon_phase (const time_t *timer)
       unsigned long gm_sidereal (const time_t *timer)
       unsigned long lm_sidereal (const time_t *timer)

Detailed Description
       #include <time.h>


   Introduction to the Time functions
       This file declares the time functions implemented in avr-libc.

       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.

Macro Definition Documentation
   #define NTP_OFFSET   3155673600
       Difference between the Y2K and the NTP epochs, in seconds. To convert a
       Y2K timestamp to NTP...

       unsigned long ntp;
       time_t y2k;

       y2k = time(NULL);
       ntp = y2k + NTP_OFFSET;


   #define ONE_DAY   86400
       One day, expressed in seconds

   #define ONE_DEGREE   3600
       Angular degree, expressed in arc seconds

   #define ONE_HOUR   3600
       One hour, expressed in seconds

   #define UNIX_OFFSET   946684800
       Difference between the Y2K and the UNIX epochs, in seconds. To convert
       a Y2K timestamp to UNIX...

       long unix;
       time_t y2k;

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


Typedef Documentation
   typedef uint32_t time_t
       time_t represents seconds elapsed from Midnight, Jan 1 2000 UTC (the
       Y2K 'epoch'). Its range allows this implementation to represent time up
       to Tue Feb 7 06:28:15 2136 UTC.

Enumeration Type Documentation
   enum _MONTHS_
       Enumerated labels for the months.

   enum _WEEK_DAYS_
       Enumerated labels for the days of the week.

Function Documentation
   char* asctime (const struct tm * timeptr)
       The asctime function converts the broken-down time of timeptr, into an
       ascii string in the form

       Sun Mar 23 01:03:52 2013

   void asctime_r (const struct tm * timeptr, char * buf)
       Re entrant version of asctime().

   char* ctime (const time_t * timer)
       The ctime function is equivalent to asctime(localtime(timer))

   void ctime_r (const time_t * timer, char * buf)
       Re entrant version of ctime().

   int32_t daylight_seconds (const time_t * timer)
       Computes the amount of time the sun is above the horizon, at the
       location of the observer.

       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)
       The difftime function returns the difference between two binary time
       stamps, time1 - time0.

   int16_t equation_of_time (const time_t * timer)
       Computes the difference between apparent solar time and mean solar
       time. The returned value is in seconds.

   uint32_t fatfs_time (const struct tm * timeptr)
       Convert a Y2K time stamp into a FAT file system time stamp.

   unsigned long gm_sidereal (const time_t * timer)
       Returns Greenwich Mean Sidereal Time, as seconds into the sidereal day.
       The returned value will range from 0 through 86399 seconds.

   struct tm* gmtime (const time_t * timer)
       The gmtime function converts the time stamp pointed to by timer into
       broken-down time, expressed as UTC.

   void gmtime_r (const time_t * timer, struct tm * timeptr)
       Re entrant version of gmtime().

   uint8_t is_leap_year (int16_t year)
       Return 1 if year is a leap year, zero if it is not.

   struct week_date* iso_week_date (int year, int yday)
       Return a week_date structure with the ISO_8601 week based date
       corresponding to the given year and day of year. See
       http://en.wikipedia.org/wiki/ISO_week_date for more information.

   void iso_week_date_r (int year, int yday, struct week_date *)
       Re-entrant version of iso-week_date.

   char* isotime (const struct tm * tmptr)
       The isotime function constructs an ascii string in the form

       2013-03-23 01:03:52


   void isotime_r (const struct tm *, char *)
       Re entrant version of isotime()

   unsigned long lm_sidereal (const time_t * timer)
       Returns Local Mean Sidereal Time, as seconds into the sidereal day. The
       returned value will range from 0 through 86399 seconds.

   struct tm* localtime (const time_t * timer)
       The localtime function converts the time stamp pointed to by timer into
       broken-down time, expressed as Local time.

   void localtime_r (const time_t * timer, struct tm * timeptr)
       Re entrant version of localtime().

   time_t mk_gmtime (const struct tm * timeptr)
       This function 'compiles' the elements of a broken-down time structure,
       returning a binary time stamp. The elements of timeptr are interpreted
       as representing UTC.

       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)
       This function 'compiles' the elements of a broken-down time structure,
       returning a binary time stamp. The elements of timeptr are interpreted
       as representing Local Time.

       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)
       Return the length of month, given the year and month, where month is in
       the range 1 to 12.

   int8_t moon_phase (const time_t * timer)
       Returns an approximation to the phase of the moon. The sign of the
       returned value indicates a waning or waxing phase. The magnitude of the
       returned value indicates the percentage illumination.

   void set_dst (int(*)(const time_t *, int32_t *))
       Specify the Daylight Saving function.

       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)
       Set the geographic coordinates of the 'observer', for use with several
       of the following functions. Parameters are passed as seconds of North
       Latitude, and seconds of East Longitude.

       For New York City...

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


   void set_system_time (time_t timestamp)
       Initialize the system time. Examples are...

       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 the 'time zone'. The parameter is given in seconds East of the
       Prime Meridian. Example for New York City:

       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)
       Returns the declination of the sun in radians.

   time_t solar_noon (const time_t * timer)
       Computes the time of solar noon, at the location of the observer.

   size_t strftime (char * s, size_t maxsize, const char * format, const
       struct tm * timeptr)
       A complete description of strftime() is beyond the pale of this
       document. Refer to ISO/IEC document 9899 for details.

       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)
       Return the time of sunrise, at the location of the observer. See the
       note about daylight_seconds().

   time_t sun_set (const time_t * timer)
       Return the time of sunset, at the location of the observer. See the
       note about daylight_seconds().

   void system_tick (void)
       Maintain the system time by calling this function at a rate of 1 Hertz.

       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)
       The time function returns the systems current time stamp. If timer is
       not a null pointer, the return value is also assigned to the object it
       points to.

   uint8_t week_of_month (const struct tm * timeptr, uint8_t start)
       Return the calendar week of month, where the first week is considered
       to begin on the day of week specified by 'start'. The returned value
       may range from zero to 5.

   uint8_t week_of_year (const struct tm * timeptr, uint8_t start)
       Return the calendar week of year, where week 1 is considered to begin
       on the day of week specified by 'start'. The returned value may range
       from zero to 52.

Author
       Generated automatically by Doxygen for avr-libc from the source code.



Version 2.0.0                   Sat Feb 16 2019                 avr_time(3avr)