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, 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.php.
  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 /** A structure holding the components of a calendar time, called the
  73     broken-down time.  The first nine (9) members are as mandated by the
  74     C95 standard.  Additional fields have been added for EFI support.
  75 **/
  76 struct tm {
  77   int     tm_year;      // years since 1900
  78   int     tm_mon;       // months since January \97 [0, 11]
  79   int     tm_mday;      // day of the month \97 [1, 31]
  80   int     tm_hour;      // hours since midnight \97 [0, 23]
  81   int     tm_min;       // minutes after the hour \97 [0, 59]
  82   int     tm_sec;       // seconds after the minute \97 [0, 60]
  83   int     tm_wday;      // days since Sunday \97 [0, 6]
  84   int     tm_yday;      // days since January 1 \97 [0, 365]
  85   int     tm_isdst;     // Daylight Saving Time flag
  86   int     tm_zoneoff;   // EFI TimeZone offset, -1440 to 1440 or 2047
  87   int     tm_daylight;  // EFI Daylight flags
  88   UINT32  tm_Nano;      // EFI Nanosecond value
  89 };
  90
  91 /* ###############  Time Manipulation Functions  ########################## */
  92
  93 /** The clock function determines the processor time used.
  94
  95     @return   The clock function returns the implementation\92s best
  96               approximation to the processor time used by the program since the
  97               beginning of an implementation-defined era related only to the
  98               program invocation.  To determine the time in seconds, the value
  99               returned by the clock function should be divided by the value of
 100               the macro CLOCKS_PER_SEC.  If the processor time used is not
 101               available or its value cannot be represented, the function
 102               returns the value (clock_t)(-1).
 103
 104               On IA32 or X64 platforms, the value returned is the number of
 105               CPU TimeStamp Counter ticks since the appliation started.
 106 **/
 107 clock_t EFIAPI clock(void);
 108
 109 /**
 110 **/
 111 double EFIAPI difftime(time_t time1, time_t time0);
 112
 113 /** The mktime function converts the broken-down time, expressed as local time,
 114     in the structure pointed to by timeptr into a calendar time value with the
 115     same encoding as that of the values returned by the time function. The
 116     original values of the tm_wday and tm_yday components of the structure are
 117     ignored, and the original values of the other components are not
 118     restricted to the ranges indicated above.270) On successful completion,
 119     the values of the tm_wday and tm_yday components of the structure are set
 120     appropriately, and the other components are set to represent the specified
 121     calendar time, but with their values forced to the ranges indicated above;
 122     the final value of tm_mday is not set until tm_mon and tm_year
 123     are determined.
 124
 125     @return   The mktime function returns the specified calendar time encoded
 126               as a value of type time_t. If the calendar time cannot be
 127               represented, the function returns the value (time_t)(-1).
 128 **/
 129 time_t EFIAPI mktime(struct tm *timeptr);
 130
 131 /**
 132 **/
 133 time_t EFIAPI time(time_t *timer);
 134
 135 /* #################  Time Conversion Functions  ########################## */
 136
 137 /**
 138 **/
 139 char * EFIAPI asctime(const struct tm *timeptr);
 140
 141 /**
 142 **/
 143 char * EFIAPI ctime(const time_t *timer);
 144
 145 /**
 146 **/
 147 struct tm  * EFIAPI gmtime(const time_t *timer);
 148
 149 /**
 150 **/
 151 struct tm  * EFIAPI localtime(const time_t *timer);
 152
 153 /** The strftime function places characters into the array pointed to by s as
 154     controlled by the string pointed to by format. The format shall be a
 155     multibyte character sequence, beginning and ending in its initial shift
 156     state. The format string consists of zero or more conversion specifiers
 157     and ordinary multibyte characters. A conversion specifier consists of
 158     a % character, possibly followed by an E or O modifier character
 159     (described below), followed by a character that determines the behavior of
 160     the conversion specifier.
 161
 162     All ordinary multibyte characters (including the terminating null
 163     character) are copied unchanged into the array. If copying takes place
 164     between objects that overlap, the behavior is undefined. No more than
 165     maxsize characters are placed into the array. 3 Each conversion specifier
 166     is replaced by appropriate characters as described in the following list.
 167     The appropriate characters are determined using the LC_TIME category of
 168     the current locale and by the values of zero or more members of the
 169     broken-down time structure pointed to by timeptr, as specified in brackets
 170     in the description. If any of the specified values is outside the normal
 171     range, the characters stored are unspecified.
 172
 173     %a is replaced by the locale\92s abbreviated weekday name. [tm_wday]
 174     %A is replaced by the locale\92s full weekday name. [tm_wday]
 175     %b is replaced by the locale\92s abbreviated month name. [tm_mon]
 176     %B is replaced by the locale\92s full month name. [tm_mon]
 177     %c is replaced by the locale\92s appropriate date and time representation.
 178     %C is replaced by the year divided by 100 and truncated to an integer,
 179        as a decimal number (00-99). [tm_year]
 180     %d is replaced by the day of the month as a decimal number (01-31). [tm_mday]
 181     %D is equivalent to "%m/%d/%y". [tm_mon, tm_mday, tm_year]
 182     %e is replaced by the day of the month as a decimal number (1-31);
 183        a single digit is preceded by a space. [tm_mday]
 184     %F is equivalent to "%Y-%m-%d" (the ISO 8601 date format).
 185        [tm_year, tm_mon, tm_mday]
 186     %g is replaced by the last 2 digits of the week-based year (see below) as
 187        a decimal number (00-99). [tm_year, tm_wday, tm_yday]
 188     %G is replaced by the week-based year (see below) as a decimal number
 189        (e.g., 1997). [tm_year, tm_wday, tm_yday]
 190     %h is equivalent to "%b". [tm_mon]
 191     %H is replaced by the hour (24-hour clock) as a decimal number (00-23). [tm_hour]
 192     %I is replaced by the hour (12-hour clock) as a decimal number (01-12). [tm_hour]
 193     %j is replaced by the day of the year as a decimal number (001-366). [tm_yday]
 194     %m is replaced by the month as a decimal number (01-12). [tm_mon]
 195     %M is replaced by the minute as a decimal number (00-59). [tm_min]
 196     %n is replaced by a new-line character.
 197     %p is replaced by the locale\92s equivalent of the AM/PM designations
 198        associated with a 12-hour clock. [tm_hour]
 199     %r is replaced by the locale\92s 12-hour clock time. [tm_hour, tm_min, tm_sec]
 200     %R is equivalent to "%H:%M". [tm_hour, tm_min]
 201     %S is replaced by the second as a decimal number (00-60). [tm_sec]
 202     %t is replaced by a horizontal-tab character.
 203     %T is equivalent to "%H:%M:%S" (the ISO 8601 time format).
 204        [tm_hour, tm_min, tm_sec]
 205     %u is replaced by the ISO 8601 weekday as a decimal number (1-7),
 206        where Monday is 1. [tm_wday]
 207     %U is replaced by the week number of the year (the first Sunday as the
 208        first day of week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
 209     %V is replaced by the ISO 8601 week number (see below) as a decimal number
 210        (01-53). [tm_year, tm_wday, tm_yday]
 211     %w is replaced by the weekday as a decimal number (0-6), where Sunday is 0.
 212        [tm_wday]
 213     %W is replaced by the week number of the year (the first Monday as the
 214        first day of week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
 215     %x is replaced by the locale\92s appropriate date representation.
 216     %X is replaced by the locale\92s appropriate time representation.
 217     %y is replaced by the last 2 digits of the year as a decimal
 218        number (00-99). [tm_year]
 219     %Y is replaced by the year as a decimal number (e.g., 1997). [tm_year]
 220     %z is replaced by the offset from UTC in the ISO 8601 format "-0430"
 221        (meaning 4 hours 30 minutes behind UTC, west of Greenwich), or by no
 222        characters if no time zone is determinable. [tm_isdst]
 223     %Z is replaced by the locale's time zone name or abbreviation, or by no
 224        characters if no time zone is determinable. [tm_isdst]
 225     %% is replaced by %.
 226
 227     Some conversion specifiers can be modified by the inclusion of an E or O
 228     modifier character to indicate an alternative format or specification.
 229     If the alternative format or specification does not exist for the current
 230     locale, the modifier is ignored. %Ec is replaced by the locale\92s
 231     alternative date and time representation.
 232
 233     %EC is replaced by the name of the base year (period) in the locale\92s
 234         alternative representation.
 235     %Ex is replaced by the locale\92s alternative date representation.
 236     %EX is replaced by the locale\92s alternative time representation.
 237     %Ey is replaced by the offset from %EC (year only) in the locale\92s
 238         alternative representation.
 239     %EY is replaced by the locale\92s full alternative year representation.
 240     %Od is replaced by the day of the month, using the locale\92s alternative
 241         numeric symbols (filled as needed with leading zeros, or with leading
 242         spaces if there is no alternative symbol for zero).
 243     %Oe is replaced by the day of the month, using the locale\92s alternative
 244         numeric symbols (filled as needed with leading spaces).
 245     %OH is replaced by the hour (24-hour clock), using the locale\92s
 246         alternative numeric symbols.
 247     %OI is replaced by the hour (12-hour clock), using the locale\92s
 248         alternative numeric symbols.
 249     %Om is replaced by the month, using the locale\92s alternative numeric symbols.
 250     %OM is replaced by the minutes, using the locale\92s alternative numeric symbols.
 251     %OS is replaced by the seconds, using the locale\92s alternative numeric symbols.
 252     %Ou is replaced by the ISO 8601 weekday as a number in the locale\92s
 253         alternative representation, where Monday is 1.
 254     %OU is replaced by the week number, using the locale\92s alternative numeric symbols.
 255     %OV is replaced by the ISO 8601 week number, using the locale\92s alternative
 256         numeric symbols.
 257     %Ow is replaced by the weekday as a number, using the locale\92s alternative
 258         numeric symbols.
 259     %OW is replaced by the week number of the year, using the locale\92s
 260         alternative numeric symbols.
 261     %Oy is replaced by the last 2 digits of the year, using the locale\92s
 262         alternative numeric symbols.
 263
 264     %g, %G, and %V give values according to the ISO 8601 week-based year. In
 265     this system, weeks begin on a Monday and week 1 of the year is the week
 266     that includes January 4th, which is also the week that includes the first
 267     Thursday of the year, and is also the first week that contains at least
 268     four days in the year. If the first Monday of January is the 2nd, 3rd, or
 269     4th, the preceding days are part of the last week of the preceding year;
 270     thus, for Saturday 2nd January 1999, %G is replaced by 1998 and %V is
 271     replaced by 53. If December 29th, 30th, or 31st is a Monday, it and any
 272     following days are part of week 1 of the following year. Thus, for Tuesday
 273     30th December 1997, %G is replaced by 1998 and %V is replaced by 01.
 274
 275     If a conversion specifier is not one of the above, the behavior is undefined.
 276
 277     In the "C" locale, the E and O modifiers are ignored and the replacement
 278     strings for the following specifiers are:
 279       %a the first three characters of %A.
 280       %A one of "Sunday", "Monday", ... , "Saturday".
 281       %b the first three characters of %B.
 282       %B one of "January", "February", ... , "December".
 283       %c equivalent to "%a %b %e %T %Y".
 284       %p one of "AM" or "PM".
 285       %r equivalent to "%I:%M:%S %p".
 286       %x equivalent to "%m/%d/%y".
 287       %X equivalent to %T.
 288       %Z implementation-defined.
 289
 290     @param  s         Pointer to the buffer in which to store the result.
 291     @param  maxsize   Maximum number of characters to put into buffer s.
 292     @param  format    Format string, as described above.
 293     @param  timeptr   Pointer to a broken-down time structure containing the
 294                       time to format.
 295
 296     @return   If the total number of resulting characters including the
 297               terminating null character is not more than maxsize, the
 298               strftime function returns the number of characters placed into
 299               the array pointed to by s not including the terminating null
 300               character. Otherwise, zero is returned and the contents of the
 301               array are indeterminate.
 302 **/
 303 size_t EFIAPI strftime( char * __restrict s, size_t maxsize,
 304                       const char * __restrict format,
 305                       const struct tm * __restrict timeptr);
 306
 307 /* #################  Implementation Functions  ########################### */
 308
 309 clock_t EFIAPI __getCPS(void);
 310
 311 #endif  /* _TIME_H */