StdLib/Include/time.h

   1 /** @file
   2     The header <time.h> defines two macros, and declares several types and
   3     functions for manipulating time.  Many functions deal with a calendar time
   4     that represents the current date (according to the Gregorian calendar) and
   5     time.  Some functions deal with local time, which is the calendar time
   6     expressed for some specific time zone, and with Daylight Saving Time, which
   7     is a temporary change in the algorithm for determining local time.  The local
   8     time zone and Daylight Saving Time are implementation-defined.
   9
  10     The macros defined are NULL; and CLOCKS_PER_SEC which expands to an
  11     expression with type clock_t (described below) that is the number per second
  12     of the value returned by the clock function.
  13
  14     The types declared are size_t along with clock_t and time_t which are
  15     arithmetic types capable of representing times; and struct tm which holds
  16     the components of a calendar time, called the broken-down time.
  17
  18     The range and precision of times representable in clock_t and time_t are
  19     implementation-defined. The tm structure shall contain at least the following
  20     members, in any order.  The semantics of the members and their normal ranges
  21     are expressed in the comments.
  22       - int tm_sec;   // seconds after the minute - [0, 60]
  23       - int tm_min;   // minutes after the hour - [0, 59]
  24       - int tm_hour;  // hours since midnight - [0, 23]
  25       - int tm_mday;  // day of the month - [1, 31]
  26       - int tm_mon;   // months since January - [0, 11]
  27       - int tm_year;  // years since 1900
  28       - int tm_wday;  // days since Sunday - [0, 6]
  29       - int tm_yday;  // days since January 1 - [0, 365]
  30       - int tm_isdst; // Daylight Saving Time flag
  31
  32     The value of tm_isdst is positive if Daylight Saving Time is in effect, zero
  33     if Daylight Saving Time is not in effect, and negative if the information
  34     is not available.
  35
  36     Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
  37     This program and the accompanying materials are licensed and made available under
  38     the terms and conditions of the BSD License that accompanies this distribution.
  39     The full text of the license may be found at
  40     http://opensource.org/licenses/bsd-license.
  41
  42     THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  43     WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  44
  45 **/
  46 #ifndef _TIME_H
  47 #define _TIME_H
  48 #include <sys/EfiCdefs.h>
  49
  50 #define CLOCKS_PER_SEC  __getCPS()
  51
  52 #ifdef _EFI_SIZE_T_
  53   typedef _EFI_SIZE_T_  size_t;
  54   #undef _EFI_SIZE_T_
  55   #undef _BSD_SIZE_T_
  56 #endif
  57
  58 /** An arithmetic type capable of representing values returned by clock(); **/
  59 #ifdef _EFI_CLOCK_T
  60   typedef _EFI_CLOCK_T  clock_t;
  61   #undef _EFI_CLOCK_T
  62 #endif
  63
  64 /** An arithmetic type capable of representing values returned as calendar time
  65     values, such as that returned by mktime();
  66 **/
  67 #ifdef _EFI_TIME_T
  68   typedef _EFI_TIME_T  time_t;
  69   #undef _EFI_TIME_T
  70 #endif
  71
  72 /** Value added to tm_year to get the full year value.  TM_YEAR_BASE + 110 --> 2010
  73 **/
  74 #define TM_YEAR_BASE  1900
  75
  76 /** Values for the tm_wday member of struct tm.
  77   @{
  78 **/
  79 #define TM_SUNDAY     0
  80 #define TM_MONDAY     1
  81 #define TM_TUESDAY    2
  82 #define TM_WEDNESDAY  3
  83 #define TM_THURSDAY   4
  84 #define TM_FRIDAY     5
  85 #define TM_SATURDAY   6
  86 /** @}  **/
  87
  88 /** Values for the tm_mon member of struct tm.
  89   @{
  90 **/
  91 #define TM_JANUARY     0
  92 #define TM_FEBRUARY    1
  93 #define TM_MARCH       2
  94 #define TM_APRIL       3
  95 #define TM_MAY         4
  96 #define TM_JUNE        5
  97 #define TM_JULY        6
  98 #define TM_AUGUST      7
  99 #define TM_SEPTEMBER   8
 100 #define TM_OCTOBER     9
 101 #define TM_NOVEMBER   10
 102 #define TM_DECEMBER   11
 103 /** @}  **/
 104
 105 /** A structure holding the components of a calendar time, called the
 106     broken-down time.  The first nine (9) members are as mandated by the
 107     C95 standard.  Additional fields have been added for EFI support.
 108 **/
 109 struct tm {
 110   int     tm_year;      // years since 1900
 111   int     tm_mon;       // months since January \97 [0, 11]
 112   int     tm_mday;      // day of the month \97 [1, 31]
 113   int     tm_hour;      // hours since midnight \97 [0, 23]
 114   int     tm_min;       // minutes after the hour \97 [0, 59]
 115   int     tm_sec;       // seconds after the minute \97 [0, 60]
 116   int     tm_wday;      // days since Sunday \97 [0, 6]
 117   int     tm_yday;      // days since January 1 \97 [0, 365]
 118   int     tm_isdst;     // Daylight Saving Time flag
 119   int     tm_zoneoff;   // EFI TimeZone offset, -1440 to 1440 or 2047
 120   int     tm_daylight;  // EFI Daylight flags
 121   UINT32  tm_Nano;      // EFI Nanosecond value
 122 };
 123
 124 /* ###############  Time Manipulation Functions  ########################## */
 125
 126 /** The clock function determines the processor time used.
 127
 128     @return   The clock function returns the implementation\92s best
 129               approximation to the processor time used by the program since the
 130               beginning of an implementation-defined era related only to the
 131               program invocation.  To determine the time in seconds, the value
 132               returned by the clock function should be divided by the value of
 133               the macro CLOCKS_PER_SEC.  If the processor time used is not
 134               available or its value cannot be represented, the function
 135               returns the value (clock_t)(-1).
 136
 137               On IA32 or X64 platforms, the value returned is the number of
 138               CPU TimeStamp Counter ticks since the appliation started.
 139 **/
 140 clock_t EFIAPI clock(void);
 141
 142 /**
 143 **/
 144 double EFIAPI difftime(time_t time1, time_t time0);
 145
 146 /** The mktime function converts the broken-down time, expressed as local time,
 147     in the structure pointed to by timeptr into a calendar time value with the
 148     same encoding as that of the values returned by the time function. The
 149     original values of the tm_wday and tm_yday components of the structure are
 150     ignored, and the original values of the other components are not
 151     restricted to the ranges indicated above. On successful completion,
 152     the values of the tm_wday and tm_yday components of the structure are set
 153     appropriately, and the other components are set to represent the specified
 154     calendar time, but with their values forced to the ranges indicated above;
 155     the final value of tm_mday is not set until tm_mon and tm_year
 156     are determined.
 157
 158     @return   The mktime function returns the specified calendar time encoded
 159               as a value of type time_t. If the calendar time cannot be
 160               represented, the function returns the value (time_t)(-1).
 161 **/
 162 time_t EFIAPI mktime(struct tm *timeptr);
 163
 164 /** The time function determines the current calendar time.
 165
 166     The encoding of the value is unspecified.
 167
 168     @return   The time function returns the implementation\92s best approximation
 169               of the current calendar time. The value (time_t)(-1) is returned
 170               if the calendar time is not available. If timer is not a null
 171               pointer, the return value is also assigned to the object it
 172               points to.
 173 **/
 174 time_t EFIAPI time(time_t *timer);
 175
 176 /* #################  Time Conversion Functions  ########################## */
 177
 178 /** The asctime function converts the broken-down time in the structure pointed
 179     to by timeptr into a string in the form
 180           Sun Sep 16 01:03:52 1973\n\0
 181
 182     @return   The asctime function returns a pointer to the string.
 183 **/
 184 char * EFIAPI asctime(const struct tm *timeptr);
 185
 186 /** The ctime function converts the calendar time pointed to by timer to local
 187     time in the form of a string. It is equivalent to asctime(localtime(timer))
 188
 189     @return   The ctime function returns the pointer returned by the asctime
 190               function with that broken-down time as argument.
 191 **/
 192 char * EFIAPI ctime(const time_t *timer);
 193
 194 /** The gmtime function converts the calendar time pointed to by timer into a
 195     brokendown time, expressed as UTC.
 196
 197     @return   The gmtime function returns a pointer to the broken-down time,
 198               or a null pointer if the specified time cannot be converted to UTC.
 199 **/
 200 struct tm  * EFIAPI gmtime(const time_t *timer);
 201
 202 /** The localtime function converts the calendar time pointed to by timer into
 203     a broken-down time, expressed as local time.
 204
 205     @return   The localtime function returns a pointer to the broken-down time,
 206               or a null pointer if the specified time cannot be converted to
 207               local time.
 208 **/
 209 struct tm  * EFIAPI localtime(const time_t *timer);
 210
 211 /** The strftime function places characters into the array pointed to by s as
 212     controlled by the string pointed to by format. The format shall be a
 213     multibyte character sequence, beginning and ending in its initial shift
 214     state. The format string consists of zero or more conversion specifiers
 215     and ordinary multibyte characters. A conversion specifier consists of
 216     a % character, possibly followed by an E or O modifier character
 217     (described below), followed by a character that determines the behavior of
 218     the conversion specifier.
 219
 220     All ordinary multibyte characters (including the terminating null
 221     character) are copied unchanged into the array. If copying takes place
 222     between objects that overlap, the behavior is undefined. No more than
 223     maxsize characters are placed into the array. 3 Each conversion specifier
 224     is replaced by appropriate characters as described in the following list.
 225     The appropriate characters are determined using the LC_TIME category of
 226     the current locale and by the values of zero or more members of the
 227     broken-down time structure pointed to by timeptr, as specified in brackets
 228     in the description. If any of the specified values is outside the normal
 229     range, the characters stored are unspecified.
 230
 231     %a is replaced by the locale\92s abbreviated weekday name. [tm_wday]
 232     %A is replaced by the locale\92s full weekday name. [tm_wday]
 233     %b is replaced by the locale\92s abbreviated month name. [tm_mon]
 234     %B is replaced by the locale\92s full month name. [tm_mon]
 235     %c is replaced by the locale\92s appropriate date and time representation.
 236     %C is replaced by the year divided by 100 and truncated to an integer,
 237        as a decimal number (00-99). [tm_year]
 238     %d is replaced by the day of the month as a decimal number (01-31). [tm_mday]
 239     %D is equivalent to "%m/%d/%y". [tm_mon, tm_mday, tm_year]
 240     %e is replaced by the day of the month as a decimal number (1-31);
 241        a single digit is preceded by a space. [tm_mday]
 242     %F is equivalent to "%Y-%m-%d" (the ISO 8601 date format).
 243        [tm_year, tm_mon, tm_mday]
 244     %g is replaced by the last 2 digits of the week-based year (see below) as
 245        a decimal number (00-99). [tm_year, tm_wday, tm_yday]
 246     %G is replaced by the week-based year (see below) as a decimal number
 247        (e.g., 1997). [tm_year, tm_wday, tm_yday]
 248     %h is equivalent to "%b". [tm_mon]
 249     %H is replaced by the hour (24-hour clock) as a decimal number (00-23). [tm_hour]
 250     %I is replaced by the hour (12-hour clock) as a decimal number (01-12). [tm_hour]
 251     %j is replaced by the day of the year as a decimal number (001-366). [tm_yday]
 252     %m is replaced by the month as a decimal number (01-12). [tm_mon]
 253     %M is replaced by the minute as a decimal number (00-59). [tm_min]
 254     %n is replaced by a new-line character.
 255     %p is replaced by the locale\92s equivalent of the AM/PM designations
 256        associated with a 12-hour clock. [tm_hour]
 257     %r is replaced by the locale\92s 12-hour clock time. [tm_hour, tm_min, tm_sec]
 258     %R is equivalent to "%H:%M". [tm_hour, tm_min]
 259     %S is replaced by the second as a decimal number (00-60). [tm_sec]
 260     %t is replaced by a horizontal-tab character.
 261     %T is equivalent to "%H:%M:%S" (the ISO 8601 time format).
 262        [tm_hour, tm_min, tm_sec]
 263     %u is replaced by the ISO 8601 weekday as a decimal number (1-7),
 264        where Monday is 1. [tm_wday]
 265     %U is replaced by the week number of the year (the first Sunday as the
 266        first day of week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
 267     %V is replaced by the ISO 8601 week number (see below) as a decimal number
 268        (01-53). [tm_year, tm_wday, tm_yday]
 269     %w is replaced by the weekday as a decimal number (0-6), where Sunday is 0.
 270        [tm_wday]
 271     %W is replaced by the week number of the year (the first Monday as the
 272        first day of week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
 273     %x is replaced by the locale\92s appropriate date representation.
 274     %X is replaced by the locale\92s appropriate time representation.
 275     %y is replaced by the last 2 digits of the year as a decimal
 276        number (00-99). [tm_year]
 277     %Y is replaced by the year as a decimal number (e.g., 1997). [tm_year]
 278     %z is replaced by the offset from UTC in the ISO 8601 format "-0430"
 279        (meaning 4 hours 30 minutes behind UTC, west of Greenwich), or by no
 280        characters if no time zone is determinable. [tm_isdst]
 281     %Z is replaced by the locale's time zone name or abbreviation, or by no
 282        characters if no time zone is determinable. [tm_isdst]
 283     %% is replaced by %.
 284
 285     Some conversion specifiers can be modified by the inclusion of an E or O
 286     modifier character to indicate an alternative format or specification.
 287     If the alternative format or specification does not exist for the current
 288     locale, the modifier is ignored. %Ec is replaced by the locale\92s
 289     alternative date and time representation.
 290
 291     %EC is replaced by the name of the base year (period) in the locale\92s
 292         alternative representation.
 293     %Ex is replaced by the locale\92s alternative date representation.
 294     %EX is replaced by the locale\92s alternative time representation.
 295     %Ey is replaced by the offset from %EC (year only) in the locale\92s
 296         alternative representation.
 297     %EY is replaced by the locale\92s full alternative year representation.
 298     %Od is replaced by the day of the month, using the locale\92s alternative
 299         numeric symbols (filled as needed with leading zeros, or with leading
 300         spaces if there is no alternative symbol for zero).
 301     %Oe is replaced by the day of the month, using the locale\92s alternative
 302         numeric symbols (filled as needed with leading spaces).
 303     %OH is replaced by the hour (24-hour clock), using the locale\92s
 304         alternative numeric symbols.
 305     %OI is replaced by the hour (12-hour clock), using the locale\92s
 306         alternative numeric symbols.
 307     %Om is replaced by the month, using the locale\92s alternative numeric symbols.
 308     %OM is replaced by the minutes, using the locale\92s alternative numeric symbols.
 309     %OS is replaced by the seconds, using the locale\92s alternative numeric symbols.
 310     %Ou is replaced by the ISO 8601 weekday as a number in the locale\92s
 311         alternative representation, where Monday is 1.
 312     %OU is replaced by the week number, using the locale\92s alternative numeric symbols.
 313     %OV is replaced by the ISO 8601 week number, using the locale\92s alternative
 314         numeric symbols.
 315     %Ow is replaced by the weekday as a number, using the locale\92s alternative
 316         numeric symbols.
 317     %OW is replaced by the week number of the year, using the locale\92s
 318         alternative numeric symbols.
 319     %Oy is replaced by the last 2 digits of the year, using the locale\92s
 320         alternative numeric symbols.
 321
 322     %g, %G, and %V give values according to the ISO 8601 week-based year. In
 323     this system, weeks begin on a Monday and week 1 of the year is the week
 324     that includes January 4th, which is also the week that includes the first
 325     Thursday of the year, and is also the first week that contains at least
 326     four days in the year. If the first Monday of January is the 2nd, 3rd, or
 327     4th, the preceding days are part of the last week of the preceding year;
 328     thus, for Saturday 2nd January 1999, %G is replaced by 1998 and %V is
 329     replaced by 53. If December 29th, 30th, or 31st is a Monday, it and any
 330     following days are part of week 1 of the following year. Thus, for Tuesday
 331     30th December 1997, %G is replaced by 1998 and %V is replaced by 01.
 332
 333     If a conversion specifier is not one of the above, the behavior is undefined.
 334
 335     In the "C" locale, the E and O modifiers are ignored and the replacement
 336     strings for the following specifiers are:
 337       %a the first three characters of %A.
 338       %A one of "Sunday", "Monday", ... , "Saturday".
 339       %b the first three characters of %B.
 340       %B one of "January", "February", ... , "December".
 341       %c equivalent to "%a %b %e %T %Y".
 342       %p one of "AM" or "PM".
 343       %r equivalent to "%I:%M:%S %p".
 344       %x equivalent to "%m/%d/%y".
 345       %X equivalent to %T.
 346       %Z implementation-defined.
 347
 348     @param  s         Pointer to the buffer in which to store the result.
 349     @param  maxsize   Maximum number of characters to put into buffer s.
 350     @param  format    Format string, as described above.
 351     @param  timeptr   Pointer to a broken-down time structure containing the
 352                       time to format.
 353
 354     @return   If the total number of resulting characters including the
 355               terminating null character is not more than maxsize, the
 356               strftime function returns the number of characters placed into
 357               the array pointed to by s not including the terminating null
 358               character. Otherwise, zero is returned and the contents of the
 359               array are indeterminate.
 360 **/
 361 size_t EFIAPI strftime( char * __restrict s, size_t maxsize,
 362                       const char * __restrict format,
 363                       const struct tm * __restrict timeptr);
 364
 365 char *strptime(const char *, const char * format, struct tm*);
 366
 367
 368 /* #################  Implementation Functions  ########################### */
 369
 370 clock_t EFIAPI __getCPS(void);
 371
 372 #endif  /* _TIME_H */