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