time.h@ 61103

Last change on this file since 61103 was 48674, checked in by vboxsync, 11 years ago
EFI: Export newly imported tinaocore UEFI sources to OSE.
Property svn:eol-style set to `native`
File size: 19.9 KB

Line
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 */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/StdLib/Include/time.h@ 61103

Download in other formats: