diff options
| author | lpleahy <lpleahy@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-09-09 00:37:42 +0000 |
|---|---|---|
| committer | lpleahy <lpleahy@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-09-09 00:37:42 +0000 |
| commit | 722dfee616bea21136bca4ce9991cfff35c1ef7c (patch) | |
| tree | 380a0bf7a594bc26a87da19c47b5bd6ded39bcfb | |
| parent | 12a9dd581a3725c29dd5c3ee58161715b3c65658 (diff) | |
| download | edk2-722dfee616bea21136bca4ce9991cfff35c1ef7c.zip edk2-722dfee616bea21136bca4ce9991cfff35c1ef7c.tar.gz edk2-722dfee616bea21136bca4ce9991cfff35c1ef7c.tar.bz2 | |
Update to revision 12303 of trunk
Signed-off by: Lee Leahy
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/branches/EADK@12306 6f19259b-4bc3-4df7-8a09-765794883524
27 files changed, 4266 insertions, 1317 deletions
diff --git a/StdLib/Include/Ia32/machine/limits.h b/StdLib/Include/Ia32/machine/limits.h index f072e54..cc42e0f 100644 --- a/StdLib/Include/Ia32/machine/limits.h +++ b/StdLib/Include/Ia32/machine/limits.h @@ -26,8 +26,8 @@ #define __LONG_MIN (-2147483647L - 1L) // -(2^31 - 1)
/** Maximum value for an object of type long int. **/
-#define __LONG_MAX +2147483647L // 2^31 - 1
+#define __LONG_MAX 2147483647L // 2^31 - 1
/** Maximum value for an object of type unsigned long int. **/
-#define __ULONG_MAX 0xffffffff // 2^32 - 1
+#define __ULONG_MAX 0xffffffffUL // 2^32 - 1
diff --git a/StdLib/Include/Ia32/machine/signal.h b/StdLib/Include/Ia32/machine/signal.h index 6628eb9..235797f 100644 --- a/StdLib/Include/Ia32/machine/signal.h +++ b/StdLib/Include/Ia32/machine/signal.h @@ -1,21 +1,21 @@ -/**
-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
+/** @file
+ Machine (processor architecture) specific portion of <signal.h>.
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.php.
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _MACHINE_SIGNAL_H
#define _MACHINE_SIGNAL_H
#include <sys/EfiCdefs.h>
-/** The type sig_atomic_t is the (possibly volatile-qualified) integer type of
- an object that can be accessed as an atomic entity, even in the presence
- of asynchronous interrupts.
+/** The type sig_atomic_t is the type of an object that can be accessed as an
+ atomic entity, even in the presence of asynchronous interrupts.
**/
typedef INTN sig_atomic_t;
diff --git a/StdLib/Include/X64/machine/limits.h b/StdLib/Include/X64/machine/limits.h index d046c64..193ce36 100644 --- a/StdLib/Include/X64/machine/limits.h +++ b/StdLib/Include/X64/machine/limits.h @@ -3,22 +3,37 @@ #define __POINTER_BIT 64
#if defined(__GNUC__)
-#define __LONG_BIT 64
-/** minimum value for an object of type long int **/
-#define __LONG_MIN (-9223372036854775807L - 1L) // -(2^63 - 1)
+#if __GNUC_PREREQ__(4,4)
+ #define __LONG_BIT 64
-/** maximum value for an object of type long int **/
-#define __LONG_MAX +9223372036854775807L // 2^63 - 1
+ /** minimum value for an object of type long int **/
+ #define __LONG_MIN (-9223372036854775807LL - 1LL) // -(2^63 - 2)
-/** maximum value for an object of type unsigned long int **/
-#define __ULONG_MAX 0xFFFFFFFFFFFFFFFFUL // 2^64 - 1
+ /** maximum value for an object of type long int **/
+ #define __LONG_MAX (9223372036854775807LL) // 2^63 - 1
+
+ /** maximum value for an object of type unsigned long int **/
+ #define __ULONG_MAX 0xFFFFFFFFFFFFFFFFULL // 2^64 - 1
#else
+ #define __LONG_BIT 32
+ /** minimum value for an object of type long int **/
+ #define __LONG_MIN (-2147483647L - 1L) // -(2^31 - 1)
+
+ /** maximum value for an object of type long int **/
+ #define __LONG_MAX 2147483647L // 2^31 - 1
+
+ /** maximum value for an object of type unsigned long int **/
+ #define __ULONG_MAX 0xffffffff // 2^32 - 1
+#endif
+
+
+#else /* NOT defined(__GNUC__) */
#define __LONG_BIT 32
/** minimum value for an object of type long int **/
#define __LONG_MIN (-2147483647L - 1L) // -(2^31 - 1)
/** maximum value for an object of type long int **/
-#define __LONG_MAX +2147483647L // 2^31 - 1
+#define __LONG_MAX 2147483647L // 2^31 - 1
/** maximum value for an object of type unsigned long int **/
#define __ULONG_MAX 0xffffffff // 2^32 - 1
diff --git a/StdLib/Include/X64/machine/types.h b/StdLib/Include/X64/machine/types.h index 1c1f1ab..f14625b 100644 --- a/StdLib/Include/X64/machine/types.h +++ b/StdLib/Include/X64/machine/types.h @@ -1,11 +1,11 @@ /** @file
Machine dependent type definitions.
- Portions Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
- This program and the accompanying materials are licensed and made available
- under the terms and conditions of the BSD License that accompanies this
- distribution. The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
@@ -46,10 +46,6 @@ #include <sys/EfiCdefs.h>
#include <machine/int_types.h>
-/* Handle the long and unsigned long data types which EFI doesn't directly support. */
-//typedef long int LONGN; // 32-bit
-//typedef long unsigned int ULONGN; // 32-bit
-
typedef PHYSICAL_ADDRESS paddr_t;
typedef UINT64 psize_t;
typedef PHYSICAL_ADDRESS vaddr_t;
diff --git a/StdLib/Include/locale.h b/StdLib/Include/locale.h index 73a6bf4..93aac0a 100644 --- a/StdLib/Include/locale.h +++ b/StdLib/Include/locale.h @@ -44,44 +44,97 @@ #ifndef _LOCALE_H_
#define _LOCALE_H_
-/** This is a structure containing members pertaining to the formatting of numeric values.
- There is no requirement for members of this structure to be in any particular order.
+/** This is a structure containing members pertaining to the formatting and display of numeric values.
+ Each member of this structure is commented with its value in the "C" locale.
+
+ The decimal_point member must point to a string with a length greater than zero.
+ All other pointer members may point to "" in order to indicate that the value is not available
+ in the current locale, or that it is of zero length. Except for grouping and mon_grouping, the
+ strings start and end in the initial shift state.
+
+ The remaining members, of type char, are non-negative numbers or CHAR_MAX, which indicates that
+ the value is not available in the current locale.
+
+ Members grouping and mon_grouping point to strings where each element (character) of the string
+ indicates the size of the corresponding group of digits and is interpreted as follows:
+ - CHAR_MAX No further grouping is to be performed.
+ - 0 The previous element is to be repeatedly used for the remainder of the digits.
+ - other The ISO specification states: "The integer value is the number of digits that
+ compose the current group. The next element is examined to determine the size
+ of the next group of digits before the current group." The EDK II implementation
+ interprets this to mean that the groups are specified left-to-right.
+
+ The *_sep_by_space members are interpreted as follows:
+ - 0 No space separates the currency symbol and value.
+ - 1 If the currency symbol and sign string are adjacent, a space separates them from the
+ value; otherwise, a space separates the currency symbol from the value.
+ - 2 If the currency symbol and sign string are adjacent, a space separates them;
+ otherwise, a space separates the sign string from the value.
+ For int_p_sep_by_space and int_n_sep_by_space, the fourth character of int_curr_symbol is
+ used instead of a space.
+
+ The values of the *_sign_posn members are interpreted as follows:
+ - 0 Parentheses surround the quantity and currency symbol.
+ - 1 The sign string precedes the quantity and currency symbol.
+ - 2 The sign string succeeds the quantity and currency symbol.
+ - 3 The sign string immediately precedes the currency symbol.
+ - 4 The sign string immediately succeeds the currency symbol.
**/
struct lconv {
- char *decimal_point;
- char *thousands_sep;
- char *grouping;
- char *int_curr_symbol;
- char *currency_symbol;
- char *mon_decimal_point;
- char *mon_thousands_sep;
- char *mon_grouping;
- char *positive_sign;
- char *negative_sign;
- char int_frac_digits;
- char frac_digits;
- char p_cs_precedes;
- char p_sep_by_space;
- char n_cs_precedes;
- char n_sep_by_space;
- char p_sign_posn;
- char n_sign_posn;
- char int_p_cs_precedes;
- char int_n_cs_precedes;
- char int_p_sep_by_space;
- char int_n_sep_by_space;
- char int_p_sign_posn;
- char int_n_sign_posn;
+ char *decimal_point; /**< "." Non-monetary decimal-point. */
+ char *thousands_sep; /**< "" Separates groups of digits before the decimal-point */
+ char *grouping; /**< "" A string whose elements (characters) indicate the size
+ of each group of digits in formatted nonmonetary quantities. */
+ char *int_curr_symbol; /**< "" A 4-character string providing the international currency
+ symbol. The first three characters contain the alphabetic
+ international currency symbol in accordance with those
+ specified in ISO 4217. The fourth character, immediately
+ preceding the null character, is the character used to separate
+ the international currency symbol from the monetary quantity. */
+ char *currency_symbol; /**< "" The local currency symbol for the current locale. */
+ char *mon_decimal_point; /**< "" The decimal point used for monetary values. */
+ char *mon_thousands_sep; /**< "" The separator for digit groups preceeding the decimal-point. */
+ char *mon_grouping; /**< "" A string, like grouping, for monetary values. */
+ char *positive_sign; /**< "" A string to indicate a non-negative monetary value. */
+ char *negative_sign; /**< "" A string to indicate a negative monetary value. */
+ char int_frac_digits; /**< CHAR_MAX The number of digits after the decimal-point for international
+ monetary values. */
+ char frac_digits; /**< CHAR_MAX The number of digits after the decimal-point for local
+ monetary values. */
+ char p_cs_precedes; /**< CHAR_MAX Set to 1 or 0 if the currency_symbol respectively precedes or
+ succeeds the value for non-negative local monetary values. */
+ char p_sep_by_space; /**< CHAR_MAX Value specifying the separation between the currency_symbol,
+ the sign string, and the value for non-negative local values. */
+ char n_cs_precedes; /**< CHAR_MAX Set to 1 or 0 if the currency_symbol respectively precedes or
+ succeeds the value for negative local monetary values. */
+ char n_sep_by_space; /**< CHAR_MAX Value specifying the separation between the currency_symbol,
+ the sign string, and the value for negative local values. */
+ char p_sign_posn; /**< CHAR_MAX Value specifying the positioning of the positive_sign for a
+ non-negative local monetary quantity. */
+ char n_sign_posn; /**< CHAR_MAX Value specifying the positioning of the negative_sign for a
+ negative local monetary quantity. */
+ char int_p_cs_precedes; /**< CHAR_MAX Set to 1 or 0 if the currency_symbol respectively precedes or
+ succeeds the value for non-negative international monetary values. */
+ char int_n_cs_precedes; /**< CHAR_MAX Set to 1 or 0 if the currency_symbol respectively precedes or
+ succeeds the value for negative international monetary values. */
+ char int_p_sep_by_space; /**< CHAR_MAX Value specifying the separation between the currency_symbol,
+ the sign string, and the value for non-negative international values. */
+ char int_n_sep_by_space; /**< CHAR_MAX Value specifying the separation between the currency_symbol,
+ the sign string, and the value for negative international values. */
+ char int_p_sign_posn; /**< CHAR_MAX Value specifying the positioning of the positive_sign for a
+ non-negative international monetary quantity. */
+ char int_n_sign_posn; /**< CHAR_MAX Value specifying the positioning of the negative_sign for a
+ negative international monetary quantity. */
};
-/** These macros expand to integer expressions suitable for use as the first
- argument to the setlocale() function.
+/** @{
+ These macros expand to integer expressions suitable for use as the first
+ argument (category) to the setlocale() function.
Only the first six macros are required by the C language specification.
Implementations are free to extend this list, as has been done with LC_MESSAGES,
with additional macro definitions, beginning with the characters LC_ and
an uppercase letter.
-@{
**/
#define LC_ALL 0 ///< The application's entire locale.
#define LC_COLLATE 1 ///< Affects the behavior of the strcoll and strxfrm functions.
@@ -91,25 +144,51 @@ struct lconv { #define LC_TIME 5 ///< Affects the behavior of the strftime and wcsftime functions.
#define LC_MESSAGES 6
#define _LC_LAST 7 ///< Number of defined macros. Marks end.
-/// @}
+/*@}*/
#include <sys/EfiCdefs.h>
-/** @fn char *setlocale(int, const char *)
+/** @fn char *setlocale(int category, const char *locale)
+
+ @brief The setlocale function is used to retrieve or change parts or all of the current locale.
+
+ @details If locale is NULL, or the same as the current locale, this function just retrieves the
+ values for the specified category in the current locale. Otherwise, the specified category
+ in the current locale is set to the corresponding values from the specified locale and a pointer
+ to the new values is returned.
+
+ @param[in] category The portion of the current locale to be affected by this call.
+ The LC_ macros list the supported categories and the meaning of each.
+ @param[in] locale A value of "C" for locale specifies the minimal environment for C translation;
+ A value of "" specifies the native environment, which is "C" for this
+ implementation. If locale is NULL, the current locale is specified.
+
+ @return A pointer to the string associated with the specified category for the new locale,
+ a pointer to the string associated with the category for the current locale,
+ or NULL if category or locale can not be honored. The return value should not be
+ modified by the program, but may be overwritten by subsequent calls to either
+ setlocale or localeconv.
**/
/** @fn struct lconv *localeconv(void)
+
+ @brief The localeconv function returns a pointer to a lconv structure containing the appropriate
+ values for the current locale.
+
+ @return A pointer to a filled-in lconv structure. The returned structure should not be
+ modified by the program, but may be overwritten by subsequent calls to either
+ setlocale or localeconv.
**/
__BEGIN_DECLS
#ifdef __SETLOCALE_SOURCE__
- char *setlocale(int, const char *);
- char *__setlocale(int, const char *);
+ char *setlocale(int category, const char *locale);
+ char *__setlocale(int category, const char *locale);
#else /* !__SETLOCALE_SOURCE__ */
- char *setlocale(int, const char *) __RENAME(__setlocale_mb_len_max_32);
+ char *setlocale(int category, const char *locale) __RENAME(__setlocale_mb_len_max_32);
#endif /* !__SETLOCALE_SOURCE__ */
struct lconv *localeconv(void);
- char *__setlocale_mb_len_max_32(int, const char *);
+ char *__setlocale_mb_len_max_32(int category, const char *locale);
__END_DECLS
#endif /* _LOCALE_H_ */
diff --git a/StdLib/Include/math.h b/StdLib/Include/math.h index 81a900e..3041120 100644 --- a/StdLib/Include/math.h +++ b/StdLib/Include/math.h @@ -1,6 +1,15 @@ -/* $NetBSD: math.h,v 1.44 2006/03/25 16:41:11 xtraeme Exp $ */
+/** @file
+ Floating-point Math functions and macros.
+
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-/*
* ====================================================
* Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
*
@@ -9,18 +18,20 @@ * software is freely granted, provided that this notice
* is preserved.
* ====================================================
- */
-
-/*
- * @(#)fdlibm.h 5.1 93/09/24
- */
+ NetBSD: math.h,v 1.44 2006/03/25 16:41:11 xtraeme Exp
+ dlibm.h 5.1 93/09/24
+**/
#ifndef _MATH_H_
#define _MATH_H_
#include <sys/EfiCdefs.h>
-#include <sys/featuretest.h>
+#include <sys/featuretest.h>
+/** @{
+ @brief These are forward references to unions and macros used internaly
+ by the implementation of the math functions and macros.
+**/
union __float_u {
unsigned char __dummy[sizeof(float)];
float __val;
@@ -36,8 +47,7 @@ union __long_double_u { long double __val;
};
-#include <machine/math.h> /* may use __float_u, __double_u,
- or __long_double_u */
+#include <machine/math.h> /* may use __float_u, __double_u, or __long_double_u */
#ifdef __HAVE_LONG_DOUBLE
#define __fpmacro_unary_floating(__name, __arg0) \
@@ -55,64 +65,290 @@ union __long_double_u { : __ ## __name ## d (__arg0))
#endif /* __HAVE_LONG_DOUBLE */
-/*
- * ANSI/POSIX
+extern const union __double_u __infinity;
+extern const union __float_u __infinityf;
+extern const union __long_double_u __infinityl;
+
+/* C99 7.12.3.1 int fpclassify(real-floating x) */
+#define fpclassify(__x) __fpmacro_unary_floating(fpclassify, __x)
+
+/* C99 7.12.3.3 int isinf(real-floating x) */
+#ifdef __isinf
+ #define isinf(__x) __isinf(__x)
+#else
+ #define isinf(__x) __fpmacro_unary_floating(isinf, __x)
+#endif
+
+/* C99 7.12.3.4 int isnan(real-floating x) */
+#ifdef __isnan
+ #define isnan(__x) __isnan(__x)
+#else
+ #define isnan(__x) __fpmacro_unary_floating(isnan, __x)
+#endif
+/*@)*/
+
+/*#############################################################
+ * ISO C95
*/
-/* 7.12#3 HUGE_VAL, HUGELF, HUGE_VALL */
-extern const union __double_u __infinity;
+
+/**@{
+ Double, float, and long double versions, respectively, of HUGE_VAL.
+*/
#define HUGE_VAL __infinity.__val
+#define HUGE_VALF __infinityf.__val
+#define HUGE_VALL __infinityl.__val
+/*@)*/
+__BEGIN_DECLS
/*
- * ISO C99
+ * ANSI/POSIX
*/
-/* 7.12#3 HUGE_VAL, HUGELF, HUGE_VALL */
-extern const union __float_u __infinityf;
-#define HUGE_VALF __infinityf.__val
+/** Compute the principal value of the arc cosine of Arg.
-extern const union __long_double_u __infinityl;
-#define HUGE_VALL __infinityl.__val
+ @param[in] Arg The value to compute the arc cosine of.
-/* 7.12#4 INFINITY */
-#ifdef __INFINITY
-#define INFINITY __INFINITY /* float constant which overflows */
-#else
-#define INFINITY HUGE_VALF /* positive infinity */
-#endif /* __INFINITY */
+ @return The computed value of the arc cosine of Arg in the interval [0,pi] radians.
+ If Arg is not in the interval [-1,+1], errno is set to EDOM.
+**/
+double acos(double Arg);
-/* 7.12#5 NAN: a quiet NaN, if supported */
-#ifdef __HAVE_NANF
-extern const union __float_u __nanf;
-#define NAN __nanf.__val
-#endif /* __HAVE_NANF */
+/** Compute the principal value of the arc sine of Arg.
-/* 7.12#6 number classification macros */
-#define FP_INFINITE 0x00
-#define FP_NAN 0x01
-#define FP_NORMAL 0x02
-#define FP_SUBNORMAL 0x03
-#define FP_ZERO 0x04
-/* NetBSD extensions */
-#define _FP_LOMD 0x80 /* range for machine-specific classes */
-#define _FP_HIMD 0xff
+ @param[in] Arg The value to compute the arc sine of.
+
+ @return The computed value of the arc sine of Arg in the interval [-pi/2,+pi/2] radians.
+ If Arg is not in the interval [-1,+1], errno is set to EDOM.
+**/
+double asin(double Arg);
+
+/** Compute the principal value of the arc tangent of Arg.
+
+ @param[in] Arg The value to compute the arc tangent of.
+
+ @return The computed value of the arc tangent of Arg in the interval [-pi/2,+pi/2] radians.
+**/
+double atan(double Arg);
+
+/** Compute the value of the arc tangent of (Num / Denom).
+ The sign of both arguments is used to determine the quadrant of the return value.
+
+ @param[in] Num The numerator of the value to compute the arc tangent of.
+ @param[in] Denom The denominator of the value to compute the arc tangent of.
+
+ @return The computed value of the arc tangent of (Num / Denom) in the interval [-pi,+pi] radians.
+**/
+double atan2(double Num, double Denom);
+
+/** Compute the value of the cosine of Arg, measured in radians.
+
+ @param[in] Arg The value to compute the cosine of.
+
+ @return The computed value of the cosine of Arg.
+**/
+double cos(double Arg);
+
+/** Compute the value of the sine of Arg.
+
+ @param[in] Arg The value to compute the sine of.
+
+ @return The computed value of the sine of Arg.
+**/
+double sin(double Arg);
+
+/** Compute the value of the tangent of Arg.
+
+ @param[in] Arg The value to compute the tangent of.
+
+ @return The computed value of the tangent of Arg.
+**/
+double tan(double Arg);
+
+
+/** Compute the value of the hyperbolic cosine of Arg.
+
+ @param[in] Arg The value to compute the hyperbolic cosine of.
+
+ @return The computed value of the hyperbolic cosine of Arg.
+ If the magnitude of Arg is too large, errno is set to ERANGE.
+**/
+double cosh(double Arg);
+
+/** Compute the value of the hyperbolic sine of Arg.
+
+ @param[in] Arg The value to compute the hyperbolic sine of.
+
+ @return The computed value of the hyperbolic sine of Arg.
+ If the magnitude of Arg is too large, errno is set to ERANGE.
+**/
+double sinh(double Arg);
+
+/** Compute the value of the hyperbolic tangent of Arg.
+
+ @param[in] Arg The value to compute the hyperbolic tangent of.
+
+ @return The computed value of the hyperbolic tangent of Arg.
+**/
+double tanh(double Arg);
+
+
+/** Compute the base-e exponential of Arg.
+
+ @param[in] Arg The value to compute the base-e exponential of.
+
+ @return The computed value of e**Arg.
+ If the magnitude of Arg is too large, errno is set to ERANGE.
+**/
+double exp(double Arg);
+
+/** Break a floating-point number into a normalized fraction and an integral power of 2.
+
+ @param[in] Value The floating-point value to be broken down.
+ @param[out] Exp A pointer to an integer object to receive the integral power of 2 exponent.
+
+ @return The frexp function returns a value R, such that Value == R**Exp.
+ If Value is zero, both parts of the result are zero.
+**/
+double frexp(double Value, int *Exp);
+
+/** Multiply a floating-point number, Value, by an integral power of 2, Exp.
+
+ @param[in] Value The floating-point value to be multiplied.
+ @param[out] Exp The integral power of 2 to multiply Value by.
+
+ @return The ldexp function returns a value R, such that R = Value x 2**Exp.
+ If a range error occurs, errno will be set to ERANGE.
+**/
+double ldexp(double Value, int Exp);
+
+/** Compute the natural logarithm of Arg.
+
+ @param[in] Arg The value to compute the natural logarithm of.
+
+ @return The log function returns log base-e of Arg. If Arg is negative, errno is set to EDOM.
+ Otherwise, errno will be set to ERANGE if a range error occurs.
+**/
+double log(double Arg);
+
+/** Compute the common (base-10) logarithm of Arg.
+
+ @param[in] Arg The value to compute the common logarithm of.
+
+ @return The log10 function returns log base-10 of Arg. If Arg is negative, errno is set to EDOM.
+ Otherwise, errno will be set to ERANGE if Arg is 0.
+**/
+double log10(double Arg);
+
+/** Compute the base-2 logarithm of Arg.
+
+ @param[in] Arg The value to compute the base-2 logarithm of.
+
+ @return The log function returns log base-2 of Arg. If Arg is negative, errno is set to EDOM.
+ Otherwise, errno will be set to ERANGE if Arg is 0.
+**/
+double log2(double Arg);
+
+/** Break Value into integral and fractional parts, each of which has the same type and sign
+ as Value. Store the integral part in the object pointed to by Integ and return the
+ fractional part.
+
+ @param[in] Value The value to compute the arc cosine of.
+ @param[out] Integ Pointer to where the integral component is to be stored.
+
+ @return The fractional part of Value is returned directly while the integral part is
+ returned in the location pointed to by Integ.
+**/
+double modf(double Value, double *Integ);
+
+/** Compute Value raised to the power Exp.
+
+ @param[in] Value The value to be raised.
+ @param[in] Exp The power Value is to be raised to.
+
+ @return The pow function returns Value**Exp. If an error occurs, errno will be set as follows:
+ - EDOM: Value is finite and negative and Exp is finite and not an integer.
+ - EDOM: Both Value and Exp are zero.
+ - EDOM: Value is zero and Exp is less than zero.
+**/
+double pow(double Value, double Exp);
+
+/** Compute the non-negative square root of Arg.
+
+ @param[in] Arg The value to compute the square root of.
+
+ @return The square root of Arg. If Arg is less than zero, errno is set to EDOM.
+**/
+double sqrt(double Arg);
+
+
+/** Compute the smallest integer value not less than Arg.
+
+ @param[in] Arg The value to compute the ceiling of.
+
+ @return The ceiling of Arg expressed as a floating-point number.
+**/
+double ceil(double Arg);
+
+/** Compute the absolute value of Arg.
+
+ @param[in] Arg The value to compute the absolute value of.
+
+ @return The absolute value of Arg.
+**/
+double fabs(double Arg);
+
+/** Compute the largest integer value not greater than Arg.
+ @param[in] Arg The value to compute the floor of.
+
+ @return The largest integer value not greater than Arg, expressed as a floating-point number.
+**/
+double floor(double);
+
+/** Compute the floating-point remainder of A1 / A2.
+
+ @param[in] A1 The dividend.
+ @param[in] A2 The divisor.
+
+ @return The remainder of A1 / A2 with the same sign as A1. If A2 is zero, the fmod function
+ returns 0.
+**/
+double fmod(double A1, double A2);
+
+
+int finite(double);
+double expm1(double);
+
+/**@{
+ C99, Posix, or NetBSD functions that are not part of the C95 specification.
+**/
/*
- * XOPEN/SVID
+ * Functions callable from C, intended to support IEEE arithmetic.
*/
-#define M_E 2.7182818284590452354 /* e */
-#define M_LOG2E 1.4426950408889634074 /* log 2e */
-#define M_LOG10E 0.43429448190325182765 /* log 10e */
-#define M_LN2 0.69314718055994530942 /* log e2 */
-#define M_LN10 2.30258509299404568402 /* log e10 */
-#define M_PI 3.14159265358979323846 /* pi */
-#define M_PI_2 1.57079632679489661923 /* pi/2 */
-#define M_PI_4 0.78539816339744830962 /* pi/4 */
-#define M_1_PI 0.31830988618379067154 /* 1/pi */
-#define M_2_PI 0.63661977236758134308 /* 2/pi */
-#define M_2_SQRTPI 1.12837916709551257390 /* 2/sqrt(pi) */
-#define M_SQRT2 1.41421356237309504880 /* sqrt(2) */
-#define M_SQRT1_2 0.70710678118654752440 /* 1/sqrt(2) */
+double copysign(double, double);
+double scalbn(double, int);
-#define MAXFLOAT ((float)3.40282346638528860e+38)
+/*
+ * Library implementation
+ */
+int __fpclassifyf(float);
+int __fpclassifyd(double);
+int __isinff(float);
+int __isinfd(double);
+int __isnanf(float);
+int __isnand(double);
+
+#ifdef __HAVE_LONG_DOUBLE
+ int __fpclassifyl(long double);
+ int __isinfl(long double);
+ int __isnanl(long double);
+#endif /* __HAVE_LONG_DOUBLE */
+/*@}*/
+
+__END_DECLS
+
+/**@{
+ Extensions provided by NetBSD but not required by the C95 standard.
+**/
extern int signgam;
enum fdversion {fdlibm_ieee = -1, fdlibm_svid, fdlibm_xopen, fdlibm_posix};
@@ -120,7 +356,7 @@ enum fdversion {fdlibm_ieee = -1, fdlibm_svid, fdlibm_xopen, fdlibm_posix}; #define _LIB_VERSION_TYPE enum fdversion
#define _LIB_VERSION _fdlib_version
-/* if global variable _LIB_VERSION is not desirable, one may
+/** If global variable _LIB_VERSION is not desirable, one may
* change the following to be a constant by:
* #define _LIB_VERSION_TYPE const enum version
* In that case, after one initializes the value _LIB_VERSION (see
@@ -146,11 +382,7 @@ struct exception { #define HUGE MAXFLOAT
-/*
- * set X_TLOSS = pi*2**52, which is possibly defined in <values.h>
- * (one may replace the following line by "#include <values.h>")
- */
-
+/** set X_TLOSS = pi*2**52 **/
#define X_TLOSS 1.41484755040568800000e+16
#define DOMAIN 1
@@ -159,295 +391,52 @@ struct exception { #define UNDERFLOW 4
#define TLOSS 5
#define PLOSS 6
+/*@}*/
-
-__BEGIN_DECLS
-/*
- * ANSI/POSIX
- */
-double acos(double);
-double asin(double);
-double atan(double);
-double atan2(double, double);
-double cos(double);
-double sin(double);
-double tan(double);
-
-double cosh(double);
-double sinh(double);
-double tanh(double);
-
-double exp(double);
-double frexp(double, int *);
-double ldexp(double, int);
-double log(double);
-double log2(double);
-double log10(double);
-double modf(double, double *);
-
-double pow(double, double);
-double sqrt(double);
-
-double ceil(double);
-double fabs(double);
-double floor(double);
-double fmod(double, double);
-
-//#if defined(_XOPEN_SOURCE) || defined(_NETBSD_SOURCE)
-//double erf(double);
-//double erfc(double);
-//double gamma(double);
-//double hypot(double, double);
-int finite(double);
-//double j0(double);
-//double j1(double);
-//double jn(int, double);
-//double lgamma(double);
-//double y0(double);
-//double y1(double);
-//double yn(int, double);
-
-//#if (_XOPEN_SOURCE - 0) >= 500 || defined(_NETBSD_SOURCE)
-//double acosh(double);
-//double asinh(double);
-//double atanh(double);
-//double cbrt(double);
-double expm1(double);
-//int ilogb(double);
-//double log1p(double);
-//double logb(double);
-//double nextafter(double, double);
-//double remainder(double, double);
-//double rint(double);
-//double scalb(double, double);
-//#endif /* (_XOPEN_SOURCE - 0) >= 500 || defined(_NETBSD_SOURCE)*/
-//#endif /* _XOPEN_SOURCE || _NETBSD_SOURCE */
-
-/* 7.12.3.1 int fpclassify(real-floating x) */
-#define fpclassify(__x) __fpmacro_unary_floating(fpclassify, __x)
-
-#if 0
-/*
- * ISO C99
- */
-#if !defined(_ANSI_SOURCE) && !defined(_POSIX_C_SOURCE) && \
- !defined(_XOPEN_SOURCE) || \
- ((__STDC_VERSION__ - 0) >= 199901L) || \
- ((_POSIX_C_SOURCE - 0) >= 200112L) || \
- ((_XOPEN_SOURCE - 0) >= 600) || \
- defined(_ISOC99_SOURCE) || defined(_NETBSD_SOURCE)
-
-/* 7.12.3.2 int isfinite(real-floating x) */
-#define isfinite(__x) __fpmacro_unary_floating(isfinite, __x)
-
-/* 7.12.3.5 int isnormal(real-floating x) */
-#define isnormal(__x) (fpclassify(__x) == FP_NORMAL)
-
-/* 7.12.3.6 int signbit(real-floating x) */
-#define signbit(__x) __fpmacro_unary_floating(signbit, __x)
-
-/* 7.12.4 trigonometric */
-
-float acosf(float);
-float asinf(float);
-float atanf(float);
-float atan2f(float, float);
-float cosf(float);
-float sinf(float);
-float tanf(float);
-
-/* 7.12.5 hyperbolic */
-
-float acoshf(float);
-float asinhf(float);
-float atanhf(float);
-float coshf(float);
-float sinhf(float);
-float tanhf(float);
-
-/* 7.12.6 exp / log */
-
-float expf(float);
-float expm1f(float);
-float frexpf(float, int *);
-int ilogbf(float);
-float ldexpf(float, int);
-float logf(float);
-float log2f(float);
-float log10f(float);
-float log1pf(float);
-float logbf(float);
-float modff(float, float *);
-float scalbnf(float, int);
-
-/* 7.12.7 power / absolute */
-
-float cbrtf(float);
-float fabsf(float);
-float hypotf(float, float);
-float powf(float, float);
-float sqrtf(float);
-
-/* 7.12.8 error / gamma */
-
-float erff(float);
-float erfcf(float);
-float lgammaf(float);
-
-/* 7.12.9 nearest integer */
-
-float ceilf(float);
-float floorf(float);
-float rintf(float);
-double round(double);
-float roundf(float);
-double trunc(double);
-float truncf(float);
-long int lrint(double);
-long int lrintf(float);
-/* LONGLONG */
-long long int llrint(double);
-/* LONGLONG */
-long long int llrintf(float);
-long int lround(double);
-long int lroundf(float);
-/* LONGLONG */
-long long int llround(double);
-/* LONGLONG */
-long long int llroundf(float);
-
-/* 7.12.10 remainder */
-
-float fmodf(float, float);
-float remainderf(float, float);
-
-/* 7.2.11 manipulation */
-
-float copysignf(float, float);
-double nan(const char *);
-float nanf(const char *);
-long double nanl(const char *);
-float nextafterf(float, float);
-
-
-#endif /* !_ANSI_SOURCE && ... */
-
-#if defined(_NETBSD_SOURCE)
-#ifndef __cplusplus
-int matherr(struct exception *);
-#endif
-#endif /* _NETBSD_SOURCE */
-
-/*
- * IEEE Test Vector
- */
-double significand(double);
-#endif /* if 0 */
-
-/* 7.12.3.3 int isinf(real-floating x) */
-#ifdef __isinf
-#define isinf(__x) __isinf(__x)
-#else
-#define isinf(__x) __fpmacro_unary_floating(isinf, __x)
-#endif
-
-/* 7.12.3.4 int isnan(real-floating x) */
-#ifdef __isnan
-#define isnan(__x) __isnan(__x)
+/* 7.12#4 INFINITY */
+#ifdef __INFINITY
+#define INFINITY __INFINITY /**< float constant which overflows */
#else
-#define isnan(__x) __fpmacro_unary_floating(isnan, __x)
-#endif
-
-/*
- * Functions callable from C, intended to support IEEE arithmetic.
- */
-double copysign(double, double);
-double scalbn(double, int);
-
-#if 0
-/*
- * BSD math library entry points
- */
-#ifndef __MATH_PRIVATE__
-double cabs(/* struct complex { double r; double i; } */);
-#endif
-double drem(double, double);
-
-
-#if defined(_NETBSD_SOURCE) || defined(_REENTRANT)
-/*
- * Reentrant version of gamma & lgamma; passes signgam back by reference
- * as the second argument; user must allocate space for signgam.
- */
-double gamma_r(double, int *);
-double lgamma_r(double, int *);
-#endif /* _NETBSD_SOURCE || _REENTRANT */
-
-
-#if defined(_NETBSD_SOURCE)
-
-/* float versions of ANSI/POSIX functions */
-
-float gammaf(float);
-int isinff(float);
-int isnanf(float);
-int finitef(float);
-float j0f(float);
-float j1f(float);
-float jnf(int, float);
-float y0f(float);
-float y1f(float);
-float ynf(int, float);
-
-float scalbf(float, float);
+#define INFINITY HUGE_VALF /**< positive infinity */
+#endif /* __INFINITY */
-/*
- * float version of IEEE Test Vector
- */
-float significandf(float);
+/* 7.12#5 NAN: a quiet NaN, if supported */
+#ifdef __HAVE_NANF
+extern const union __float_u __nanf;
+#define NAN __nanf.__val
+#endif /* __HAVE_NANF */
-/*
- * float versions of BSD math library entry points
- */
-#ifndef __MATH_PRIVATE__
-float cabsf(/* struct complex { float r; float i; } */);
-#endif
-float dremf(float, float);
-#endif /* _NETBSD_SOURCE */
+/**@{
+ C99 7.12#6 Number classification macros represent mutually exclusive kinds of floating-point
+ values.
+**/
+#define FP_INFINITE 0x00
+#define FP_NAN 0x01
+#define FP_NORMAL 0x02
+#define FP_SUBNORMAL 0x03
+#define FP_ZERO 0x04
+/* NetBSD extensions */
+#define _FP_LOMD 0x80 /**< range for machine-specific classes */
+#define _FP_HIMD 0xff
+/*@)*/
-#if defined(_NETBSD_SOURCE) || defined(_REENTRANT)
-/*
- * Float versions of reentrant version of gamma & lgamma; passes
- * signgam back by reference as the second argument; user must
- * allocate space for signgam.
+/**@{
+ * Constants ala XOPEN/SVID.
*/
-float gammaf_r(float, int *);
-float lgammaf_r(float, int *);
-#endif /* !... || _REENTRANT */
-
-#endif /* if 0 */
-
-///*
-// * Library implementation
-// */
-int __fpclassifyf(float);
-int __fpclassifyd(double);
-//int __isfinitef(float);
-//int __isfinited(double);
-int __isinff(float);
-int __isinfd(double);
-int __isnanf(float);
-int __isnand(double);
-//int __signbitf(float);
-//int __signbitd(double);
-
-//#ifdef __HAVE_LONG_DOUBLE
-int __fpclassifyl(long double);
-//int __isfinitel(long double);
-int __isinfl(long double);
-int __isnanl(long double);
-//int __signbitl(long double);
-//#endif
-__END_DECLS
+#define M_E 2.7182818284590452354 /**< e */
+#define M_LOG2E 1.4426950408889634074 /**< log 2e */
+#define M_LOG10E 0.43429448190325182765 /**< log 10e */
+#define M_LN2 0.69314718055994530942 /**< log e2 */
+#define M_LN10 2.30258509299404568402 /**< log e10 */
+#define M_PI 3.14159265358979323846 /**< pi */
+#define M_PI_2 1.57079632679489661923 /**< pi/2 */
+#define M_PI_4 0.78539816339744830962 /**< pi/4 */
+#define M_1_PI 0.31830988618379067154 /**< 1/pi */
+#define M_2_PI 0.63661977236758134308 /**< 2/pi */
+#define M_2_SQRTPI 1.12837916709551257390 /**< 2/sqrt(pi) */
+#define M_SQRT2 1.41421356237309504880 /**< sqrt(2) */
+#define M_SQRT1_2 0.70710678118654752440 /**< 1/sqrt(2) */
+#define MAXFLOAT ((float)3.40282346638528860e+38)
+/*@}*/
#endif /* _MATH_H_ */
diff --git a/StdLib/Include/setjmp.h b/StdLib/Include/setjmp.h index ed691e6..33ea161 100644 --- a/StdLib/Include/setjmp.h +++ b/StdLib/Include/setjmp.h @@ -1,16 +1,15 @@ /** @file
- The header <setjmp.h> defines the macro setjmp, and declares one function
- and one type, for bypassing the normal function call and return discipline.
+ This file defines the macro setjmp, and declares the function longjmp
+ and the type jmp_buf, for bypassing the normal function call and return discipline.
-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _SETJMP_H
#define _SETJMP_H
@@ -40,7 +39,8 @@ typedef BASE_LIBRARY_JUMP_BUFFER jmp_buf[1]; @return If the return is from a direct invocation, the setjmp macro
returns the value zero. If the return is from a call to the longjmp
- function, the setjmp macro returns a nonzero value.
+ function, the setjmp macro returns a nonzero value based upon the value
+ of the second argument to the longjmp function.
**/
#define setjmp(env) (INTN)SetJump((env))
@@ -52,7 +52,10 @@ typedef BASE_LIBRARY_JUMP_BUFFER jmp_buf[1]; macro was within the scope of an identifier with variably modified type and
execution has left that scope in the interim, the behavior is undefined.
- After longjmp is completed, program execution continues as if the
+ @param[in] env The jump buffer containing the environment to be returned to.
+ @param[in] val A non-zero value to be returned from setjmp.
+
+ @return After longjmp is completed, program execution continues as if the
corresponding invocation of the setjmp macro had just returned the value
specified by val. The longjmp function cannot cause the setjmp macro to
return the value 0; if val is 0, the setjmp macro returns the value 1.
diff --git a/StdLib/Include/signal.h b/StdLib/Include/signal.h index 6c1ff1b..26f8d6b 100644 --- a/StdLib/Include/signal.h +++ b/StdLib/Include/signal.h @@ -1,28 +1,25 @@ /** @file
- The header <signal.h> declares a type and two functions and defines several
+ This file declares a type and two functions and defines several
macros, for handling various signals (conditions that may be reported during
program execution).
- The UEFI implementation of <signal.h> maps signals onto the UEFI
- event mechanism.
+ For historical reasons; programs expect signal to be declared
+ in <sys/signal.h>. The signal function is documented in <sys/signal.h>.
- An implementation need not generate any of these signals, except as a result
- of explicit calls to the raise function. Additional signals and pointers to
- undeclarable functions, with macro definitions beginning, respectively, with
- the letters SIG and an uppercase letter or with SIG_ and an uppercase letter
- may also be specified by the implementation. The complete set of signals,
- their semantics, and their default handling is implementation-defined; all
- signal numbers shall be positive.
+ The signal function is declared in the C Standard as:<BR>
+ void (*signal(int sig, void (*func)(int)))(int);
-Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
+ The EDK II implementation of the library or base firmware does not generate
+ any of these signals, except as a result of explicit calls to the raise function.
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _SIGNAL_H
#define _SIGNAL_H
@@ -36,7 +33,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. This, possibly machine specific, type is defined in <machine/signal.h>.
*/
-/** The following three macros expand to constant expressions with distinct
+/** @{
+ The following three macros expand to constant expressions with distinct
values that have type compatible with the second argument to, and the
return value of, the signal function, and whose values compare unequal to
the address of any declarable function.
@@ -44,11 +42,13 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define SIG_IGN ((__sighandler_t *) 0)
#define SIG_DFL ((__sighandler_t *) 1)
#define SIG_ERR ((__sighandler_t *) 3)
+/*@}*/
-/** The following members expand to positive integer constant expressions with
+/** @{
+ The following macros expand to positive integer constant expressions with
type int and distinct values that are the signal numbers, each
corresponding to the specified condition.
- Many existing programs expect these to be macros.
+ The C95 specification requires these to be macros.
**/
#define SIGINT __SigInt ///< receipt of an interactive attention signal
#define SIGILL __SigIll ///< detection of an invalid function image, such as an invalid instruction
@@ -66,24 +66,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define SIGPIPE __SigPipe ///< Added for Posix timer functions
#define SIGQUIT __SigQuit ///< Added for Posix timer functions
#define SIG_LAST __Sig_Last ///< One more than the largest signal number
+/*@}*/
__BEGIN_DECLS
-/* For historical reasons; programs expect signal to be declared
- in <sys/signal.h>. The function is documented in <sys/signal.h>.
-
- The function is declared in the C Standard as:<BR>
- void (*signal(int sig, void (*func)(int)))(int);
-*/
-
/** Send a signal.
The raise function carries out the actions described for signal,
in <sys/signal.h>, for the signal sig. If a signal handler is called, the
- raise function shall not return until after the signal handler does.
+ raise function does not return until after the signal handler does.
@return The raise function returns zero if successful,
- nonzero if unsuccessful.
+ or nonzero if unsuccessful.
**/
int raise(int sig);
diff --git a/StdLib/Include/stdarg.h b/StdLib/Include/stdarg.h index b966a5c..b9de364 100644 --- a/StdLib/Include/stdarg.h +++ b/StdLib/Include/stdarg.h @@ -1,54 +1,53 @@ /** @file
- The header <stdarg.h> declares a type and defines three macros, for advancing
- through a list of arguments whose number and types are not known to the
- called function when it is translated.
-
- A function may be called with a variable number of arguments of varying types.
- Its parameter list contains one or more parameters. The rightmost parameter
- plays a special role in the access mechanism, and will be designated paramN
- in this description.
-
- The type va_list is a type suitable for holding information needed by the
- macros va_start, va_arg, and va_end. If access to the varying arguments
- is desired, the called function shall declare an object (referred to as ap
- in these descriptions) having type va_list. The object ap may be passed as
- an argument to another function; if that function invokes the va_arg macro
- with parameter ap, the value of ap in the calling function is indeterminate
- and shall be passed to the va_end macro prior to any further reference to ap.
-
- The va_start and va_arg macros shall be implemented as macros, not as actual
- functions. It is unspecified, by the C library standards, whether va_end
- is a macro or an identifier declared with external linkage. If a macro
- definition is suppressed in order to access an actual function, or a
- program defines an external identifier with the name va_end, the behavior
- is undefined. The va_start and va_end macros shall be invoked in the
- function accepting a varying number of arguments, if access to the varying
- arguments is desired.
-
-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
+ This header, <stdarg.h>, declares type va_list and defines macros: va_start, va_arg, va_end;
+ for advancing through a list of arguments whose number and types are not known to the
+ called function when it is translated.
+
+ A function may be called with a variable number of arguments of varying types.
+ The rightmost argument plays a special role in the access mechanism, and will
+ be designated paramN in this and subsequent descriptions.
+
+ The type va_list is a type suitable for holding information needed by the
+ macros va_start, va_arg, and va_end. If access to the varying arguments
+ is desired, the called function shall declare an object (referred to as ap
+ in these descriptions) having type va_list. The object ap may be passed as
+ an argument to another function; if the receiving function invokes the va_arg macro
+ with parameter ap, the value of ap in the calling function becomes indeterminate
+ and must be passed to the va_end macro prior to any further reference to ap.
+
+ The va_start and va_arg macros must be implemented as macros, not as actual
+ functions. The va_start and va_end macros must be invoked in the
+ function accepting a varying number of arguments, if access to the varying
+ arguments is desired.
+
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _STDARG_H
#define _STDARG_H
#include <sys/EfiCdefs.h>
-/** The type va_list is a type suitable for holding information needed by the
+/** @{
+ The type va_list is a type suitable for holding information needed by the
macros va_start, va_arg, and va_end.
+
+ Depending upon compiler or CPU architecture, different definitions are required.
**/
#if defined(__GNUC__)
typedef __builtin_va_list va_list;
#else
#define va_list VA_LIST
#endif
+/*@}*/
-/** The va_start macro shall be invoked before any access to the unnamed arguments.
+/** @{
+ The va_start macro must be invoked before any access to the unnamed arguments.
The va_start macro initializes ap for subsequent use by va_arg and va_end.
Synopsys: void va_start(va_list ap, paramN);
@@ -71,8 +70,10 @@ typedef __builtin_va_list va_list; #else
#define va_start VA_START
#endif
+/*@}*/
-/** The va_arg macro expands to an expression that has the type and value of
+/** @{
+ The va_arg macro expands to an expression that has the type and value of
the next argument in the call. The parameter ap shall be the same as the
va_list ap initialized by va_start. Each invocation of va_arg modifies ap
so that the values of successive arguments are returned in turn. The
@@ -99,8 +100,10 @@ typedef __builtin_va_list va_list; #else
#define va_arg VA_ARG
#endif
+/*@}*/
-/** The va_end macro facillitates a normal return from the function whose
+/** @{
+ The va_end macro facillitates a normal return from the function whose
variable argument list was referred to by the expansion of va_start that
initialized the va_list ap.
@@ -119,12 +122,16 @@ typedef __builtin_va_list va_list; #else
#define va_end VA_END
#endif
+/*@}*/
-/** For BSD compatibility. **/
+/** @{
+ For BSD compatibility.
+**/
#if defined(__GNUC__)
#define va_copy __builtin_va_copy
#else
#define va_copy(s,d) (s) = (d)
#endif
+/*@}*/
#endif /* _STDARG_H */
diff --git a/StdLib/Include/stdbool.h b/StdLib/Include/stdbool.h index 42dcd86..3208866 100644 --- a/StdLib/Include/stdbool.h +++ b/StdLib/Include/stdbool.h @@ -1,8 +1,12 @@ /** @file
- The header <stdbool.h> defines four macros: bool, true, false,
- and __bool_true_false_are_defined.
+ Macros to simplify boolean expressions and operations.
- The macro bool expands to _Bool.
+ This header is not specified by the C95 standard but is included here for
+ operational convenience.
+
+ The macro bool expands to _Bool, as required by the C99 specification.
+ This subsequently expands to BOOLEAN, is a UEFI data type which is automatically
+ defined correctly for the target CPU architecture.
The remaining three macros are suitable for use in #if preprocessing
directives. They are true, which expands to the integer constant 1,
@@ -12,23 +16,22 @@ A program may undefine and perhaps then redefine the
macros bool, true, and false.
- Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
+ http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
**/
#ifndef _STDBOOL_H
#define _STDBOOL_H
#include <sys/EfiCdefs.h>
-#define bool _Bool
-#define true 1
-#define false 0
+#define bool _Bool
+#define true 1
+#define false 0
#define __bool_true_false_are_defined 1
#endif /* _STDBOOL_H */
diff --git a/StdLib/Include/stddef.h b/StdLib/Include/stddef.h index c97d564..ce4483a 100644 --- a/StdLib/Include/stddef.h +++ b/StdLib/Include/stddef.h @@ -1,64 +1,68 @@ /** @file
- Common Definitions.
+ Common "Standard" Definitions.
-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
+ The files stddef.h and stdlib.h are "catch all" headers for definitions and declarations
+ that don't fit well in the other headers. There are two separate header files because
+ the contents of <stddef.h> are valid in both freestanding and hosted environment, while the
+ header <stdlib.h> contains elements that are only valid in a hosted environment.
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ This means that the elements in this file may not impose dependencies on headers other than
+ <float.h>, <iso646.h>, <limits.h>, <stdarg.h>, <stdbool.h>, and (of course) <sys/EfiCdefs.h>.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _STDDEF_H
#define _STDDEF_H
#include <sys/EfiCdefs.h>
-/** ptrdiff_t is the signed integer type of the result of subtracting two pointers.
-**/
#ifdef _EFI_PTRDIFF_T_
+ /** ptrdiff_t is the signed integer type of the result of subtracting two pointers. **/
typedef _EFI_PTRDIFF_T_ ptrdiff_t;
#undef _EFI_PTRDIFF_T_
#endif
-/** size_t is the unsigned integer type of the result of the sizeof operator.
-**/
#ifdef _EFI_SIZE_T_
+ /** size_t is the unsigned integer type of the result of the sizeof operator. **/
typedef _EFI_SIZE_T_ size_t;
#undef _EFI_SIZE_T_
#undef _BSD_SIZE_T_
#endif
-/** wchar_t is an integer type whose range of values can represent distinct
- codes for all members of the largest extended character set specified among
- the supported locales. The null character shall have the code value zero.
-**/
#ifndef __cplusplus
#ifdef _EFI_WCHAR_T
+ /** wchar_t is an integer type whose range of values can represent distinct
+ codes for all members of the largest extended character set specified among
+ the supported locales. The null character shall have the code value zero.
+ **/
typedef _EFI_WCHAR_T wchar_t;
#undef _EFI_WCHAR_T
#undef _BSD_WCHAR_T_
#endif
#endif
-/** NULL expands to an implementation-defined null pointer constant.
+/** @def NULL
+ A macro that expands to a null pointer constant.<BR>
NULL is defined in MdePkg/Include/Base.h which is automatically included
by the EDK II build tools.
**/
-/** offsetof(type, member-designator) expands to an integer constant expression
- that has type size_t, the value of which is the offset in bytes, to the
- structure member (designated by member-designator), from the beginning of
- its structure (designated by type). The type and member designator shall be
- such that given<BR>
- static type t;<BR>
- then the expression &(t.member-designator) evaluates to an address constant.
- (If the specified member is a bit-field, the behavior is undefined.)
+/** The offsetof macro determines the offset of the beginning of a structure
+ member from the beginning of the structure.
+
+ The macro expands to an integer constant expression that has type size_t,
+ the value of which is the offset in bytes, to the structure member (Member),
+ from the beginning of its structure (StrucName).
Alliased to OFFSET_OF which is defined in MdePkg/Include/Base.h which is
automatically included by the EDK II build tools.
**/
-#define offsetof(type, member) OFFSET_OF(type, member)
+#define offsetof(StrucName, Member) OFFSET_OF(StrucName, Member)
#endif /* _STDDEF_H */
diff --git a/StdLib/Include/stdio.h b/StdLib/Include/stdio.h index 7c3586c..666e190 100644 --- a/StdLib/Include/stdio.h +++ b/StdLib/Include/stdio.h @@ -1,4 +1,119 @@ -/*-
+/** @file
+ Macros, types, and functions for performing I/O.
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ################### Operations on files. ####
+ int remove (const char *FileName);
+ int rename (const char *, const char *);
+ FILE *tmpfile (void);
+ char *tmpnam (char *);
+
+ ################### File access functions. ####
+ int fclose (FILE *);
+ int fflush (FILE *);
+ FILE *fopen (const char * __restrict ,
+ const char * __restrict);
+ FILE *freopen (const char * __restrict,
+ const char * __restrict, FILE * __restrict);
+ void setbuf (FILE * __restrict, char * __restrict);
+ int setvbuf (FILE * __restrict, char * __restrict,
+ int, size_t);
+
+ ################### Formatted Input/Output Functions. ####
+ int fprintf (FILE * __restrict stream,
+ const char * __restrict format, ...);
+ int fscanf (FILE * __restrict, const char * __restrict, ...);
+ int printf (const char * __restrict, ...);
+ int scanf (const char * __restrict, ...);
+ int sprintf (char * __restrict, const char * __restrict, ...);
+ int sscanf (const char * __restrict,
+ const char * __restrict, ...);
+ int vfprintf (FILE * __restrict,
+ const char * __restrict, va_list);
+ int vprintf (const char * __restrict, va_list);
+ int vsprintf (char * __restrict,
+ const char * __restrict, va_list);
+
+ ################### Character Input/Output Functions. ####
+ int fgetc (FILE *);
+ char *fgets (char * __restrict, int, FILE * __restrict);
+ int fputc (int, FILE *);
+ int fputs (const char * __restrict, FILE * __restrict);
+ int getc (FILE *);
+ int getchar (void);
+ char *gets (char *);
+ int putc (int, FILE *);
+ int putchar (int);
+ int puts (const char *);
+ int ungetc (int, FILE *);
+
+ ################### Direct Input/Output Functions. ####
+ size_t fread (void * __restrict, size_t, size_t,
+ FILE * __restrict);
+ size_t fwrite (const void * __restrict, size_t, size_t,
+ FILE * __restrict);
+
+ ################### File Positioning Functions. ####
+ int fgetpos (FILE * __restrict, fpos_t * __restrict);
+ int fseek (FILE *, long, int);
+ int fsetpos (FILE *, const fpos_t *);
+ long ftell (FILE *);
+ void rewind (FILE *);
+
+ ################### Error-handling Functions. ####
+ void clearerr (FILE *);
+ int feof (FILE *);
+ int ferror (FILE *);
+ void perror (const char *);
+
+ ################### Functions NOT specified by C95 ####
+
+ FILE *fdopen (int, const char *);
+ void flockfile (FILE *);
+ int ftrylockfile (FILE *);
+ void funlockfile (FILE *);
+ int getc_unlocked (FILE *);
+ int getchar_unlocked(void);
+ int putc_unlocked (int, FILE *);
+ int putchar_unlocked(int);
+ int pclose (FILE *);
+ FILE *popen (const char *, const char *);
+ int snprintf (char * __restrict, size_t,
+ const char * __restrict, ...);
+ int vsnprintf (char * __restrict, size_t,
+ const char * __restrict, va_list);
+ char *mkdtemp (char *);
+ int mkstemp (char *);
+ char *mktemp (char *);
+ char *tempnam (const char *, const char *);
+ int fseeko (FILE *, off_t, int);
+ char *fgetln (FILE * __restrict, size_t * __restrict);
+ char *fparseln (FILE *, size_t *, size_t *, const char[3], int);
+ int fpurge (FILE *);
+ void setbuffer (FILE *, char *, int);
+ int setlinebuf (FILE *);
+ int vasprintf (char ** __restrict, const char * __restrict,
+ va_list);
+ int vscanf (const char * __restrict, va_list);
+ int vsscanf (const char * __restrict,
+ const char * __restrict, va_list);
+@endverbatim
+
+ @note To fit things in six character monocase externals, the stdio
+ code uses the prefix `__s' for stdio objects, typically followed
+ by a three-character attempt at a mnemonic.
+
+
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
*
@@ -30,9 +145,8 @@ * SUCH DAMAGE.
*
* @(#)stdio.h 8.5 (Berkeley) 4/29/95
+ NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp
*/
-/* $NetBSD: stdio.h,v 1.66.2.3 2007/08/24 20:07:38 liamjfoy Exp $ */
-
#ifndef _STDIO_H_
#define _STDIO_H_
@@ -42,16 +156,27 @@ #include <machine/ansi.h>
#ifdef _EFI_SIZE_T_
+ /** size_t is the unsigned integer type of the result of the sizeof operator. **/
typedef _EFI_SIZE_T_ size_t;
#undef _EFI_SIZE_T_
#undef _BSD_SIZE_T_
#endif
-/*
- * This is fairly grotesque, but pure ANSI code must not inspect the
- * innards of an fpos_t anyway. The library internally uses off_t,
- * which we assume is exactly as big as eight chars.
- */
+/** @{
+ An object type capable of holding all information necessary to specify any
+ position within a file.
+
+ Each wide-oriented stream has an associated mbstate_t object that stores the
+ current parse state of the stream. A successful call to fgetpos stores a
+ representation of the value of this mbstate_t object as part of the value
+ of the fpos_t object. A later successful call to fsetpos using the same
+ stored fpos_t value restores the value of the associated mbstate_t object
+ as well as the position within the controlled stream.
+
+ This is fairly grotesque, but pure ANSI code must not inspect the
+ innards of an fpos_t anyway. The library internally uses off_t,
+ which we assume is exactly as big as eight chars.
+**/
#if (!defined(_ANSI_SOURCE) && !defined(__STRICT_ANSI__)) || defined(_LIBC)
typedef __off_t fpos_t;
#else
@@ -59,14 +184,7 @@ typedef struct __sfpos { __off_t _pos;
} fpos_t;
#endif
-
-#define _FSTDIO /* Define for new stdio with functions. */
-
-/*
- * NB: to fit things in six character monocase externals, the stdio
- * code uses the prefix `__s' for stdio objects, typically followed
- * by a three-character attempt at a mnemonic.
- */
+/*@}*/
/* stdio buffers */
struct __sbuf {
@@ -74,15 +192,14 @@ struct __sbuf { int _size;
};
-/*
- * stdio state variables.
+/** Structure which holds all the information needed to control a stream or file.
*
- * The following always hold:
+ * The following always hold:<BR>
*
- * if (_flags&(__SLBF|__SWR)) == (__SLBF|__SWR),
- * _lbfsize is -_bf._size, else _lbfsize is 0
- * if _flags&__SRD, _w is 0
- * if _flags&__SWR, _r is 0
+ * - if (_flags&(__SLBF|__SWR)) == (__SLBF|__SWR),
+ * - _lbfsize is -_bf._size, else _lbfsize is 0
+ * - if _flags&__SRD, _w is 0
+ * - if _flags&__SWR, _r is 0
*
* This ensures that the getc and putc macros (or inline functions) never
* try to write or read from a file that is in `read' or `write' mode.
@@ -98,133 +215,295 @@ struct __sbuf { * _ub._base becomes non-nil (i.e., a stream has ungetc() data iff
* _ub._base!=NULL) and _up and _ur save the current values of _p and _r.
*
- * NB: see WARNING above before changing the layout of this structure!
*/
typedef struct __sFILE {
- unsigned char *_p; /* current position in (some) buffer */
- int _r; /* read space left for getc() */
- int _w; /* write space left for putc() */
- unsigned short _flags; /* flags, below; this FILE is free if 0 */
- short _file; /* fileno, if Unix descriptor, else -1 */
- struct __sbuf _bf; /* the buffer (at least 1 byte, if !NULL) */
- int _lbfsize; /* 0 or -_bf._size, for inline putc */
+ unsigned char *_p; /**< current position in (some) buffer */
+ int _r; /**< read space left for getc() */
+ int _w; /**< write space left for putc() */
+ unsigned short _flags; /**< flags, below; this FILE is free if 0 */
+ short _file; /**< fileno, if Unix descriptor, else -1 */
+ struct __sbuf _bf; /**< the buffer (at least 1 byte, if !NULL) */
+ int _lbfsize; /**< 0 or -_bf._size, for inline putc */
/* operations */
- void *_cookie; /* cookie passed to io functions */
+ void *_cookie; /**< cookie passed to io functions */
int (*_close)(void *);
int (*_read) (void *, char *, int);
fpos_t (*_seek) (void *, fpos_t, int);
int (*_write)(void *, const char *, int);
- /* file extension */
+ /** file extension */
struct __sbuf _ext;
- /* separate buffer for long sequences of ungetc() */
- unsigned char *_up; /* saved _p when _p is doing ungetc data */
- int _ur; /* saved _r when _r is counting ungetc data */
+ /** @{
+ Separate buffer for long sequences of ungetc().
+ **/
+ unsigned char *_up; /**< saved _p when _p is doing ungetc data */
+ int _ur; /**< saved _r when _r is counting ungetc data */
+ /*@}*/
/* tricks to meet minimum requirements even when malloc() fails */
- unsigned char _ubuf[3]; /* guarantee an ungetc() buffer */
- unsigned char _nbuf[1]; /* guarantee a getc() buffer */
+ unsigned char _ubuf[3]; /**< guarantee an ungetc() buffer */
+ unsigned char _nbuf[1]; /**< guarantee a getc() buffer */
- /* separate buffer for fgetln() when line crosses buffer boundary */
+ /** separate buffer for fgetln() when line crosses buffer boundary */
struct __sbuf _lb; /* buffer for fgetln() */
/* Unix stdio files get aligned to block boundaries on fseek() */
- int _blksize; /* stat.st_blksize (may be != _bf._size) */
- fpos_t _offset; /* current lseek offset */
+ int _blksize; /**< stat.st_blksize (may be != _bf._size) */
+ fpos_t _offset; /**< current lseek offset */
} FILE;
__BEGIN_DECLS
extern FILE __sF[];
__END_DECLS
-#define __SLBF 0x0001 /* line buffered */
-#define __SNBF 0x0002 /* unbuffered */
-#define __SRD 0x0004 /* OK to read */
-#define __SWR 0x0008 /* OK to write */
+#define __SLBF 0x0001 /**< line buffered */
+#define __SNBF 0x0002 /**< unbuffered */
+#define __SRD 0x0004 /**< OK to read */
+#define __SWR 0x0008 /**< OK to write */
/* RD and WR are never simultaneously asserted */
-#define __SRW 0x0010 /* open for reading & writing */
-#define __SEOF 0x0020 /* found EOF */
-#define __SERR 0x0040 /* found error */
-#define __SMBF 0x0080 /* _buf is from malloc */
-#define __SAPP 0x0100 /* fdopen()ed in append mode */
-#define __SSTR 0x0200 /* this is an sprintf/snprintf string */
-#define __SOPT 0x0400 /* do fseek() optimization */
-#define __SNPT 0x0800 /* do not do fseek() optimization */
-#define __SOFF 0x1000 /* set iff _offset is in fact correct */
-#define __SMOD 0x2000 /* true => fgetln modified _p text */
-#define __SALC 0x4000 /* allocate string space dynamically */
+#define __SRW 0x0010 /**< open for reading & writing */
+#define __SEOF 0x0020 /**< found EOF */
+#define __SERR 0x0040 /**< found error */
+#define __SMBF 0x0080 /**< _buf is from malloc */
+#define __SAPP 0x0100 /**< fdopen()ed in append mode */
+#define __SSTR 0x0200 /**< this is an sprintf/snprintf string */
+#define __SOPT 0x0400 /**< do fseek() optimization */
+#define __SNPT 0x0800 /**< do not do fseek() optimization */
+#define __SOFF 0x1000 /**< set iff _offset is in fact correct */
+#define __SMOD 0x2000 /**< true => fgetln modified _p text */
+#define __SALC 0x4000 /**< allocate string space dynamically */
-/*
- * The following three definitions are for ANSI C, which took them
- * from System V, which brilliantly took internal interface macros and
- * made them official arguments to setvbuf(), without renaming them.
- * Hence, these ugly _IOxxx names are *supposed* to appear in user code.
- *
- * Although numbered as their counterparts above, the implementation
- * does not rely on this.
+/* The following three definitions are for ANSI C, which took them
+ from System V, which brilliantly took internal interface macros and
+ made them official arguments to setvbuf(), without renaming them.
+ Hence, these ugly _IOxxx names are *supposed* to appear in user code.
+
+ Although numbered as their counterparts above, the implementation
+ does not rely on this.
*/
-#define _IOFBF 0 /* setvbuf should set fully buffered */
-#define _IOLBF 1 /* setvbuf should set line buffered */
-#define _IONBF 2 /* setvbuf should set unbuffered */
+#define _IOFBF 0 /**< setvbuf should set fully buffered */
+#define _IOLBF 1 /**< setvbuf should set line buffered */
+#define _IONBF 2 /**< setvbuf should set unbuffered */
-#define BUFSIZ 1024 /* size of buffer used by setbuf */
-#define EOF (-1)
+#define BUFSIZ 1024 /**< size of buffer used by setbuf */
+#define EOF (-1) /**< A constant integer expression indicating end-of-file. */
-/*
- * FOPEN_MAX is a minimum maximum, and is the number of streams that
- * stdio can provide without attempting to allocate further resources
- * (which could fail). Do not use this for anything.
+/** FOPEN_MAX is a minimum maximum, and is the number of streams that
+ stdio can provide without attempting to allocate further resources
+ (which could fail). Do not use this for anything.
*/
#define FOPEN_MAX OPEN_MAX /* must be <= OPEN_MAX <sys/syslimits.h> */
+
+/** Size needed for an array of char large enough to hold the longest file name string. */
#define FILENAME_MAX PATH_MAX /* must be <= PATH_MAX <sys/syslimits.h> */
+/** Size needed for an array of char large enough to hold the file name string
+ generated by the tmpname() function.
+**/
#define L_tmpnam PATH_MAX /* must be == PATH_MAX */
#ifndef TMP_MAX
-#define TMP_MAX 308915776 /* Legacy */
+#define TMP_MAX 308915776 /**< The maximum number of unique file names
+ that can be generated by tmpnam(). **/
#endif
/* Always ensure that these are consistent with <fcntl.h>! */
#ifndef SEEK_SET
-#define SEEK_SET 0 /* set file offset to offset */
+#define SEEK_SET 0 /**< set file offset to offset */
#endif
#ifndef SEEK_CUR
-#define SEEK_CUR 1 /* set file offset to current plus offset */
+#define SEEK_CUR 1 /**< set file offset to current plus offset */
#endif
#ifndef SEEK_END
-#define SEEK_END 2 /* set file offset to EOF plus offset */
+#define SEEK_END 2 /**< set file offset to EOF plus offset */
#endif
-#define stdin (&__sF[0])
-#define stdout (&__sF[1])
-#define stderr (&__sF[2])
+#define stdin (&__sF[0]) /**< FILE reference for the STanDard INput stream. */
+#define stdout (&__sF[1]) /**< FILE reference for the STanDard OUTput stream. */
+#define stderr (&__sF[2]) /**< FILE reference for the STanDard ERRor stream. */
-/*
- * Functions defined in ANSI C standard.
- */
__BEGIN_DECLS
-void clearerr(FILE *);
-int fclose (FILE *);
-int feof (FILE *);
-int ferror (FILE *);
-int fflush (FILE *);
-int fgetc (FILE *);
-int fgetpos (FILE * __restrict, fpos_t * __restrict);
-char *fgets (char * __restrict, int, FILE * __restrict);
-FILE *fopen (const char * __restrict , const char * __restrict);
+/* Functions defined in C95 standard. ###################################### */
+
+/* ################ Operations on files. */
+
+/** Remove (delete) a file.
+
+ @param[in] FileName The path to the file to be removed.
+
+ @retval Zero The operation succeeded.
+ @retval Non-zero The operation failed.
+**/
+int remove (const char *FileName);
+
+/** Rename the file named OldName to NewName.
+
+ @param[in] OldName The name of the existing file to be renamed.
+ @param[in] NewName The new name of the file.
+
+ @retval Zero The operation succeeded.
+ @retval Non-zero The operation failed. OldName still exists and has been unmodified.
+ If OldName does not exist, or a file named NewName already exists,
+ rename() will fail are return a non-zero value.
+**/
+int rename (const char *OldName, const char *NewName);
+
+/** Create a guaranteed unique temporary file.
+ A binary file is created in the _PATH_TMP directory that is guaranteed to
+ have a unique name. The file will be open for update with mode "wb+" and
+ its FILE pointer returned upon successfull completion. When the file is
+ closed, or when the creating program terminates, the file will be removed.
+
+ @retval NULL The temporary file could not be created.
+ @retval non-NULL The returned value is a pointer to the FILE object
+ associated with the newly created and open temporary file.
+**/
+FILE *tmpfile (void);
+
+/** Generate a string that is a valid file name, in the _PATH_TMP directory, that
+ is not the same as the name of an existing file. The function can potentially
+ generate up to TMP_MAX different strings.
+
+ @param[out] Buffer A pointer to an array of at least L_tmpnam char elements.
+ or NULL. If non-NULL, the tmpnam function writes its
+ result into that array and returns the argument
+ as its value.
+
+ @return If no suitable string can be generated a NULL pointer is returned.
+ Otherwise, if Buffer is NULL, the result is produced in an internal
+ static object and a pointer to that object is returned. If Buffer
+ is non-null, the results are written into the array pointed to by
+ Buffer and Buffer is returned.
+**/
+char *tmpnam (char *Buffer);
+
+/* ################ File access functions. */
+
+/** Close the open stream, specified by fp, and de-associate it from any file or device.
+
+ @param[in] fp Pointer to a stream object, of type FILE, associated with a
+ file or device.
+
+ @retval Zero The stream was successfully closed.
+ @retval Non-zero There was an error closing the stream.
+**/
+int fclose (FILE *fp);
+
+/** Empties any buffers associated with the stream specified by fp.
+
+ @param[in] fp Pointer to a stream object, of type FILE, associated with a
+ file or device.
+
+ @retval Zero The stream's buffers were successfully emptied.
+ @retval EOF There was an error writing to the stream.
+**/
+int fflush (FILE *fp);
+
+/** Associates a file, named by Path, with a stream and prepares it for subsequent
+ operations.
+
+ The parameter Mode points to a string specifying behavior characteristics for
+ the opened file. The recognized Mode strings are:
+ - r Open text file for reading.
+ - w Truncate file to zero length or create text file for writing.
+ - a Open or create a text file for writing at end-of-file (append).
+ - rb Open binary file for reading.
+ - wb Truncate file to zero length or create binary file for writing.
+ - ab Open or create a binary file for writing at end-of-file (append).
+ - r+ Open text file for update (reading and writing).
+ - w+ Truncate file to zero length or create text file for update.
+ - a+ Open or create a text file for update, writing at end-of-file.
+ - r+b or rb+ Open binary file for update (reading and writing).
+ - w+b or wb+ Truncate file to zero length or create binary file for update.
+ - a+b or ab+ Open or create a binary file for update, writing at end-of-file.
+
+ Opening a file with read mode fails if the file does not exist.
+
+ Opening a file with append mode causes all writes to the file to be forced to
+ the current end-of-file, regardless of any intervening calls to fseek.
+
+ @param[in] Path The path or name of the file or device to open.
+ @param[in] Mode The mode in which the file is to be opened.
+
+ @return A pointer to a FILE object associated with the opened file is returned
+ if the file was opened successfully. Otherwise, NULL is returned.
+**/
+FILE *fopen (const char * __restrict Path, const char * __restrict Mode);
+
+/** Closes the file associated with Ofp then opens the file specified by Path and associates it with
+ stream Ofp.
+
+ Any errors that occur when closing Ofp are ignored. The file specified by Path is opened with mode Mode
+ and associated with stream Ofp instead of producing a new stream object.
+
+ If Path is NULL, the mode of the file associated with Ofp is changed to Mode.
+
+ @param[in] Path The path or name of the file or device to open.
+ @param[in] Mode The mode in which the file is to be opened.
+ @param[in] Ofp Pointer to the FILE object to be closed and associated with the new file.
+
+ @return If Path was not able to be opened, or the mode changed, NULL is returned;
+ otherwise Ofp is returned.
+**/
+FILE *freopen (const char * __restrict Path, const char * __restrict Mode, FILE * __restrict Ofp);
+
+/** Establishes Fully Buffered or Non-buffered mode for a stream, fp, using Buff as the buffer.
+
+ The file associated with fp must have been successfully opened with no operations, other than
+ possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
+
+ If Buff is non-NULL, the stream associated with fp is set to Fully Buffered mode using the
+ array pointed to by Buff as the buffer. The buffer is assumed to be BUFSIZ char long.
+ This is equivalent to calling setvbuf(fp, Buff, _IOFBF, BUFSIZ);
+
+ If Buff is NULL, stream fp is set to Non-buffered mode.
+ This is equivalent to calling setvbuf(fp, NULL, _IONBF, 0);
+
+ @param[in] fp Pointer to the FILE object which will have its buffer set.
+ @param[in] Buff The buffer to use for fp, or NULL.
+**/
+void setbuf (FILE * __restrict fp, char * __restrict Buff);
+
+/** Establishes a buffering mode and buffer for use by operations performed on the file associated with fp.
+
+ The file associated with fp must have been successfully opened with no operations, other than
+ possibly an unsuccessful call to setvbuf, performed prior to the call to setbuf.
+
+ Parameter BufMode determines how stream fp will be buffered:
+ - _IOFBF causes I/O to be fully buffered.
+ - _IOLBF causes I/O to be line buffered.
+ - _IONBF causes I/O to be unbuffered.
+
+ If Buff is not NULL, it points to an array to be used as an I/O buffer for stream fp. The
+ buffer is set to BufSize char in length. Otherwise, an array of BufSize char is allocated
+ by the setvbuf function if BufMode is not _IONBF.
+
+ It is an error for BufSize to be zero unless BufMode is _IONBF, in which case BufSize is ignored.
+
+ @param[in] fp Pointer to the FILE object which will have its buffer set.
+ @param[in] Buff The buffer to use for fp, or NULL.
+ @param[in] BufMode The buffering mode to use.
+ @param[in] BufSize The size of the buffer to use, specified in char.
+
+ @retval Zero The buffer and mode were established successfully.
+ @retval Non-zero The request can not be honored, or an invalid value for BufMode was given.
+**/
+int setvbuf (FILE * __restrict fp, char * __restrict Buff, int BufMode, size_t BufSize);
+
+/* ################ Formatted Input/Output Functions. */
/** The fprintf function writes output to the stream pointed to by stream,
under control of the string pointed to by format that specifies how
subsequent arguments are converted for output. If there are insufficient
- arguments for the format, the behavior is undefined. If the format is
+ arguments for the format, the behavior is indeterminate. If the format is
exhausted while arguments remain, the excess arguments are evaluated
(as always) but are otherwise ignored. The fprintf function returns when
the end of the format string is encountered.
- The format shall be a multibyte character sequence, beginning and ending in
- its initial shift state. The format is composed of zero or more directives:
+ The format is interpreted as a multibyte character sequence, beginning and ending
+ in its initial shift state. The format is composed of zero or more directives:
ordinary multibyte characters (not %), which are copied unchanged to the
output stream; and conversion specifications, each of which results in
fetching zero or more subsequent arguments, converting them, if applicable,
@@ -248,8 +527,8 @@ FILE *fopen (const char * __restrict , const char * __restrict); conversions. The precision takes the form of a period (.) followed
either by an asterisk * (described later) or by an optional decimal
integer; if only the period is specified, the precision is taken as
- zero. If a precision appears with any other conversion specifier, the
- behavior is undefined.
+ zero. If a precision appears with any other conversion specifier, it
+ is ignored.
- An optional length modifier that specifies the size of the argument.
- A conversion specifier character that specifies the type of conversion
to be applied.
@@ -259,7 +538,7 @@ FILE *fopen (const char * __restrict , const char * __restrict); precision. The arguments specifying field width, or precision, or both, shall
appear (in that order) before the argument (if any) to be converted. A negative
field width argument is taken as a - flag followed by a positive field width.
- A negative precision argument is taken as if the precision were omitted.
+ A negative precision argument is interpreted as if the precision were omitted.
The flag characters and their meanings are:
- The result of the conversion is left-justified within the field.
@@ -271,24 +550,24 @@ FILE *fopen (const char * __restrict , const char * __restrict); if a signed conversion results in no characters, a space is
prefixed to the result. If the space and + flags both appear, the
space flag is ignored.
- # The result is converted to an "alternative form". For o
- conversion, it increases the precision, if and only if necessary,
- to force the first digit of the result to be a zero (if the value
- and precision are both 0, a single 0 is printed). For x (or X)
- conversion, a nonzero result has 0x (or 0X) prefixed to it. For e,
- E, f, F, g, and G conversions, the result of converting a
- floating-point number always contains a decimal-point character,
- even if no digits follow it. (Normally, a decimal-point character
- appears in the result of these conversions only if a digit follows
- it.) For g and G conversions, trailing zeros are not removed from
- the result. For other conversions, the behavior is undefined.
+ # The result is converted to an "alternative form".
+ - For o conversion, it increases the precision, if and only if necessary,
+ to force the first digit of the result to be a zero (if the value
+ and precision are both 0, a single 0 is printed).
+ - For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it.
+ - For e, E, f, F, g, and G conversions, the result of converting a
+ floating-point number always contains a decimal-point character,
+ even if no digits follow it. (Normally, a decimal-point character
+ appears in the result of these conversions only if a digit follows
+ it.)
+ - For g and G conversions, trailing zeros are not removed from
+ the result. For other conversions, it is ignored.
0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading
zeros (following any indication of sign or base) are used to pad to
the field width rather than performing space padding, except when
converting an infinity or NaN. If the 0 and - flags both appear,
the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
- precision is specified, the 0 flag is ignored. For other
- conversions, the behavior is undefined.
+ precision is specified, the 0 flag is ignored.
The length modifiers and their meanings are:
hh Specifies that a following d, i, o, u, x, or X conversion specifier
@@ -329,7 +608,7 @@ FILE *fopen (const char * __restrict , const char * __restrict); applies to a long double argument.
If a length modifier appears with any conversion specifier other than as
- specified above, the behavior is undefined.
+ specified above, it is ignored.
The conversion specifiers and their meanings are:
d,i The int argument is converted to signed decimal in the style
@@ -354,12 +633,9 @@ FILE *fopen (const char * __restrict , const char * __restrict); decimal-point character appears. If a decimal-point character
appears, at least one digit appears before it. The value is rounded
to the appropriate number of digits.
- A double argument representing an infinity is converted in one
- of the styles [-]inf or [-]infinity - which style is
- implementation-defined. A double argument representing a NaN is
- converted in one of the styles [-]nan or [-]nan(n-char-sequence)
- - which style, and the meaning of any n-char-sequence, is
- implementation-defined. The F conversion specifier produces INF,
+ A double argument representing an infinity is converted in
+ the style [-]inf. A double argument representing a NaN is
+ converted in the style [-]nan. The F conversion specifier produces INF,
INFINITY, or NAN instead of inf, infinity, or nan, respectively.
e,E A double argument representing a floating-point number is
converted in the style [-]d.ddd e[+-]dd, where there is one digit
@@ -423,13 +699,12 @@ FILE *fopen (const char * __restrict , const char * __restrict); past the end of the array. In no case is a partial multibyte
character written.
p The argument shall be a pointer to void. The value of the
- pointer is converted to a sequence of printing characters, in an
- implementation-defined manner.
+ pointer is converted to a sequence of printing characters.
n The argument shall be a pointer to signed integer into which is
written the number of characters written to the output stream so
far by this call to fprintf. No argument is converted, but one is
consumed. If the conversion specification includes any flags, a
- field width, or a precision, the behavior is undefined.
+ field width, or a precision, they will be ignored.
% A % character is written. No argument is converted. The
complete conversion specification shall be %%.
@@ -440,93 +715,758 @@ FILE *fopen (const char * __restrict , const char * __restrict); @param[in] stream An open File specifier to which the output is sent.
@param[in] format A multi-byte character sequence containing characters
to be copied unchanged, and conversion specifiers
+ which convert their associated arguments.
+ @param ... Variable number of parameters as required by format.
+
+ @return The fprintf function returns the number of characters
+ transmitted, or a negative value if an output or encoding
+ error occurred.
+**/
+int fprintf (FILE * __restrict stream, const char * __restrict format, ...);
+
+/** Reads characters from stream, under control of format, storing the converted values
+ in variables pointed to by the variable-length parameter list.
+
+ The format is interpreted as a multibyte character sequence, beginning and ending
+ in its initial shift state. The format is composed of zero or more directives:
+ one or more white-space characters, an ordinary multibyte character
+ (neither % nor a white-space character), or a conversion specification.
+
+ Each conversion specification is introduced by the character %. After
+ the %, the following appear in sequence:
+ - An optional assignment-suppressing character, *.
+ - An optional decimal integer, greater than zero, that specifies the
+ maximum field width (in characters).
+ - An optional length modifier that specifies the size of the receiving object.
+ - A conversion specifier character that specifies the type of conversion
+ to be applied.
+
+ The fscanf function executes each directive of the format in turn. If a directive fails, as
+ detailed below, the function returns. Failures are described as input failures (due to the
+ occurrence of an encoding error or the unavailability of input characters), or matching
+ failures (due to inappropriate input).
+
+ A directive composed of white-space character(s) is executed by reading input up to the
+ first non-white-space character (which remains unread), or until no more characters can
+ be read.
+
+ A directive that is an ordinary multibyte character is executed by reading the next
+ characters of the stream. If any of those characters differ from the ones composing the
+ directive, the directive fails and the differing and subsequent characters remain unread.
+ Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
+ read, the directive fails.
+
+ The length modifiers and their meanings are:
+ - hh Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to signed
+ char or unsigned char.
+ - h Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to short
+ int or unsigned short int.
+ - l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to
+ long int or unsigned long int; that a following a, A, e,
+ E, f, F, g, or G conversion specifier applies to an
+ argument with type pointer to double; or that a following
+ c, s, or [ conversion specifier applies to an argument
+ with type pointer to wchar_t.
+ - ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to
+ long long int or unsigned long long int.
+ - j Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to
+ intmax_t or uintmax_t.
+ - z Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to
+ size_t or the corresponding signed integer type.
+ - t Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to
+ ptrdiff_t or the corresponding unsigned integer type.
+ - L Specifies that a following e, E, f, F, g, or G
+ conversion specifier applies to an argument with type
+ pointer to long double.
+
+ If a length modifier appears with any conversion specifier other than as specified above,
+ it will be ignored.
+
+ The conversion specifiers and their meanings are:
+ - d Matches an optionally signed decimal integer, whose format is
+ the same as expected for the subject sequence of the strtol
+ function with the value 10 for the base argument. The
+ corresponding argument shall be a pointer to signed integer.
+ - i Matches an optionally signed integer, whose format is the same
+ as expected for the subject sequence of the strtol function
+ with the value 0 for the base argument. The corresponding
+ argument shall be a pointer to signed integer.
+ - o Matches an optionally signed octal integer, whose format is the
+ same as expected for the subject sequence of the strtoul
+ function with the value 8 for the base argument. The
+ corresponding argument shall be a pointer to unsigned integer.
+ - u Matches an optionally signed decimal integer, whose format is
+ the same as expected for the subject sequence of the strtoul
+ function with the value 10 for the base argument. The
+ corresponding argument shall be a pointer to unsigned integer.
+ - x Matches an optionally signed hexadecimal integer, whose format
+ is the same as expected for the subject sequence of the strtoul
+ function with the value 16 for the base argument. The
+ corresponding argument shall be a pointer to unsigned integer.
+ - e,f,g Matches an optionally signed floating-point number, infinity,
+ or NaN, whose format is the same as expected for the subject
+ sequence of the strtod function. The corresponding argument
+ shall be a pointer to floating.
+ - c Matches a sequence of characters of exactly the number
+ specified by the field width (1 if no field width is present
+ in the directive). If no l length modifier is present, the
+ corresponding argument shall be a pointer to the initial
+ element of a character array large enough to accept the
+ sequence. No null character is added.<BR><BR>
+ If an l length modifier is present, the input shall be a
+ sequence of multibyte characters that begins in the initial
+ shift state. Each multibyte character in the sequence is
+ converted to a wide character as if by a call to the mbrtowc
+ function, with the conversion state described by an mbstate_t
+ object initialized to zero before the first multibyte character
+ is converted. The corresponding argument shall be a pointer to
+ the initial element of an array of wchar_t large enough to
+ accept the resulting sequence of wide characters. No null wide
+ character is added.
+ - s Matches a sequence of non-white-space characters.
+ If no l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of a character array
+ large enough to accept the sequence and a terminating null
+ character, which will be added automatically. If an l length
+ modifier is present, the input shall be a sequence of multibyte
+ characters that begins in the initial shift state. Each
+ multibyte character is converted to a wide character as if by a
+ call to the mbrtowc function, with the conversion state
+ described by an mbstate_t object initialized to zero before the
+ first multibyte character is converted. The corresponding
+ argument shall be a pointer to the initial element of an array
+ of wchar_t large enough to accept the sequence and the
+ terminating null wide character, which will be added automatically.
+ - [ Matches a nonempty sequence of characters from a set of
+ expected characters (the scanset).<BR><BR>
+ If no l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of a character array
+ large enough to accept the sequence and a terminating null
+ character, which will be added automatically. If an l length
+ modifier is present, the input shall be a sequence of multibyte
+ characters that begins in the initial shift state. Each
+ multibyte character is converted to a wide character as if by a
+ call to the mbrtowc function, with the conversion state
+ described by an mbstate_t object initialized to zero before the
+ first multibyte character is converted. The corresponding
+ argument shall be a pointer to the initial element of an array
+ of wchar_t large enough to accept the sequence and the
+ terminating null wide character, which will be added
+ automatically.<BR><BR>
+ The conversion specifier includes all subsequent characters in
+ the format string, up to and including the matching right
+ bracket (]). The characters between the brackets (the scanlist)
+ compose the scanset, unless the character after the left
+ bracket is a circumflex (^), in which case the scanset contains
+ all characters that do not appear in the scanlist between the
+ circumflex and the right bracket. If the conversion specifier
+ begins with [] or [^], the right bracket character is in the
+ scanlist and the next following right bracket character is the
+ matching right bracket that ends the specification; otherwise
+ the first following right bracket character is the one that
+ ends the specification. If a - character is in the scanlist and
+ is not the first, nor the second where the first character is
+ a ^, nor the last character, it will be treated as a regular character.
+ - p Matches a set of sequences, which are the same as the set of
+ sequences that are produced by the %p conversion of the fprintf
+ function. The corresponding argument must be a pointer to a
+ pointer to void. The input item is converted to a pointer value.
+ If the input item is a value converted earlier during the same
+ program execution, the pointer that results will compare equal
+ to that value; otherwise the behavior of the %p conversion is
+ indeterminate.
+ - n No input is consumed. The corresponding argument shall be a
+ pointer to signed integer into which is to be written the
+ number of characters read from the input stream so far by this
+ call to the fscanf function. Execution of a %n directive does
+ not increment the assignment count returned at the completion
+ of execution of the fscanf function. No argument is converted,
+ but one is consumed. If the conversion specification includes
+ an assignment suppressing character the conversion specification
+ is ignored. If the conversion specification contains a
+ field width, the field width will be ignored.
+ - % Matches a single % character; no conversion or assignment occurs.
+
+ @param[in] stream An open File specifier from which the input is read.
+ @param[in] format A multi-byte character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The fscanf function returns EOF if an input failure occurs before
+ any conversion. Otherwise the number of input items assigned
+ is returned; which can be fewer than provided for, or even zero
+ in the event of an early matching failure.
+**/
+int fscanf (FILE * __restrict stream, const char * __restrict format, ...);
+
+/** Formatted print to stdout.
+
+ The printf function is equivalent to fprintf with stdout used as the output stream.
+
+ @param[in] format A multi-byte character sequence containing characters
+ to be copied unchanged, and conversion specifiers
which convert their associated arguments. Copied and
converted characters are sent to the output stream.
@param ... Variable number of parameters as required by format.
- @return The fprintf function returns the number of characters
+ @return The printf function returns the number of characters
transmitted, or a negative value if an output or encoding
error occurred.
+**/
+int printf (const char * __restrict format, ...);
+/** Formatted input from stdin.
+
+ The scanf function is equivalent to fscanf with stdin used as the input stream.
+
+ @param[in] format A multi-byte character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param[out] ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The scanf function returns EOF if an input failure occurs before
+ any conversion. Otherwise the number of input items assigned
+ is returned; which can be fewer than provided for, or even zero
+ in the event of an early matching failure.
**/
-int fprintf (FILE * __restrict stream, const char * __restrict format, ...);
+int scanf (const char * __restrict format, ...);
+
+/** Formatted output to a buffer.
+
+ The sprintf function is equivalent to fprintf, except that the output is
+ written into array Buff instead of to a stream. A null character is written
+ at the end of the characters written; it is not counted as part of the
+ returned value.
+
+ @param[out] Buff A pointer to the array to receive the formatted output.
+ @param[in] Format A multi-byte character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments. Copied and
+ converted characters are written to the array pointed
+ to by Buff.
+ @param ... Variable number of parameters as required by format.
+
+ @return The sprintf function returns the number of characters written in
+ the array, not counting the terminating null character, or a
+ negative value if an encoding error occurred.
+**/
+int sprintf (char * __restrict Buff, const char * __restrict Format, ...);
+
+/** Formatted input from a string.
+
+ The sscanf function is equivalent to fscanf, except that input is obtained
+ from a string rather than from a stream. Reaching the end of the string
+ is equivalent to encountering end-of-file for the fscanf function.
+
+ @param[in] Buff Pointer to the string from which to obtain input.
+ @param[in] Format A multi-byte character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param[out] ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The scanf function returns EOF if an input failure occurs before
+ any conversion. Otherwise the number of input items assigned
+ is returned; which can be fewer than provided for, or even zero
+ in the event of an early matching failure.
+**/
+int sscanf (const char * __restrict Buff, const char * __restrict Format, ...);
+
+/** Print formatted values from an argument list.
+
+ The vfprintf function is equivalent to fprintf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start macro.
+ The vfprintf function does not invoke the va_end macro.
-int fputc (int, FILE *);
-int fputs (const char * __restrict, FILE * __restrict);
-size_t fread (void * __restrict, size_t, size_t, FILE * __restrict);
-FILE *freopen (const char * __restrict, const char * __restrict, FILE * __restrict);
-int fscanf (FILE * __restrict, const char * __restrict, ...);
-int fseek (FILE *, long, int);
-int fsetpos (FILE *, const fpos_t *);
-long ftell (FILE *);
-size_t fwrite (const void * __restrict, size_t, size_t, FILE * __restrict);
+ @param[in] Stream The output stream to receive the formatted output.
+ @param[in] Format A multi-byte character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vfprintf function returns the number of characters transmitted,
+ or a negative value if an output or encoding error occurred.
+**/
+int vfprintf(FILE * __restrict Stream, const char * __restrict Format, va_list Args);
+
+/** Formatted print, to stdout, from an argument list.
+
+ The vprintf function is equivalent to printf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro (and possibly subsequent va_arg calls). The vprintf function does
+ not invoke the va_end macro.
+
+ @param[in] Format A multi-byte character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vprintf function returns the number of characters transmitted,
+ or a negative value if an output or encoding error occurred.
+**/
+int vprintf (const char * __restrict Format, va_list Args);
+
+/** Formatted print, to a buffer, from an argument list.
+
+ The vsprintf function is equivalent to sprintf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro. The vsprintf function does not invoke the va_end macro.
+
+ @param[out] Buff A pointer to the array to receive the formatted output.
+ @param[in] Format A multi-byte character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments. Copied and
+ converted characters are written to the array pointed
+ to by Buff.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vsprintf function returns the number of characters written in
+ the array, not counting the terminating null character, or a
+ negative value if an encoding error occurred.
+**/
+int vsprintf(char * __restrict Buff, const char * __restrict Format, va_list Args);
+
+/* ################ Character Input/Output Functions. */
+
+/** Get a character from an input Stream.
+
+ If the end-of-file indicator for the input stream pointed to by Stream is
+ not set, and a next character is present, the fgetc function obtains that
+ character as an unsigned char converted to an int and advances the
+ associated file position indicator for the stream.
+
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return If the end-of-file indicator for the stream is set, or if the
+ stream is at end-of-file, the end-of-file indicator for the
+ stream is set and the fgetc function returns EOF. Otherwise,
+ the fgetc function returns the next character from the input
+ stream pointed to by Stream. If a read error occurs, the
+ error indicator for the stream is set and the fgetc function
+ returns EOF.
+**/
+int fgetc (FILE *Stream);
+
+/** Read a string from an input stream into a buffer.
+
+ The fgets function reads at most one less than the number of characters
+ specified by Limit from the stream pointed to by Stream into the array
+ pointed to by Buff. No additional characters are read after a
+ new-line character (which is retained) or after end-of-file. A null
+ character is written immediately after the last character read into the array.
+
+ @param[out] Buff A pointer to the array to receive the input string.
+ @param[in] Limit The maximum number of characters to put into Buff,
+ including the terminating null character.
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return The fgets function returns Buff if successful. If end-of-file is
+ encountered and no characters have been read into the array, the
+ contents of the array remain unchanged and a null pointer is
+ returned. If a read error occurs during the operation, the array
+ contents are indeterminate and a null pointer is returned.
+**/
+char *fgets (char * __restrict Buff, int Limit, FILE * __restrict Stream);
+
+/** Write a character to an output stream.
+
+ The fputc function writes the character specified by C (converted to an
+ unsigned char) to the output stream pointed to by Stream, at the position
+ indicated by the associated file position indicator for the stream
+ (if defined), and advances the indicator appropriately. If the file cannot
+ support positioning requests, or if the stream was opened with append mode,
+ the character is appended to the output stream.
+
+ @param[in] C The character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The fputc function returns the character written. If a write
+ error occurs, the error indicator for the stream is set and
+ fputc returns EOF.
+**/
+int fputc (int C, FILE *Stream);
+
+/** Write a string to an output stream.
+
+ The fputs function writes String to the stream pointed to by Stream. The
+ terminating null character is not written.
+
+ @param[in] String The character string to be written to Stream.
+ @param[in] Stream The output stream that String is to be written to.
+
+ @return The fputs function returns EOF if a write error occurs; otherwise
+ it returns a non-negative value.
+**/
+int fputs (const char * __restrict String, FILE * __restrict Stream);
+
+/** Get a character from an input stream.
+
+ The getc function is equivalent to fgetc, except that if it is implemented
+ as a macro, it may evaluate stream more than once, so the argument should
+ never be an expression with side effects.
+
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return If the end-of-file indicator for the stream is set, or if the
+ stream is at end-of-file, the end-of-file indicator for the
+ stream is set and getc returns EOF. Otherwise, getc returns
+ the next character from the input stream pointed to by Stream.
+ If a read error occurs, the error indicator for the stream is set
+ and getc returns EOF.
+**/
int getc (FILE *);
+
+/** Get a character from stdin.
+
+ The getchar function is equivalent to getc with the argument stdin.
+
+ @return If the end-of-file indicator for stdin is set, or if stdin
+ is at end-of-file, the end-of-file indicator is set and getchar
+ returns EOF. Otherwise, getchar returns the next character from
+ stdin. If a read error occurs, the error indicator for stdin is
+ set and getchar returns EOF.
+**/
int getchar (void);
-void perror (const char *);
-int printf (const char * __restrict, ...);
-int putc (int, FILE *);
-int putchar (int);
-int puts (const char *);
-int remove (const char *);
-void rewind (FILE *);
-int scanf (const char * __restrict, ...);
-void setbuf (FILE * __restrict, char * __restrict);
-int setvbuf (FILE * __restrict, char * __restrict, int, size_t);
-int sscanf (const char * __restrict, const char * __restrict, ...);
-FILE *tmpfile (void);
-int ungetc (int, FILE *);
-int vfprintf(FILE * __restrict, const char * __restrict, va_list);
-int vprintf (const char * __restrict, va_list);
-
-#ifndef __AUDIT__
-char *gets (char *);
-int sprintf (char * __restrict, const char * __restrict, ...);
-char *tmpnam (char *);
-int vsprintf(char * __restrict, const char * __restrict, va_list);
-#endif
-#if defined(_POSIX_C_SOURCE) || defined(_XOPEN_SOURCE)
-int rename (const char *, const char *) __RENAME(__posix_rename);
-#else
-int rename (const char *, const char *);
-#endif
+/** Read a string from stdin into a buffer.
+
+ The gets function reads characters from the input stream pointed to by
+ stdin, into the array pointed to by Buff, until end-of-file is encountered
+ or a new-line character is read. Any new-line character is discarded, and
+ a null character is written immediately after the last character read into
+ the array.
+
+ @param[out] Buff A pointer to the array to receive the input string.
+
+ @return The gets function returns Buff if successful. If end-of-file is
+ encountered and no characters have been read into the array, the
+ contents of the array remain unchanged and a null pointer is
+ returned. If a read error occurs during the operation, the array
+ contents are indeterminate and a null pointer is returned.
+**/
+char *gets (char *Buff);
+
+/** Write a character to an output stream.
+
+ The putc function is equivalent to fputc, except that if it is implemented
+ as a macro, it may evaluate Stream more than once, so that argument should
+ never be an expression with side effects.
+
+ @param[in] C The character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The putc function returns the character written. If a write
+ error occurs, the error indicator for the stream is set and
+ putc returns EOF.
+**/
+int putc (int C, FILE *Stream);
+
+/** Write a character to stdout.
+
+ The putchar function is equivalent to putc with stdout as the Stream argument.
+
+ @param[in] C The character to be written to stdout.
+
+ @return The putchar function returns the character written. If a write
+ error occurs, the error indicator for stdout is set and putchar
+ returns EOF.
+**/
+int putchar (int C);
+
+/** Write String to stdout.
+
+ The puts function writes the string pointed to by String to the stream
+ pointed to by stdout, and appends a new-line character to the output. The
+ terminating null character is not written.
+
+ @param[in] String A pointer to the character string to write to stdout.
+
+ @return The puts function returns EOF if a write error occurs; otherwise
+ it returns a non-negative value.
+**/
+int puts (const char *String);
+
+/** Return a character to the input Stream as if it had not been read.
+
+ The ungetc function pushes the character specified by C (converted to an
+ unsigned char) back onto the input stream pointed to by Stream. Pushed-back
+ characters will be returned by subsequent reads on that stream in the
+ reverse order of their being pushed. A successful intervening call
+ (with the stream pointed to by Stream) to a file positioning function
+ (fseek, fsetpos, or rewind) discards any pushed-back characters for the
+ stream. The external storage corresponding to the stream is unchanged.
+
+ One character of pushback is guaranteed. If the ungetc function is called
+ too many times on the same stream without an intervening read or file
+ positioning operation on that stream, the operation will fail.
+
+ If the value of C equals that of the macro EOF, the operation fails and the
+ input stream is unchanged.
+
+ A successful call to the ungetc function clears the end-of-file indicator
+ for the stream. The value of the file position indicator for the stream
+ after reading or discarding all pushed-back characters is the same as it
+ was before the characters were pushed back. For a binary stream, its
+ file position indicator is decremented by each successful call to the
+ ungetc function; if its value was zero before a call, it will remain zero
+ after the call.
+
+ @param[in] C The character to push back onto the Stream.
+ @param[in] Stream The output stream that C is to be pushed back onto.
+
+ @return The ungetc function returns the character pushed back,
+ or EOF if the operation fails.
+**/
+int ungetc (int C, FILE *Stream);
+
+/* ################ Direct Input/Output Functions. */
+
+/** Read Num elements of size Size from a Stream into a Buffer.
+
+ The fread function reads, into the array pointed to by Buffer, up to Num
+ elements, whose size is specified by Size, from the stream pointed to by
+ Stream. For each object, Size calls are made to the fgetc function and the
+ results stored, in the order read, in an array of unsigned char exactly
+ overlaying the Buffer object. The file position indicator for the stream
+ (if defined) is advanced by the number of characters successfully read. If
+ an error occurs, the resulting value of the file position indicator for the
+ stream is indeterminate.
+
+ @param[out] Buffer Pointer to an object to receive the read data.
+ @param[in] Size Size of each element to be read.
+ @param[in] Num Number of elements to read.
+ @param[in] Stream Input stream to read the data from.
+
+ @return The fread function returns the number of elements successfully
+ read, which may be less than Num if a read error or end-of-file
+ is encountered. If Size or Num is zero, fread returns zero and
+ the contents of the array and the state of the stream remain
+ unchanged.
+**/
+size_t fread (void * __restrict Buffer,
+ size_t Size,
+ size_t Num,
+ FILE * __restrict Stream
+ );
+
+/** Write Num elements of size Size from Buffer to Stream.
+
+ The fwrite function writes, from the array pointed to by Buffer, up to Num
+ elements whose size is specified by Size, to the stream pointed to by
+ Stream. For each object, Size calls are made to the fputc function, taking
+ the values (in order) from an array of unsigned char exactly overlaying the
+ Buffer object. The file position indicator for the stream (if defined) is
+ advanced by the number of characters successfully written. If an error
+ occurs, the resulting value of the file position indicator for the stream is
+ indeterminate.
+
+ @param[out] Buffer Pointer to an object containing the data to be written.
+ @param[in] Size Size of each element to be written.
+ @param[in] Num Number of elements to write.
+ @param[in] Stream Output stream to write the data to.
+
+ @return The fwrite function returns the number of elements successfully
+ written, which will be less than Num only if a write error is
+ encountered. If Size or Num is zero, fwrite returns zero and
+ the state of the stream remains unchanged.
+**/
+size_t fwrite (const void * __restrict Buffer,
+ size_t Size,
+ size_t Num,
+ FILE * __restrict Stream
+ );
+
+/* ################ File Positioning Functions. */
+
+/** Get a stream's position and parse state.
+
+ The fgetpos function stores the current values of the parse state (if any)
+ and file position indicator for the stream pointed to by Stream in the
+ object pointed to by Pos. The values stored contain unspecified
+ information usable by the fsetpos function for repositioning the stream
+ to its position at the time of the call to the fgetpos function.
+
+ @param[in] Stream Stream to get current position of.
+ @param[out] Pos Object to receive the stream's state and position information.
+
+ @return If successful, the fgetpos function returns zero; if either
+ parameter is NULL, the fgetpos function returns nonzero and
+ stores EINVAL in errno.
+**/
+int fgetpos (FILE * __restrict Stream, fpos_t * __restrict Pos);
+
+/** Set the file position for a stream.
+
+ The fseek function sets the file position indicator for the stream pointed
+ to by Stream. If a read or write error occurs, the error indicator for the
+ stream is set and fseek fails.
+
+ For a binary stream, the new position, measured in characters from the
+ beginning of the file, is obtained by adding Offset to the position
+ specified by Whence. The specified position is the beginning of the file if
+ Whence is SEEK_SET, the current value of the file position indicator if
+ SEEK_CUR, or end-of-file if SEEK_END.
+
+ For a text stream, Offset must either be zero or a value returned by an
+ earlier successful call to the ftell function, on a stream associated with
+ the same file, and Whence must be SEEK_SET.
+
+ After determining the new position, a successful call to the fseek function
+ undoes any effects of the ungetc function on the stream, clears the
+ end-of-file indicator for the stream, and then establishes the new position.
+ After a successful fseek call, the next operation on an update stream may
+ be either input or output.
+
+ @param[in] Stream The I/O stream to set the position of.
+ @param[in] Offset The position, interpreted depending upon the value of
+ Whence, that the stream is to be positioned to.
+ @param[in] Whence A value indicating how Offset is to be interpreted:
+ - SEEK_SET indicates Offset is an absolute position.
+ - SEEK_END indicates Offset is relative to the end of the file.
+ - SEEK_CUR indicates Offset is relative to the current position.
+
+@return The fseek function returns nonzero only for a request that cannot be satisfied.
+**/
+int fseek (FILE *Stream, long Offset, int Whence);
+
+/** Set a stream's position and parse state.
+
+ The fsetpos function sets the mbstate_t object (if any) and file position
+ indicator for the stream pointed to by Stream according to the value of the
+ object pointed to by Pos, which is a value that was obtained from an
+ earlier successful call to the fgetpos function on a stream associated with
+ the same file. If a read or write error occurs, the error indicator for the
+ stream is set and fsetpos fails.
+
+ A successful call to the fsetpos function undoes any effects of the ungetc
+ function on the stream, clears the end-of-file indicator for the stream,
+ and then establishes the new parse state and position. After a successful
+ fsetpos call, the next operation on an update stream may be either input or output.
+
+ @param[in] Stream Stream to set current position of.
+ @param[in] Pos Object containing the state and position information.
+
+ @return If successful, the fsetpos function returns zero; on failure, the
+ fsetpos function returns nonzero and stores EINVAL, or ESPIPE,
+ in errno; depending upon whether the error was because of an invalid
+ parameter, or because Stream is not seekable.
+**/
+int fsetpos (FILE *Stream, const fpos_t *Pos);
+
+/** Get Stream's current position.
+
+ The ftell function obtains the current value of the file position indicator
+ for the stream pointed to by Stream. For a binary stream, the value is the
+ number of characters from the beginning of the file. For a text stream, its
+ file position indicator contains unspecified information, usable by the
+ fseek function for returning the file position indicator for the stream to
+ its position at the time of the ftell call; the difference between two such
+ return values is not necessarily a meaningful measure of the number of
+ characters written or read.
+
+ @param[in] Stream Pointer to the FILE object to get the current position of.
+
+ @return If successful, the ftell function returns the current value of
+ the file position indicator for the stream. On failure, the
+ ftell function returns -1L and stores ESPIPE in errno indicating
+ that the stream is not seekable.
+**/
+long ftell (FILE *Stream);
+
+/** Restore a Stream's file position to the beginning of the file.
+
+ The rewind function sets the file position indicator for the stream pointed
+ to by Stream to the beginning of the file and clears the stream's error indicator.
+
+ @param[in] Stream Pointer to the stream to be positioned to its beginning.
+**/
+void rewind (FILE *Stream);
+
+/* ################ Error-handling Functions. */
+
+/** Clear a Stream's error and end-of-file indicators.
+
+ @param[in] Stream Pointer to the stream to be cleared of errors.
+**/
+void clearerr(FILE *Stream);
+
+/** Test the end-of-file indicator for Stream.
+
+ @param[in] Stream Pointer to the FILE object to be tested for EOF.
+
+ @return The feof function returns non-zero if, and only if, the end-of-file
+ indicator is set for Stream.
+**/
+int feof (FILE *Stream);
+
+/** Test the error indicator for Stream.
+
+ @param[in] Stream Pointer to the stream to be tested for error.
+
+ @return The ferror function returns non-zero if, and only if, the error
+ indicator is set for Stream.
+**/
+int ferror (FILE *Stream);
+
+/** Print an error message to stderr based upon the value of errno and String.
+
+ The perror function maps the error number in the integer expression errno
+ to an error message. It writes a sequence of characters to the standard
+ error stream thus: first (if String is not a null pointer and the character
+ pointed to by String is not the null character), the string pointed to by
+ String followed by a colon (:) and a space; then an appropriate error
+ message string followed by a new-line character. The contents of the error
+ message strings are the same as those returned by the strerror function
+ with argument errno.
+
+ @param[in] String A text string to prefix the output error message with.
+
+ @sa strerror in <string.h>
+**/
+void perror (const char *String);
+
__END_DECLS
/*
* IEEE Std 1003.1-90
*/
-#if defined(_POSIX_C_SOURCE) || defined(_XOPEN_SOURCE) || \
- defined(_NETBSD_SOURCE)
- #define L_ctermid 1024 /* size for ctermid(); PATH_MAX */
- #define L_cuserid 9 /* size for cuserid(); UT_NAMESIZE + 1 */
-
- __BEGIN_DECLS
- char *ctermid(char *);
- #ifndef __CUSERID_DECLARED
- #define __CUSERID_DECLARED
- /* also declared in unistd.h */
- char *cuserid(char *);
- #endif /* __CUSERID_DECLARED */
- FILE *fdopen(int, const char *);
- int fileno(FILE *);
- __END_DECLS
-#endif /* not ANSI */
+__BEGIN_DECLS
+FILE *fdopen(int, const char *);
+__END_DECLS
/*
* IEEE Std 1003.1c-95, also adopted by X/Open CAE Spec Issue 5 Version 2
*/
-#if (_POSIX_C_SOURCE - 0) >= 199506L || (_XOPEN_SOURCE - 0) >= 500 || \
- defined(_REENTRANT) || defined(_NETBSD_SOURCE)
- __BEGIN_DECLS
- void flockfile (FILE *);
- int ftrylockfile (FILE *);
- void funlockfile (FILE *);
- int getc_unlocked (FILE *);
- int getchar_unlocked(void);
- int putc_unlocked (int, FILE *);
- int putchar_unlocked(int);
- __END_DECLS
-#endif /* _POSIX_C_SOURCE >= 1995056 || _XOPEN_SOURCE >= 500 || ... */
+__BEGIN_DECLS
+void flockfile (FILE *);
+int ftrylockfile (FILE *);
+void funlockfile (FILE *);
+int getc_unlocked (FILE *);
+int getchar_unlocked(void);
+int putc_unlocked (int, FILE *);
+int putchar_unlocked(int);
+__END_DECLS
/*
* Functions defined in POSIX 1003.2 and XPG2 or later.
@@ -550,8 +1490,8 @@ __END_DECLS * Functions defined in XPG4.2.
*/
__BEGIN_DECLS
- int getw(FILE *);
- int putw(int, FILE *);
+ //int getw(FILE *);
+ //int putw(int, FILE *);
char *mkdtemp(char *);
int mkstemp(char *);
char *mktemp(char *);
@@ -568,18 +1508,18 @@ __END_DECLS #endif /* off_t */
__BEGIN_DECLS
-int fseeko(FILE *, off_t, int);
-off_t ftello(FILE *);
+int fseeko(FILE *, off_t, int);
+off_t ftello(FILE *);
__END_DECLS
/*
* Routines that are purely local.
*/
-#define FPARSELN_UNESCESC 0x01
+#define FPARSELN_UNESCESC 0x01
#define FPARSELN_UNESCCONT 0x02
#define FPARSELN_UNESCCOMM 0x04
#define FPARSELN_UNESCREST 0x08
-#define FPARSELN_UNESCALL 0x0f
+#define FPARSELN_UNESCALL 0x0f
__BEGIN_DECLS
//int asprintf(char ** __restrict, const char * __restrict, ...)
@@ -594,14 +1534,14 @@ __BEGIN_DECLS __attribute__((__format__(__printf__, 2, 0)));
int vscanf(const char * __restrict, va_list)
__attribute__((__format__(__scanf__, 1, 0)));
- int vfscanf(FILE * __restrict, const char * __restrict,
- va_list)
- __attribute__((__format__(__scanf__, 2, 0)));
+ //int vfscanf(FILE * __restrict, const char * __restrict,
+ // va_list)
+ // __attribute__((__format__(__scanf__, 2, 0)));
int vsscanf(const char * __restrict, const char * __restrict,
va_list)
__attribute__((__format__(__scanf__, 2, 0)));
- const char *fmtcheck(const char *, const char *)
- __attribute__((__format_arg__(2)));
+ //const char *fmtcheck(const char *, const char *)
+ // __attribute__((__format_arg__(2)));
__END_DECLS
/*
diff --git a/StdLib/Include/stdlib.h b/StdLib/Include/stdlib.h index d51d4bf..1166847 100644 --- a/StdLib/Include/stdlib.h +++ b/StdLib/Include/stdlib.h @@ -2,21 +2,120 @@ The header <stdlib.h> declares five types and several functions of general
utility, and defines several macros.
+ The files stddef.h and stdlib.h are "catch all" headers for definitions and declarations
+ that don't fit well in the other headers. There are two separate header files because
+ the contents of <stddef.h> are valid in both freestanding and hosted environment, while the
+ header <stdlib.h> contains elements that are only valid in a hosted environment.
+
+ The following macros are defined in this file:<BR>
+ @verbatim
+ EXIT_FAILURE An expression indicating application failure, used as an argument to exit().
+ EXIT_SUCCESS An expression indicating application success, used as an argument to exit().
+ RAND_MAX The maximum value returned by the rand function.
+ MB_CUR_MAX Maximum number of bytes in a multibyte character for the current locale.
+ ATEXIT_MAX Maximum number of routines that may be registered by the atexit function.
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ wchar_t The type of a wide character.
+ div_t Type of the value returned by the div function.
+ ldiv_t Type of the value returned by the ldiv function.
+ lldiv_t Type of the value returned by the lldiv function.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+ @verbatim
+ ################ Communication with the environment
+ void abort (void) __noreturn;
+ int atexit (void (*)(void));
+ void exit (int status) __noreturn;
+ void _Exit (int status) __noreturn;
+ char *getenv (const char *name);
+ int setenv (register const char * name,
+ register const char * value, int rewrite);
+ int system (const char *string);
+
+ ################ Integer arithmetic functions
+ int abs (int j);
+ long labs (long j);
+ long long llabs (long long j);
+ div_t div (int numer, int denom);
+ ldiv_t ldiv (long numer, long denom);
+ lldiv_t lldiv (long long numer, long long denom);
+
+ ################ Pseudo-random sequence generation functions
+ int rand (void);
+ void srand (unsigned seed);
+
+ ################ Memory management functions
+ void *calloc (size_t Num, size_t Size);
+ void free (void *);
+ void *malloc (size_t);
+ void *realloc (void *Ptr, size_t NewSize);
+
+ ################ Searching and Sorting utilities
+ void *bsearch (const void *key, const void *base0,
+ size_t nmemb, size_t size,
+ int (*compar)(const void *, const void *));
+ void qsort (void *base, size_t nmemb, size_t size,
+ int (*compar)(const void *, const void *));
+
+ ################ Multibyte/wide character conversion functions
+ int mblen (const char *, size_t);
+ int mbtowc (wchar_t * __restrict, const char * __restrict, size_t);
+ int wctomb (char *, wchar_t);
+
+ ################ Multibyte/wide string conversion functions
+ size_t mbstowcs (wchar_t * __restrict dest,
+ const char * __restrict src, size_t limit);
+ size_t wcstombs (char * __restrict dest,
+ const wchar_t * __restrict src, size_t limit);
+
+ ################ Miscelaneous functions for *nix compatibility
+ char *realpath (char *file_name, char *resolved_name);
+ const char *getprogname (void);
+ void setprogname (const char *progname);
+
+ ############ Integer Numeric conversion functions
+ int atoi (const char *nptr);
+ long atol (const char *nptr);
+ long long atoll (const char *nptr);
+ long strtol (const char * __restrict nptr,
+ char ** __restrict endptr, int base);
+ unsigned long strtoul (const char * __restrict nptr,
+ char ** __restrict endptr, int base);
+ long long strtoll (const char * __restrict nptr,
+ char ** __restrict endptr, int base);
+ unsigned long long strtoull (const char * __restrict nptr,
+ char ** __restrict endptr, int base);
+
+ ######### Floating-point Numeric conversion functions
+ double atof (const char *);
+ double strtod (const char * __restrict nptr,
+ char ** __restrict endptr);
+ float strtof (const char * __restrict nptr,
+ char ** __restrict endptr);
+ long double strtold (const char * __restrict nptr,
+ char ** __restrict endptr);
+ @endverbatim
+
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
+ http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
**/
#ifndef _STDLIB_H
#define _STDLIB_H
#include <sys/EfiCdefs.h>
#ifdef _EFI_SIZE_T_
+ /** Unsigned integer type of the result of the sizeof operator. **/
typedef _EFI_SIZE_T_ size_t;
#undef _EFI_SIZE_T_
#undef _BSD_SIZE_T_
@@ -24,6 +123,7 @@ #ifndef __cplusplus
#ifdef _EFI_WCHAR_T
+ /** Type of a wide (Unicode) character. **/
typedef _EFI_WCHAR_T wchar_t;
#undef _EFI_WCHAR_T
#undef _BSD_WCHAR_T_
@@ -32,8 +132,8 @@ /// A structure type that is the type of the value returned by the div function.
typedef struct {
- int quot; /* quotient */
- int rem; /* remainder */
+ int quot; /**< quotient */
+ int rem; /**< remainder */
} div_t;
/// A structure type that is the type of the value returned by the ldiv function.
@@ -48,17 +148,17 @@ typedef struct { long long rem;
} lldiv_t;
-/** Expand to integer constant expressions that can be used as the argument to
+/** @{
+ Expand to integer constant expressions that can be used as the argument to
the exit function to return unsuccessful or successful termination status,
respectively, to the host environment.
**/
#define EXIT_FAILURE 1
#define EXIT_SUCCESS 0
+/*@}*/
/** Expands to an integer constant expression that is the maximum value
returned by the rand function.
-
- The value of the RAND_MAX macro shall be at least 32767.
**/
#define RAND_MAX 0x7fffffff
@@ -98,10 +198,13 @@ void abort(void) __noreturn; The implementation supports the registration of up to 32 functions.
+ @param[in] Handler Pointer to the function to register as one of the
+ routines to call at application exit time.
+
@return The atexit function returns zero if the registration succeeds,
nonzero if it fails.
**/
-int atexit(void (*)(void));
+int atexit(void (*Handler)(void));
/** The exit function causes normal program termination to occur. If more than
one call to the exit function is executed by a program,
@@ -118,14 +221,13 @@ int atexit(void (*)(void)); streams are closed, and all files created by the tmpfile function
are removed.
- Finally, control is returned to the host environment. If the value of
- status is zero, or EXIT_SUCCESS, status is returned unchanged. If the value
- of status is EXIT_FAILURE, EAPPLICATION is returned.
- Otherwise, status is returned unchanged.
+ Finally, control is returned to the host environment.
+
+ @param[in] status A value to be returned when the application exits.
- While this function does not return, it can NOT be marked as "__noreturn"
- without causing a warning to be emitted because the compilers can not
- determine that the function truly does not return.
+ @return If the value of status is zero, or EXIT_SUCCESS, status is
+ returned unchanged. If the value of status is EXIT_FAILURE,
+ RETURN_ABORTED is returned. Otherwise, status is returned unchanged.
**/
void exit(int status) __noreturn;
@@ -137,12 +239,14 @@ void exit(int status) __noreturn; buffered data are not flushed, open streams are not closed, and temporary
files are not removed by abort.
- While this function does not return, it can NOT be marked as "__noreturn"
- without causing a warning to be emitted because the compilers can not
- determine that the function truly does not return.
-
The status returned to the host environment is determined in the same way
as for the exit function.
+
+ @param[in] status A value to be returned when the application exits.
+
+ @return If the value of status is zero, or EXIT_SUCCESS, status is
+ returned unchanged. If the value of status is EXIT_FAILURE,
+ RETURN_ABORTED is returned. Otherwise, status is returned unchanged.
**/
void _Exit(int status) __noreturn;
@@ -151,6 +255,8 @@ void _Exit(int status) __noreturn; set of environment names and the method for altering the environment list
are determined by the underlying UEFI Shell implementation.
+ @param[in] name Pointer to a string naming the environment variable to retrieve.
+
@return The getenv function returns a pointer to a string associated with
the matched list member. The string pointed to shall not be
modified by the program, but may be overwritten by a subsequent
@@ -159,16 +265,14 @@ void _Exit(int status) __noreturn; **/
char *getenv(const char *name);
-/**
- Add or update a variable in the environment list
-
- @param name Address of a zero terminated name string
- @param value Address of a zero terminated value string
- @param rewrite TRUE allows overwriting existing values
+/** Add or update a variable in the environment list.
- @retval Returns 0 upon success
- @retval Returns -1 upon failure, sets errno with more information
+ @param[in] name Address of a zero terminated name string.
+ @param[in] value Address of a zero terminated value string.
+ @param[in] rewrite TRUE allows overwriting existing values.
+ @retval 0 Returns 0 upon success.
+ @retval -1 Returns -1 upon failure, sets errno with more information.
**/
int
setenv (
@@ -184,6 +288,8 @@ setenv ( document; this might then cause the program calling system to behave in a
non-conforming manner or to terminate.
+ @param[in] string Pointer to the command string to be executed.
+
@return If the argument is a null pointer, the system function returns
nonzero only if a command processor is available. If the argument
is not a null pointer, and the system function does return, it
@@ -196,17 +302,23 @@ int system(const char *string); /** Computes the absolute value of an integer j.
+ @param[in] j The value to find the absolute value of.
+
@return The absolute value of j.
**/
int abs(int j);
-/** Computes the absolute value of an integer j.
+/** Computes the absolute value of a long integer j.
+
+ @param[in] j The value to find the absolute value of.
@return The absolute value of j.
**/
long labs(long j);
-/** Computes the absolute value of an integer j.
+/** Computes the absolute value of a long long integer j.
+
+ @param[in] j The value to find the absolute value of.
@return The absolute value of j.
**/
@@ -215,6 +327,9 @@ long long /** Computes numer / denom and numer % denom in a single operation.
+ @param[in] numer The numerator for the division.
+ @param[in] denom The denominator for the division.
+
@return Returns a structure of type div_t, comprising both the
quotient and the remainder.
**/
@@ -222,6 +337,9 @@ div_t div(int numer, int denom); /** Computes numer / denom and numer % denom in a single operation.
+ @param[in] numer The numerator for the division.
+ @param[in] denom The denominator for the division.
+
@return Returns a structure of type ldiv_t, comprising both the
quotient and the remainder.
**/
@@ -229,6 +347,9 @@ ldiv_t ldiv(long numer, long denom); /** Computes numer / denom and numer % denom in a single operation.
+ @param[in] numer The numerator for the division.
+ @param[in] denom The denominator for the division.
+
@return Returns a structure of type lldiv_t, comprising both the
quotient and the remainder.
**/
@@ -241,7 +362,9 @@ lldiv_t lldiv(long long numer, long long denom); equivalent to:
- atoi: (int)strtol(nptr, (char **)NULL, 10)
- @return The atoi function returns the converted value.
+ @param[in] nptr Pointer to the string to be converted.
+
+ @return The atoi function returns the converted value.
**/
int atoi(const char *nptr);
@@ -250,7 +373,9 @@ int atoi(const char *nptr); equivalent to:
- atol: strtol(nptr, (char **)NULL, 10)
- @return The atol function returns the converted value.
+ @param[in] nptr Pointer to the string to be converted.
+
+ @return The atol function returns the converted value.
**/
long atol(const char *nptr);
@@ -259,7 +384,9 @@ long atol(const char *nptr); is equivalent to:
- atoll: strtoll(nptr, (char **)NULL, 10)
- @return The atoll function returns the converted value.
+ @param[in] nptr Pointer to the string to be converted.
+
+ @return The atoll function returns the converted value.
**/
long long
atoll(const char *nptr);
@@ -276,7 +403,7 @@ long long integer, and return the result.
If the value of base is zero, the expected form of the subject sequence is
- that of an integer constant as described in 6.4.4.1, optionally preceded
+ that of an integer constant, optionally preceded
by a plus or minus sign, but not including an integer suffix. If the value
of base is between 2 and 36 (inclusive), the expected form of the subject
sequence is a sequence of letters and digits representing an integer with
@@ -310,13 +437,17 @@ long long conversion is performed; the value of nptr is stored in the object pointed
to by endptr, provided that endptr is not a null pointer.
- @return The strtol, strtoll, strtoul, and strtoull functions return the
- converted value, if any. If no conversion could be performed, zero
- is returned. If the correct value is outside the range of
- representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
- ULONG_MAX, or ULLONG_MAX is returned (according to the return type
- and sign of the value, if any), and the value of the macro ERANGE
- is stored in errno.
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
+ @param[in] base The base, 0 to 36, of the number represented by the input string.
+
+ @return The strtol, strtoll, strtoul, and strtoull functions return the
+ converted value, if any. If no conversion could be performed, zero
+ is returned. If the correct value is outside the range of
+ representable values, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX,
+ ULONG_MAX, or ULLONG_MAX is returned (according to the return type
+ and sign of the value, if any), and the value of the macro ERANGE
+ is stored in errno.
**/
long strtol(const char * __restrict nptr, char ** __restrict endptr, int base);
@@ -325,10 +456,14 @@ long strtol(const char * __restrict nptr, char ** __restrict endptr, int base See the description for strtol for more information.
- @return The strtoul function returns the converted value, if any. If no
- conversion could be performed, zero is returned. If the correct
- value is outside the range of representable values, ULONG_MAX is
- returned and the value of the macro ERANGE is stored in errno.
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
+ @param[in] base The base, 0 to 36, of the number represented by the input string.
+
+ @return The strtoul function returns the converted value, if any. If no
+ conversion could be performed, zero is returned. If the correct
+ value is outside the range of representable values, ULONG_MAX is
+ returned and the value of the macro ERANGE is stored in errno.
**/
unsigned long
strtoul(const char * __restrict nptr, char ** __restrict endptr, int base);
@@ -338,11 +473,15 @@ unsigned long See the description for strtol for more information.
- @return The strtoll function returns the converted value, if any. If no
- conversion could be performed, zero is returned. If the correct
- value is outside the range of representable values, LLONG_MIN or
- LLONG_MAX is returned (according to the sign of the value, if any),
- and the value of the macro ERANGE is stored in errno.
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
+ @param[in] base The base, 0 to 36, of the number represented by the input string.
+
+ @return The strtoll function returns the converted value, if any. If no
+ conversion could be performed, zero is returned. If the correct
+ value is outside the range of representable values, LLONG_MIN or
+ LLONG_MAX is returned (according to the sign of the value, if any),
+ and the value of the macro ERANGE is stored in errno.
**/
long long
strtoll(const char * __restrict nptr, char ** __restrict endptr, int base);
@@ -352,40 +491,83 @@ long long See the description for strtol for more information.
- @return The strtoull function returns the converted value, if any. If no
- conversion could be performed, zero is returned. If the correct
- value is outside the range of representable values, ULLONG_MAX is
- returned and the value of the macro ERANGE is stored in errno.
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
+ @param[in] base The base, 0 to 36, of the number represented by the input string.
+
+ @return The strtoull function returns the converted value, if any. If no
+ conversion could be performed, zero is returned. If the correct
+ value is outside the range of representable values, ULLONG_MAX is
+ returned and the value of the macro ERANGE is stored in errno.
**/
unsigned long long
strtoull(const char * __restrict nptr, char ** __restrict endptr, int base);
/* ######### Floating-point Numeric conversion functions ################ */
-/**
+/** Convert the initial part of a string to double representation.
+
+ @param[in] nptr Pointer to the string to be converted.
- @return
+ @return The floating-point value representing the string nptr.
**/
-double atof(const char *);
+double atof(const char *nptr);
+
+/** @{
+ The strtod, strtof, and strtold functions convert the initial portion of
+ the string pointed to by nptr to double, float, and long double
+ representation, respectively. First, they decompose the input string into
+ three parts: an initial, possibly empty, sequence of white-space characters
+ (as specified by the isspace function), a subject sequence resembling a
+ floating-point constant or representing an infinity or NaN; and a final
+ string of one or more unrecognized characters, including the terminating
+ null character of the input string. Then, they attempt to convert the
+ subject sequence to a floating-point number, and return the result.
+*/
+
+/** Convert a string to a double and point to the character after the last converted.
-/**
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
- @return
+ @return A floating-point value representing the string nptr.
+ A pointer to the final string is stored in the object pointed to
+ by endptr, provided that endptr is not a null pointer.
+ If the subject sequence is empty or does not have the expected
+ form, no conversion is performed; the value of nptr is stored in
+ the object pointed to by endptr, provided that endptr is not a null pointer.
**/
double strtod(const char * __restrict nptr, char ** __restrict endptr);
-/**
+/** Convert a string to a float and point to the character after the last converted.
- @return
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
+
+ @return A floating-point value representing the string nptr.
+ A pointer to the final string is stored in the object pointed to
+ by endptr, provided that endptr is not a null pointer.
+ If the subject sequence is empty or does not have the expected
+ form, no conversion is performed; the value of nptr is stored in
+ the object pointed to by endptr, provided that endptr is not a null pointer.
**/
float strtof(const char * __restrict nptr, char ** __restrict endptr);
-/**
+/** Convert a string to a long double and point to the character after the last converted.
+
+ @param[in] nptr Pointer to the string to be converted.
+ @param[out] endptr If not NULL, points to an object to receive a pointer to the final string.
- @return
+ @return A floating-point value representing the string nptr.
+ A pointer to the final string is stored in the object pointed to
+ by endptr, provided that endptr is not a null pointer.
+ If the subject sequence is empty or does not have the expected
+ form, no conversion is performed; the value of nptr is stored in
+ the object pointed to by endptr, provided that endptr is not a null pointer.
**/
long double
strtold(const char * __restrict nptr, char ** __restrict endptr);
+/*@}*/
/* ################ Pseudo-random sequence generation functions ######### */
@@ -403,6 +585,8 @@ int rand(void); pseudo-random numbers shall be repeated. If rand is called before any calls
to srand have been made, the same sequence shall be generated as when srand
is first called with a seed value of 1.
+
+ @param[in] seed The value used to "seed" the random number generator with.
**/
void srand(unsigned seed);
@@ -411,6 +595,9 @@ void srand(unsigned seed); /** The calloc function allocates space for an array of Num objects, each of
whose size is Size. The space is initialized to all bits zero.
+ @param[in] Num The number of objects to allocate space for.
+ @param[in] Size The size, in bytes, of each object.
+
@return NULL is returned if the space could not be allocated and errno
contains the cause. Otherwise, a pointer to an 8-byte aligned
region of the requested size is returned.
@@ -426,9 +613,8 @@ void *calloc(size_t Num, size_t Size); realloc, the behavior is undefined.
@param Ptr Pointer to a previously allocated region of memory to be freed.
-
**/
-void free(void *);
+void free(void *Ptr);
/** The malloc function allocates space for an object whose size is specified
by size and whose value is indeterminate.
@@ -437,7 +623,7 @@ void free(void *); region of memory that is 8-byte aligned and of the specified size. The
region is allocated with type EfiLoaderData.
- @param size Size, in bytes, of the region to allocate.
+ @param Size Size, in bytes, of the region to allocate.
@return NULL is returned if the space could not be allocated and errno
contains the cause. Otherwise, a pointer to an 8-byte aligned
@@ -446,7 +632,7 @@ void free(void *); - EINVAL: Requested Size is zero.
- ENOMEM: Memory could not be allocated.
**/
-void *malloc(size_t);
+void *malloc(size_t Size);
/** The realloc function changes the size of the object pointed to by Ptr to
the size specified by NewSize.
@@ -483,35 +669,40 @@ void *realloc(void *Ptr, size_t NewSize); /* ################ Searching and Sorting utilities ##################### */
-/** The bsearch function searches an array of nmemb objects, the initial
- element of which is pointed to by base, for an element that matches the
- object pointed to by key. The size of each element of the array is
- specified by size.
+/** The bsearch function searches an array of Nmemb objects, the initial
+ element of which is pointed to by Base, for an element that matches the
+ object pointed to by Key. The size of each element of the array is
+ specified by Size.
- The comparison function pointed to by compar is called with two arguments
- that point to the key object and to an array element, in that order. The
+ The comparison function pointed to by Compar is called with two arguments
+ that point to the Key object and to an array element, in that order. The
function returns an integer less than, equal to, or greater than zero if
- the key object is considered, respectively, to be less than, to match, or
+ the Key object is considered, respectively, to be less than, to match, or
to be greater than the array element. The array consists of: all the
elements that compare less than, all the elements that compare equal to,
and all the elements that compare greater than the key object,
in that order.
- @return The bsearch function returns a pointer to a matching element of the
- array, or a null pointer if no match is found. If two elements
- compare as equal, which element is matched is unspecified.
+ @param[in] Key Pointer to the object to search for.
+ @param[in] Base Pointer to the first element of an array to search.
+ @param[in] Nmemb Number of objects in the search array.
+ @param[in] Size The size of each object in the search array.
+ @param[in] Compar Pointer to the function used to compare two objects.
+
+ @return The bsearch function returns a pointer to a matching element of the
+ array, or a null pointer if no match is found. If two elements
+ compare as equal, which element is matched is unspecified.
**/
-void *
-bsearch( const void *key, const void *base0,
- size_t nmemb, size_t size,
- int (*compar)(const void *, const void *)
-);
+void *bsearch( const void *Key, const void *Base,
+ size_t Nmemb, size_t Size,
+ int (*Compar)(const void *, const void *)
+ );
-/** The qsort function sorts an array of nmemb objects, the initial element of
- which is pointed to by base. The size of each object is specified by size.
+/** The qsort function sorts an array of Nmemb objects, the initial element of
+ which is pointed to by Base. The size of each object is specified by Size.
The contents of the array are sorted into ascending order according to a
- comparison function pointed to by compar, which is called with two
+ comparison function pointed to by Compar, which is called with two
arguments that point to the objects being compared. The function shall
return an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or greater
@@ -519,165 +710,183 @@ bsearch( const void *key, const void *base0, If two elements compare as equal, their order in the resulting sorted array
is unspecified.
+
+ @param[in,out] Base Pointer to the first element of an array to sort.
+ @param[in] Nmemb Number of objects in the array.
+ @param[in] Size The size of each object in the array.
+ @param[in] Compar Pointer to the function used to compare two objects.
**/
-void qsort( void *base, size_t nmemb, size_t size,
- int (*compar)(const void *, const void *));
+void qsort( void *base, size_t nmemb, size_t size,
+ int (*compar)(const void *, const void *));
/* ################ Multibyte/wide character conversion functions ####### */
/** Determine the number of bytes comprising a multibyte character.
- If s is not a null pointer, the mblen function determines the number of bytes
- contained in the multibyte character pointed to by s. Except that the
+ If S is not a null pointer, the mblen function determines the number of bytes
+ contained in the multibyte character pointed to by S. Except that the
conversion state of the mbtowc function is not affected, it is equivalent to
- mbtowc((wchar_t *)0, s, n);
+ mbtowc((wchar_t *)0, S, N);
- The implementation shall behave as if no library function calls the mblen
- function.
+ @param[in] S NULL to query whether multibyte characters have
+ state-dependent encodings. Otherwise, points to a
+ multibyte character.
+ @param[in] N The maximum number of bytes in a multibyte character.
- @return If s is a null pointer, the mblen function returns a nonzero or
+ @return If S is a null pointer, the mblen function returns a nonzero or
zero value, if multibyte character encodings, respectively, do
- or do not have state-dependent encodings. If s is not a null
- pointer, the mblen function either returns 0 (if s points to the
+ or do not have state-dependent encodings. If S is not a null
+ pointer, the mblen function either returns 0 (if S points to the
null character), or returns the number of bytes that are contained
- in the multibyte character (if the next n or fewer bytes form a
+ in the multibyte character (if the next N or fewer bytes form a
valid multibyte character), or returns -1 (if they do not form a
valid multibyte character).
**/
-int mblen(const char *, size_t);
+int mblen(const char *S, size_t N);
/** Convert a multibyte character into a wide character.
- If s is not a null pointer, the mbtowc function inspects at most n bytes
- beginning with the byte pointed to by s to determine the number of bytes
+ If S is not a null pointer, the mbtowc function inspects at most N bytes
+ beginning with the byte pointed to by S to determine the number of bytes
needed to complete the next multibyte character (including any shift
sequences). If the function determines that the next multibyte character
is complete and valid, it determines the value of the corresponding wide
- character and then, if pwc is not a null pointer, stores that value in
- the object pointed to by pwc. If the corresponding wide character is the
+ character and then, if Pwc is not a null pointer, stores that value in
+ the object pointed to by Pwc. If the corresponding wide character is the
null wide character, the function is left in the initial conversion state.
- The implementation shall behave as if no library function calls the
- mbtowc function.
+ @param[out] Pwc Pointer to a wide-character object to receive the converted character.
+ @param[in] S Pointer to a multibyte character to convert.
+ @param[in] N Maximum number of bytes in a multibyte character.
- @return If s is a null pointer, the mbtowc function returns a nonzero or
+ @return If S is a null pointer, the mbtowc function returns a nonzero or
zero value, if multibyte character encodings, respectively, do
- or do not have state-dependent encodings. If s is not a null
- pointer, the mbtowc function either returns 0 (if s points to
+ or do not have state-dependent encodings. If S is not a null
+ pointer, the mbtowc function either returns 0 (if S points to
the null character), or returns the number of bytes that are
- contained in the converted multibyte character (if the next n or
+ contained in the converted multibyte character (if the next N or
fewer bytes form a valid multibyte character), or returns -1
(if they do not form a valid multibyte character).
- In no case will the value returned be greater than n or the value
+ In no case will the value returned be greater than N or the value
of the MB_CUR_MAX macro.
**/
-int mbtowc(wchar_t * __restrict, const char * __restrict, size_t);
+int mbtowc(wchar_t * __restrict Pwc, const char * __restrict S, size_t N);
-/**
-The wctomb function determines the number of bytes needed to represent the multibyte
-character corresponding to the wide character given by wc (including any shift
-sequences), and stores the multibyte character representation in the array whose first
-element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
-are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
-sequence needed to restore the initial shift state, and the function is left in the initial
-conversion state.
+/** Convert a wide character into a multibyte character.
-The implementation shall behave as if no library function calls the wctomb function.
+ The wctomb function determines the number of bytes needed to represent the
+ multibyte character corresponding to the wide character given by WC
+ (including any shift sequences), and stores the multibyte character
+ representation in the array whose first element is pointed to by S (if S is
+ not a null pointer). At most MB_CUR_MAX characters are stored. If WC is a
+ null wide character, a null byte is stored, preceded by any shift sequence
+ needed to restore the initial shift state, and the function is left in the
+ initial conversion state.
- @return
-If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
-character encodings, respectively, do or do not have state-dependent encodings. If s is
-not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
-to a valid multibyte character, or returns the number of bytes that are contained in the
-multibyte character corresponding to the value of wc.
+ @param[out] S Pointer to the object to receive the converted multibyte character.
+ @param[in] WC Wide character to be converted.
-In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
+ @return If S is a null pointer, the wctomb function returns a nonzero or
+ zero value, if multibyte character encodings, respectively, do or
+ do not have state-dependent encodings. If S is not a null pointer,
+ the wctomb function returns -1 if the value of WC does not
+ correspond to a valid multibyte character, or returns the number
+ of bytes that are contained in the multibyte character
+ corresponding to the value of WC.
+ In no case will the value returned be greater than the value of
+ the MB_CUR_MAX macro.
**/
-int wctomb(char *, wchar_t);
+int wctomb(char *S, wchar_t WC);
/* ################ Multibyte/wide string conversion functions ########## */
/** Convert a multibyte character string into a wide-character string.
The mbstowcs function converts a sequence of multibyte characters that
- begins in the initial shift state from the array pointed to by src into
+ begins in the initial shift state from the array pointed to by Src into
a sequence of corresponding wide characters and stores not more than limit
- wide characters into the array pointed to by dest. No multibyte
+ wide characters into the array pointed to by Dest. No multibyte
characters that follow a null character (which is converted into a null
wide character) will be examined or converted. Each multibyte character
is converted as if by a call to the mbtowc function, except that the
conversion state of the mbtowc function is not affected.
- No more than limit elements will be modified in the array pointed to by dest.
+ No more than Limit elements will be modified in the array pointed to by Dest.
If copying takes place between objects that overlap,
the behavior is undefined.
- @return If an invalid multibyte character is encountered, the mbstowcs
- function returns (size_t)(-1). Otherwise, the mbstowcs function
- returns the number of array elements modified, not including a
- terminating null wide character, if any.
+ @param[out] Dest Pointer to the array to receive the converted string.
+ @param[in] Src Pointer to the string to be converted.
+ @param[in] Limit Maximum number of elements to be written to Dest.
+ @return If an invalid multibyte character is encountered, the mbstowcs
+ function returns (size_t)(-1). Otherwise, the mbstowcs function
+ returns the number of array elements modified, not including a
+ terminating null wide character, if any.
**/
-size_t mbstowcs(wchar_t * __restrict dest, const char * __restrict src, size_t limit);
+size_t mbstowcs(wchar_t * __restrict Dest, const char * __restrict Src, size_t Limit);
/** Convert a wide-character string into a multibyte character string.
The wcstombs function converts a sequence of wide characters from the
- array pointed to by src into a sequence of corresponding multibyte
+ array pointed to by Src into a sequence of corresponding multibyte
characters that begins in the initial shift state, and stores these
- multibyte characters into the array pointed to by dest, stopping if a
- multibyte character would exceed the limit of limit total bytes or if a
+ multibyte characters into the array pointed to by Dest, stopping if a
+ multibyte character would exceed the limit of Limit total bytes or if a
null character is stored. Each wide character is converted as if by
a call to the wctomb function, except that the conversion state of
the wctomb function is not affected.
- No more than limit bytes will be modified in the array pointed to by dest.
+ No more than Limit bytes will be modified in the array pointed to by Dest.
If copying takes place between objects that overlap,
the behavior is undefined.
- @return If a wide character is encountered that does not correspond to a
- valid multibyte character, the wcstombs function returns
- (size_t)(-1). Otherwise, the wcstombs function returns the number
- of bytes modified, not including a terminating null character,
- if any.
+ @param[out] Dest Pointer to the array to receive the converted string.
+ @param[in] Src Pointer to the string to be converted.
+ @param[in] Limit Maximum number of elements to be written to Dest.
+
+ @return If a wide character is encountered that does not correspond to a
+ valid multibyte character, the wcstombs function returns
+ (size_t)(-1). Otherwise, the wcstombs function returns the number
+ of bytes modified, not including a terminating null character,
+ if any.
**/
-size_t wcstombs(char * __restrict dest, const wchar_t * __restrict src, size_t limit);
+size_t wcstombs(char * __restrict Dest, const wchar_t * __restrict Src, size_t Limit);
+
+/* ################ Miscelaneous functions for *nix compatibility ########## */
-/**
- The realpath() function shall derive, from the pathname pointed to by
- file_name, an absolute pathname that names the same file, whose resolution
- does not involve '.', '..', or symbolic links. The generated pathname shall
- be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
- in the buffer pointed to by resolved_name.
+/** The realpath() function shall derive, from the pathname pointed to by
+ file_name, an absolute pathname that names the same file, whose resolution
+ does not involve '.', '..', or symbolic links. The generated pathname shall
+ be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes,
+ in the buffer pointed to by resolved_name.
- If resolved_name is a null pointer, the behavior of realpath() is
- implementation-defined.
+ If resolved_name is a null pointer, the behavior of realpath() is
+ implementation-defined.
- @param[in] file_name The filename to convert.
- @param[in,out] resolved_name The resultant name.
+ @param[in] file_name The filename to convert.
+ @param[in,out] resolved_name The resultant name.
- @retval NULL An error occured.
- @return resolved_name.
+ @retval NULL An error occured.
+ @retval resolved_name.
**/
char * realpath(char *file_name, char *resolved_name);
-/**
- The getprogname() function returns the name of the program. If the name
- has not been set yet, it will return NULL.
+/** The getprogname() function returns the name of the program. If the name
+ has not been set yet, it will return NULL.
- @retval The name of the program.
- @retval NULL The name has not been set.
+ @return The getprogname function returns NULL if the program's name has not
+ been set, otherwise it returns the name of the program.
**/
const char * getprogname(void);
-/**
- The setprogname() function sets the name of the program.
+/** The setprogname() function sets the name of the program.
- @param[in] The name of the program. This memory must be retained
- by the caller until no calls to "getprogname" will be
- called.
+ @param[in] progname The name of the program. This memory must be retained
+ by the caller until no calls to "getprogname" will be
+ called.
**/
void setprogname(const char *progname);
diff --git a/StdLib/Include/string.h b/StdLib/Include/string.h index 517b9e6..0c80944 100644 --- a/StdLib/Include/string.h +++ b/StdLib/Include/string.h @@ -1,29 +1,87 @@ /** @file
- The header <string.h> declares one type and several functions, and defines
- one macro useful for manipulating arrays of character type and other objects
- treated as arrays of character type. Various methods are used for
- determining the lengths of the arrays, but in all cases a char * or void *
- argument points to the initial (lowest addressed) character of the array. If
- an array is accessed beyond the end of an object, the behavior is undefined.
-
- Where an argument declared as size_t n specifies the length of the array for
- a function, n can have the value zero on a call to that function. Unless
- explicitly stated otherwise in the description of those functions, pointer
- arguments on such a call shall still have valid values.
-
- For all functions declared in this header, each character shall be
- interpreted as if it had the type unsigned char (and therefore every possible
- object representation is valid and has a different value).
-
-Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
+ The header <string.h> declares one type and several functions, and defines
+ one macro useful for manipulating arrays of character type and other objects
+ treated as arrays of character type. Various methods are used for
+ determining the lengths of the arrays, but in all cases a char * or void *
+ argument points to the initial (lowest addressed) character of the array. If
+ an array is accessed beyond the end of an object, the behavior is undefined.
+
+ Where an argument declared as size_t n specifies the length of the array for
+ a function, n can have the value zero on a call to that function. Unless
+ explicitly stated otherwise in the description of those functions, pointer
+ arguments on such a call must still have valid values.
+
+ For all functions declared in this header, each character shall be
+ interpreted as if it had the type unsigned char (and therefore every possible
+ object representation is valid and has a different value).
+
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL
+ bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c))
+ bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c))
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+ @verbatim
+ ################ Copying Functions
+ void *memcpy (void * __restrict s1, const void * __restrict s2, size_t n);
+ void *memmove (void *s1, const void *s2, size_t n);
+ char *strcpy (char * __restrict s1, const char * __restrict s2);
+ char *strncpy (char * __restrict s1, const char * __restrict s2, size_t n);
+ int strncpyX (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Concatenation Functions
+ char *strcat (char * __restrict s1, const char * __restrict s2);
+ char *strncat (char * __restrict s1, const char * __restrict s2, size_t n);
+ int strncatX (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Comparison Functions
+ int memcmp (const void *s1, const void *s2, size_t n);
+ int strcmp (const char *s1, const char *s2);
+ int strcoll (const char *s1, const char *s2);
+ int strncmp (const char *s1, const char *s2, size_t n);
+ size_t strxfrm (char * __restrict s1, const char * __restrict s2, size_t n);
+
+ ################ Search Functions
+ void *memchr (const void *s, int c, size_t n);
+ char *strchr (const char *s, int c);
+ size_t strcspn (const char *s1, const char *s2);
+ char *strpbrk (const char *s1, const char *s2);
+ char *strrchr (const char *s, int c);
+ size_t strspn (const char *s1 , const char *s2);
+ char *strstr (const char *s1 , const char *s2);
+ char *strtok (char * __restrict s1, const char * __restrict s2);
+
+ ################ Miscellaneous Functions
+ void *memset (void *s, int c, size_t n);
+ char *strerror (int num);
+ size_t strlen (const char *);
+
+ ################ BSD Compatibility Functions
+ char *strdup (const char *);
+ int strerror_r (int, char *, size_t);
+ int strcasecmp (const char *s1, const char *s2);
+ void *memccpy (void *, const void *, int, size_t);
+ int strncasecmp (const char *s1, const char *s2, size_t n);
+ size_t strlcpy (char *destination, const char *source, size_t size);
+ size_t strlcat (char *destination, const char *source, size_t size);
+ char *strsep (register char **stringp, register const char *delim);
+ @endverbatim
+
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _STRING_H
#define _STRING_H
@@ -39,239 +97,311 @@ __BEGIN_DECLS /* ################ Copying Functions ################################# */
-/** The memcpy function copies n characters from the object pointed to by s2
- into the object pointed to by s1. If copying takes place between objects
+/** The memcpy function copies N characters from the object pointed to by Src
+ into the object pointed to by Dest. If copying takes place between objects
that overlap, the behavior is undefined.
- @return The memcpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The memcpy function returns the value of Dest.
**/
-void *memcpy(void * __restrict s1, const void * __restrict s2, size_t n);
+void *memcpy(void * __restrict Dest, const void * __restrict Src, size_t N);
-/** The memmove function copies n characters from the object pointed to by s2
- into the object pointed to by s1. Copying takes place as if the n
- characters from the object pointed to by s2 are first copied into a
- temporary array of n characters that does not overlap the objects pointed
- to by s1 and s2, and then the n characters from the temporary array are
- copied into the object pointed to by s1.
+/** The memmove function copies N characters from the object pointed to by Src
+ into the object pointed to by Dest. Copying takes place as if the N
+ characters from the object pointed to by Src are first copied into a
+ temporary array of N characters that does not overlap the objects pointed
+ to by Dest and Src, and then the N characters from the temporary array are
+ copied into the object pointed to by Dest.
- @return The memmove function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The memmove function returns the value of Dest.
**/
-void *memmove(void *s1, const void *s2, size_t n);
+void *memmove(void *Dest, const void *Src, size_t N);
-/** The strcpy function copies the string pointed to by s2 (including the
- terminating null character) into the array pointed to by s1. If copying
+/** The strcpy function copies the string pointed to by Src (including the
+ terminating null character) into the array pointed to by Dest. If copying
takes place between objects that overlap, the behavior is undefined.
- @return The strcpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+
+ @return The strcpy function returns the value of Dest.
**/
-char *strcpy(char * __restrict s1, const char * __restrict s2);
+char *strcpy(char * __restrict Dest, const char * __restrict Src);
-/** The strncpy function copies not more than n characters (characters that
- follow a null character are not copied) from the array pointed to by s2 to
- the array pointed to by s1. If copying takes place between objects that
+/** The strncpy function copies not more than N characters (characters that
+ follow a null character are not copied) from the array pointed to by Src to
+ the array pointed to by Dest. If copying takes place between objects that
overlap, the behavior is undefined.
- If the array pointed to by s2 is a string that is shorter than n
+ If the array pointed to by Src is a string that is shorter than N
characters, null characters are appended to the copy in the array pointed
- to by s1, until n characters in all have been written.
+ to by Dest, until N characters in all have been written.
- @return The strncpy function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
+
+ @return The strncpy function returns the value of Dest.
**/
-char *strncpy(char * __restrict s1, const char * __restrict s2, size_t n);
+char *strncpy(char * __restrict Dest, const char * __restrict Src, size_t N);
-/** The strncpyX function copies not more than n-1 characters (characters that
- follow a null character are not copied) from the array pointed to by s2 to
- the array pointed to by s1. Array s1 is guaranteed to be NULL terminated.
+/** The strncpyX function copies not more than N-1 characters (characters that
+ follow a null character are not copied) from the array pointed to by Src to
+ the array pointed to by Dest. Array Dest is guaranteed to be NULL terminated.
If copying takes place between objects that overlap,
the behavior is undefined.
strncpyX exists because normal strncpy does not indicate if the copy was
- terminated because of exhausting the buffer or reaching the end of s2.
+ terminated because of exhausting the buffer or reaching the end of Src.
+
+ @param[out] Dest Pointer to the destination of the copy operation.
+ @param[in] Src Pointer to the Source data to be copied.
+ @param[in] N Number of characters (bytes) to be copied.
@return The strncpyX function returns 0 if the copy operation was
- terminated because it reached the end of s1. Otherwise,
+ terminated because it reached the end of Dest. Otherwise,
a non-zero value is returned indicating how many characters
- remain in s1.
+ remain in Dest.
**/
-int strncpyX(char * __restrict s1, const char * __restrict s2, size_t n);
+int strncpyX(char * __restrict Dest, const char * __restrict Src, size_t N);
/* ################ Concatenation Functions ########################### */
-/** The strcat function appends a copy of the string pointed to by s2
+/** The strcat function appends a copy of the string pointed to by Src
(including the terminating null character) to the end of the string pointed
- to by s1. The initial character of s2 overwrites the null character at the
- end of s1. If copying takes place between objects that overlap, the
+ to by Dest. The initial character of Src overwrites the null character at the
+ end of Dest. If copying takes place between objects that overlap, the
behavior is undefined.
- @return The strcat function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+
+ @return The strcat function returns the value of Dest.
**/
-char *strcat(char * __restrict s1, const char * __restrict s2);
+char *strcat(char * __restrict Dest, const char * __restrict Src);
-/** The strncat function appends not more than n characters (a null character
+/** The strncat function appends not more than N characters (a null character
and characters that follow it are not appended) from the array pointed to
- by s2 to the end of the string pointed to by s1. The initial character of
- s2 overwrites the null character at the end of s1. A terminating null
+ by Src to the end of the string pointed to by Dest. The initial character of
+ Src overwrites the null character at the end of Dest. A terminating null
character is always appended to the result. If copying takes place
between objects that overlap, the behavior is undefined.
- @return The strncat function returns the value of s1.
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+ @param[in] N Max Number of characters (bytes) to be concatenated.
+
+ @return The strncat function returns the value of Dest.
**/
-char *strncat(char * __restrict s1, const char * __restrict s2, size_t n);
+char *strncat(char * __restrict Dest, const char * __restrict Src, size_t N);
-/** The strncatX function appends not more than n characters (a null character
+/** The strncatX function appends not more than N characters (a null character
and characters that follow it are not appended) from the array pointed to
- by s2 to the end of the string pointed to by s1. The initial character of
- s2 overwrites the null character at the end of s1. The result is always
+ by Src to the end of the string pointed to by Dest. The initial character of
+ Src overwrites the null character at the end of Dest. The result is always
terminated with a null character. If copying takes place between objects
that overlap, the behavior is undefined.
strncatX exists because normal strncat does not indicate if the operation
- was terminated because of exhausting n or reaching the end of s2.
+ was terminated because of exhausting N or reaching the end of Src.
+
+ @param[out] Dest Pointer to the destination of the concatenation operation.
+ @param[in] Src Pointer to the Source data to be concatenated.
+ @param[in] N Max Number of characters (bytes) to be concatenated.
@return The strncatX function returns 0 if the operation was terminated
- because it reached the end of s1. Otherwise, a non-zero value is
- returned indicating how many characters remain in s1.
+ because it reached the end of Dest. Otherwise, a non-zero value is
+ returned indicating how many characters remain in Dest.
**/
int strncatX(char * __restrict s1, const char * __restrict s2, size_t n);
/* ################ Comparison Functions ############################## */
-/** The memcmp function compares the first n characters of the object pointed
- to by s1 to the first n characters of the object pointed to by s2.
+/** The memcmp function compares the first N characters of the object pointed
+ to by S1 to the first N characters of the object pointed to by S2.
+
+ @param[out] S1 Pointer to the first object to be compared.
+ @param[in] S2 Pointer to the object to be compared to S1.
+ @param[in] N Max Number of characters (bytes) to be compared.
@return The memcmp function returns an integer greater than, equal to, or
- less than zero, accordingly as the object pointed to by s1 is
- greater than, equal to, or less than the object pointed to by s2.
+ less than zero, accordingly as the object pointed to by S1 is
+ greater than, equal to, or less than the object pointed to by S2.
**/
-int memcmp(const void *s1, const void *s2, size_t n);
+int memcmp(const void *S1, const void *S2, size_t N);
-/** The strcmp function compares the string pointed to by s1 to the string
- pointed to by s2.
+/** The strcmp function compares the string pointed to by S1 to the string
+ pointed to by S2.
+
+ @param[out] S1 Pointer to the first string to be compared.
+ @param[in] S2 Pointer to the string to be compared to S1.
@return The strcmp function returns an integer greater than, equal to, or
- less than zero, accordingly as the string pointed to by s1 is
- greater than, equal to, or less than the string pointed to by s2.
+ less than zero, accordingly as the string pointed to by S1 is
+ greater than, equal to, or less than the string pointed to by S2.
**/
-int strcmp(const char *s1, const char *s2);
+int strcmp(const char *S1, const char *S2);
-/** The strcoll function compares the string pointed to by s1 to the string
- pointed to by s2, both interpreted as appropriate to the LC_COLLATE
+/** The strcoll function compares the string pointed to by S1 to the string
+ pointed to by S2, both interpreted as appropriate to the LC_COLLATE
category of the current locale.
+ @param[out] S1 Pointer to the first string to be compared.
+ @param[in] S2 Pointer to the string to be compared to S1.
+
@return The strcoll function returns an integer greater than, equal to,
- or less than zero, accordingly as the string pointed to by s1 is
- greater than, equal to, or less than the string pointed to by s2
+ or less than zero, accordingly as the string pointed to by S1 is
+ greater than, equal to, or less than the string pointed to by S2
when both are interpreted as appropriate to the current locale.
**/
-int strcoll(const char *s1, const char *s2);
+int strcoll(const char *S1, const char *S2);
+
+/** The strncmp function compares not more than N characters (characters that
+ follow a null character are not compared) from the array pointed to by S1
+ to the array pointed to by S2.
-/** The strncmp function compares not more than n characters (characters that
- follow a null character are not compared) from the array pointed to by s1
- to the array pointed to by s2.
+ @param[out] S1 Pointer to the first object to be compared.
+ @param[in] S2 Pointer to the object to be compared to S1.
+ @param[in] N Max Number of characters (bytes) to be compared.
@return The strncmp function returns an integer greater than, equal to,
or less than zero, accordingly as the possibly null-terminated
- array pointed to by s1 is greater than, equal to, or less than
- the possibly null-terminated array pointed to by s2.
+ array pointed to by S1 is greater than, equal to, or less than
+ the possibly null-terminated array pointed to by S2.
**/
-int strncmp(const char *s1, const char *s2, size_t n);
+int strncmp(const char *S1, const char *S2, size_t N);
-/** The strxfrm function transforms the string pointed to by s2 and places the
- resulting string into the array pointed to by s1. The transformation is
+/** The strxfrm function transforms the string pointed to by Src and places the
+ resulting string into the array pointed to by Dest. The transformation is
such that if the strcmp function is applied to two transformed strings, it
returns a value greater than, equal to, or less than zero, corresponding to
the result of the strcoll function applied to the same two original
- strings. No more than n characters are placed into the resulting array
- pointed to by s1, including the terminating null character. If n is zero,
- s1 is permitted to be a null pointer. If copying takes place between
+ strings. No more than N characters are placed into the resulting array
+ pointed to by Dest, including the terminating null character. If N is zero,
+ Dest is permitted to be a null pointer. If copying takes place between
objects that overlap, the behavior is undefined.
+ @param[out] Dest Pointer to the object to receive the transformed string.
+ @param[in] Src Pointer to the string to be transformed.
+ @param[in] N Max Number of characters (bytes) to be transformed.
+
@return The strxfrm function returns the length of the transformed string
(not including the terminating null character). If the value
- returned is n or more, the contents of the array pointed to by s1
+ returned is N or more, the contents of the array pointed to by Dest
are indeterminate.
**/
-size_t strxfrm(char * __restrict s1, const char * __restrict s2, size_t n);
+size_t strxfrm(char * __restrict Dest, const char * __restrict Src, size_t N);
/* ################ Search Functions ################################## */
-/** The memchr function locates the first occurrence of c (converted to an
- unsigned char) in the initial n characters (each interpreted as
- unsigned char) of the object pointed to by s.
+/** The memchr function locates the first occurrence of C (converted to an
+ unsigned char) in the initial N characters (each interpreted as
+ unsigned char) of the object pointed to by S.
+
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+ @param[in] N Max Number of characters (bytes) to be searched.
@return The memchr function returns a pointer to the located character,
or a null pointer if the character does not occur in the object.
**/
-void *memchr(const void *s, int c, size_t n);
+void *memchr(const void *S, int C, size_t N);
-/** The strchr function locates the first occurrence of c (converted to a char)
- in the string pointed to by s. The terminating null character is considered
+/** The strchr function locates the first occurrence of C (converted to a char)
+ in the string pointed to by S. The terminating null character is considered
to be part of the string.
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+
@return The strchr function returns a pointer to the located character,
or a null pointer if the character does not occur in the string.
**/
-char *strchr(const char *s, int c);
+char *strchr(const char *S, int C);
/** The strcspn function computes the length of the maximum initial segment of
- the string pointed to by s1 which consists entirely of characters NOT from
- the string pointed to by s2.
+ the string pointed to by S1 which consists entirely of characters NOT from
+ the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strcspn function returns the length of the segment.
**/
-size_t strcspn(const char *s1, const char *s2);
+size_t strcspn(const char *S1, const char *S2);
/** The strpbrk function locates the first occurrence in the string pointed to
- by s1 of any character from the string pointed to by s2.
+ by S1 of any character from the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strpbrk function returns a pointer to the character, or a
- null pointer if no character from s2 occurs in s1.
+ null pointer if no character from S2 occurs in S1.
**/
-char *strpbrk(const char *s1, const char *s2);
+char *strpbrk(const char *S1, const char *S2);
-/** The strrchr function locates the last occurrence of c (converted to a char)
- in the string pointed to by s. The terminating null character is considered
+/** The strrchr function locates the last occurrence of C (converted to a char)
+ in the string pointed to by S. The terminating null character is considered
to be part of the string.
+ @param[in] S Pointer to the object to be searched.
+ @param[in] C The character value to search for.
+
@return The strrchr function returns a pointer to the character, or a
- null pointer if c does not occur in the string.
+ null pointer if C does not occur in the string.
**/
-char *strrchr(const char *s, int c);
+char *strrchr(const char *S, int C);
/** The strspn function computes the length of the maximum initial segment of
- the string pointed to by s1 which consists entirely of characters from the
- string pointed to by s2.
+ the string pointed to by S1 which consists entirely of characters from the
+ string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the list of characters to search for.
@return The strspn function returns the length of the segment.
**/
-size_t strspn(const char *s1 , const char *s2);
+size_t strspn(const char *S1 , const char *S2);
/** The strstr function locates the first occurrence in the string pointed to
- by s1 of the sequence of characters (excluding the terminating null
- character) in the string pointed to by s2.
+ by S1 of the sequence of characters (excluding the terminating null
+ character) in the string pointed to by S2.
+
+ @param[in] S1 Pointer to the object to be searched.
+ @param[in] S2 Pointer to the sequence of characters to search for.
@return The strstr function returns a pointer to the located string, or a
- null pointer if the string is not found. If s2 points to a string
- with zero length, the function returns s1.
+ null pointer if the string is not found. If S2 points to a string
+ with zero length, the function returns S1.
**/
-char *strstr(const char *s1 , const char *s2);
+char *strstr(const char *S1 , const char *S2);
+
+/** Break a string into a sequence of tokens.
-/** A sequence of calls to the strtok function breaks the string pointed to by
- s1 into a sequence of tokens, each of which is delimited by a character
- from the string pointed to by s2. The first call in the sequence has a
+ A sequence of calls to the strtok function breaks the string pointed to by
+ S1 into a sequence of tokens, each of which is delimited by a character
+ from the string pointed to by S2. The first call in the sequence has a
non-null first argument; subsequent calls in the sequence have a null first
- argument. The separator string pointed to by s2 may be different from call
+ argument. The separator string pointed to by S2 may be different from call
to call.
- The first call in the sequence searches the string pointed to by s1 for the
+ The first call in the sequence searches the string pointed to by S1 for the
first character that is not contained in the current separator string
- pointed to by s2. If no such character is found, then there are no tokens
- in the string pointed to by s1 and the strtok function returns a null
+ pointed to by S2. If no such character is found, then there are no tokens
+ in the string pointed to by S1 and the strtok function returns a null
pointer. If such a character is found, it is the start of the first token.
The strtok function then searches from there for a character that is
contained in the current separator string. If no such character is found,
- the current token extends to the end of the string pointed to by s1, and
+ the current token extends to the end of the string pointed to by S1, and
subsequent searches for a token will return a null pointer. If such a
character is found, it is overwritten by a null character, which terminates
the current token. The strtok function saves a pointer to the following
@@ -281,40 +411,48 @@ char *strstr(const char *s1 , const char *s2); argument, starts searching from the saved pointer and behaves as
described above.
+ @param[in] S1 Pointer to the string to be tokenized.
+ @param[in] S2 Pointer to a list of separator characters.
+
@return The strtok function returns a pointer to the first character of a
token, or a null pointer if there is no token.
**/
-char *strtok(char * __restrict s1, const char * __restrict s2);
+char *strtok(char * __restrict S1, const char * __restrict S2);
/* ################ Miscellaneous Functions ########################### */
-/** The memset function copies the value of c (converted to an unsigned char)
- into each of the first n characters of the object pointed to by s.
+/** The memset function copies the value of C (converted to an unsigned char)
+ into each of the first N characters of the object pointed to by S.
+
+ @param[out] S Pointer to the first element of the object to be set.
+ @param[in] C Value to store in each element of S.
+ @param[in] N Number of elements in S to be set.
- @return The memset function returns the value of s.
+ @return The memset function returns the value of S.
**/
-void *memset(void *s, int c, size_t n);
+void *memset(void *S, int C, size_t N);
-/** The strerror function maps the number in errnum to a message string.
- Typically, the values for errnum come from errno, but strerror shall map
+/** The strerror function maps the number in Num to a message string.
+ Typically, the values for Num come from errno, but strerror shall map
any value of type int to a message.
- The implementation shall behave as if no library function calls the
- strerror function.
+ @param[in] Num A value to be converted to a message.
@return The strerror function returns a pointer to the string, the
contents of which are locale specific. The array pointed to
- shall not be modified by the program, but may be overwritten by
+ must not be modified by the program, but may be overwritten by
a subsequent call to the strerror function.
**/
-char *strerror(int num);
+char *strerror(int Num);
+
+/** The strlen function computes the length of the string pointed to by S.
-/** The strlen function computes the length of the string pointed to by s.
+ @param[in] S Pointer to the string to determine the length of.
@return The strlen function returns the number of characters that
precede the terminating null character.
**/
-size_t strlen(const char *);
+size_t strlen(const char *S);
/* ################ BSD Compatibility Functions ####################### */
diff --git a/StdLib/Include/sys/EfiCdefs.h b/StdLib/Include/sys/EfiCdefs.h index c3a2772..812a495 100644 --- a/StdLib/Include/sys/EfiCdefs.h +++ b/StdLib/Include/sys/EfiCdefs.h @@ -102,6 +102,7 @@ //#define _EFI_WINT_MIN (0)
//#define _EFI_WINT_MAX (0xFFFF)
#define _EFI_PTRDIFF_T_ __PTRDIFF_TYPE__ /* ptr1 - ptr2 --- Must be same size as size_t */
+
#else
#define _EFI_SIZE_T_ UINTN /* sizeof() */
#define _EFI_WCHAR_T UINT16
@@ -338,13 +339,29 @@ extern int _fltused; // VC++ requires this if you use floating point. KEEP f #define _DIAGASSERT(e)
// Types used to replace long so that it will have constant length regardless of compiler.
-typedef INT32 EFI_LONG_T; // Equivalent to long in VS200?
-typedef UINT32 EFI_ULONG_T; // Equivalent to unsigned long in VS200?
-typedef INTN LONGN;
-typedef UINTN ULONGN;
-typedef INT32 LONG32;
+typedef INT32 LONG32;
typedef UINT32 ULONG32;
typedef INT64 LONG64;
typedef UINT64 ULONG64;
+typedef INT32 EFI_LONG_T;
+typedef UINT32 EFI_ULONG_T;
+
+/* These types reflect the compiler's size for long */
+#if defined(__GNUC__)
+ #if __GNUC_PREREQ__(4,4)
+ /* GCC 4.4 or later */
+ typedef INT64 LONGN;
+ typedef UINT64 ULONGN;
+ #else
+ /* minGW gcc variant */
+ typedef INT32 LONGN;
+ typedef UINT32 ULONGN;
+ #endif /* __GNUC_PREREQ__(4,4) */
+#else /* NOT GCC */
+ /* Microsoft or Intel compilers */
+ typedef INT32 LONGN;
+ typedef UINT32 ULONGN;
+#endif /* defined(__GNUC__) */
+
#endif /* _EFI_CDEFS_H */
diff --git a/StdLib/Include/sys/EfiSysCall.h b/StdLib/Include/sys/EfiSysCall.h index a49eeda..bfbd14e 100644 --- a/StdLib/Include/sys/EfiSysCall.h +++ b/StdLib/Include/sys/EfiSysCall.h @@ -1,17 +1,74 @@ /** @file
Function declarations for UEFI "system calls".
- Concept derived from NetBSD's unistd.h file.
+ The following macros are defined in this file:<BR>
+@verbatim
+ STDIN_FILENO 0 standard input file descriptor
+ STDOUT_FILENO 1 standard output file descriptor
+ STDERR_FILENO 2 standard error file descriptor
+ F_OK 0 test for existence of file
+ X_OK 0x01 test for execute or search permission
+ W_OK 0x02 test for write permission
+ R_OK 0x04 test for read permission
+ SEEK_SET 0 set file offset to offset
+ SEEK_CUR 1 set file offset to current plus offset
+ SEEK_END 2 set file offset to EOF plus offset
+ VALID_OPEN 1
+ VALID_CLOSED 0
+ VALID_DONT_CARE -1
+@endverbatim
+
+ The following types are defined in this file:<BR>
+@verbatim
+ struct stat; Structure declared in <sys/stat.h>
+@endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### System Calls used in stdio.
+ int close (int fd);
+ ssize_t read (int fd, void *buf, size_t n);
+ ssize_t write (int fd, const void *buf, size_t n);
+ int unlink (const char *name);
+ int dup2 (int, int);
+ int rmdir (const char *);
+ int isatty (int);
+
+ ############### System Calls which are also declared in sys/fcntl.h.
+ int open (const char *name, int oflags, int mode);
+ int creat (const char *, mode_t);
+ int fcntl (int, int, ...);
+
+ ############### System Calls which are also declared in stat.h.
+ int mkdir (const char *, mode_t);
+ int fstat (int, struct stat *);
+ int lstat (const char *, struct stat *);
+ int stat (const char *, void *);
+ int chmod (const char *, mode_t);
+
+ ############### System Calls which are also declared in sys/types.h.
+ off_t lseek (int, off_t, int);
+ int truncate (const char *, off_t);
+ int ftruncate (int, off_t); // IEEE Std 1003.1b-93
+
+ ############### EFI-specific Functions.
+ int DeleteOnClose (int fd); Mark an open file to be deleted when closed.
+ int FindFreeFD (int MinFd);
+ BOOLEAN ValidateFD (int fd, int IsOpen);
+
+ ############### Functions added for compatibility.
+ char *getcwd (char *, size_t);
+ int chdir (const char *);
+@endverbatim
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
+ http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
**/
#ifndef _EFI_SYS_CALL_H
#define _EFI_SYS_CALL_H
@@ -21,27 +78,27 @@ struct stat; /* Structure declared in <sys/stat.h> */
-#define STDIN_FILENO 0 /* standard input file descriptor */
-#define STDOUT_FILENO 1 /* standard output file descriptor */
-#define STDERR_FILENO 2 /* standard error file descriptor */
+#define STDIN_FILENO 0 /**< standard input file descriptor */
+#define STDOUT_FILENO 1 /**< standard output file descriptor */
+#define STDERR_FILENO 2 /**< standard error file descriptor */
/* access function */
-#define F_OK 0 /* test for existence of file */
-#define X_OK 0x01 /* test for execute or search permission */
-#define W_OK 0x02 /* test for write permission */
-#define R_OK 0x04 /* test for read permission */
+#define F_OK 0 /**< test for existence of file */
+#define X_OK 0x01 /**< test for execute or search permission */
+#define W_OK 0x02 /**< test for write permission */
+#define R_OK 0x04 /**< test for read permission */
/* whence values for lseek(2)
Always ensure that these are consistent with <stdio.h> and <unistd.h>!
*/
#ifndef SEEK_SET
- #define SEEK_SET 0 /* set file offset to offset */
+ #define SEEK_SET 0 /**< set file offset to offset */
#endif
#ifndef SEEK_CUR
- #define SEEK_CUR 1 /* set file offset to current plus offset */
+ #define SEEK_CUR 1 /**< set file offset to current plus offset */
#endif
#ifndef SEEK_END
- #define SEEK_END 2 /* set file offset to EOF plus offset */
+ #define SEEK_END 2 /**< set file offset to EOF plus offset */
#endif
// Parameters for the ValidateFD function.
@@ -50,44 +107,234 @@ struct stat; /* Structure declared in <sys/stat.h> */ #define VALID_DONT_CARE -1
__BEGIN_DECLS
-
/* EFI versions of BSD system calls used in stdio */
-int close (int fd);
-ssize_t read (int fd, void *buf, size_t n);
-ssize_t write (int fd, const void *buf, size_t n);
-int unlink (const char *name);
-int dup2 (int, int);
-int rmdir (const char *);
-int isatty (int);
+
+ /** Close a file or device.
+
+ @param[in] fd File Descriptor for the file or device to close.
+
+ @retval 0 Successful completion.
+ @retval -1 An error occurred, identified by errno.
+ - EBADF fd is not a valid File Descriptor.
+ - EINTR The function was interrupted by a signal.
+ - EIO An I/O error occurred.
+ **/
+ int close (int fd);
+
+ /** Read from a file or device.
+
+ @param[in] fd File Descriptor for the file or device to read.
+ @param[in] buf Buffer to read data into.
+ @param[in] N Maximum number of bytes to read.
+
+ @return On successful completion, read returns a non-negative integer
+ indicating the number of bytes actually read. Otherwise, it
+ returns -1 and sets errno as follows:
+ - EAGAIN
+ - EWOULDBLOCK
+ - EBADF
+ - EBADMSG
+ - EINTR
+ - EINVAL
+ - EIO
+ - EISDIR
+ - EOVERFLOW
+ - ECONNRESET
+ - ENOTCONN
+ - ETIMEDOUT
+ - ENOBUFS
+ - ENOMEM
+ - ENXIO
+ **/
+ ssize_t read (int fd, void *buf, size_t n);
+
+ /** Write to a file or device.
+
+ @param[in] fd File Descriptor for the file or device to write.
+ @param[in] buf Buffer to write data from.
+ @param[in] N Maximum number of bytes to write.
+
+ @return On successful completion, write returns a non-negative integer
+ indicating the number of bytes actually written. Otherwise, it
+ returns -1 and sets errno as follows:
+ - EAGAIN
+ - EWOULDBLOCK
+ - EBADF
+ - EFBIG
+ - EINTR
+ - EINVAL
+ - EIO
+ - ENOSPC
+ - EPIPE
+ - ERANGE
+ - ECONNRESET
+ - ENOBUFS
+ - ENXIO
+ - ENETDOWN
+ - ENETUNREACH
+ **/
+ ssize_t write (int fd, const void *buf, size_t n);
+
+ /** Unlink (delete) a file.
+
+ @param[in] name The name of the file to be deleted.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information. The file name is unchanged.
+ **/
+ int unlink (const char *name);
+
+ /** Make file descriptor Fd2 a duplicate of file descriptor Fd1.
+
+ @param[in] Fd1 File descriptor to be duplicated
+ @param[in] Fd2 File descriptor to become a duplicate of Fd1.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information.
+ **/
+ int dup2 (int Fd1, int Fd2);
+
+ /** Remove a directory.
+
+ @param[in] Path Path to the directory to be deleted.
+
+ @retval 0 Successful completion.
+ @retval -1 Unable to perform operation, errno contains further
+ information. The named directory remains unchanged.
+ **/
+ int rmdir (const char *Path);
+
+ /** Determine if fd refers to an interactive terminal device.
+
+ @param[in] fd The file descriptor to be tested.
+
+ @retval 0 The file descriptor, fd, is not for a terminal. errno is set
+ indicating the cause for failure.
+ - EBADF fd is not a valid open file descriptor.
+ - ENOTTY fd does not refer to a terminal.
+ @retval 1 The file descriptor, fd, is for a terminal.
+ **/
+ int isatty (int fd);
/* These system calls are also declared in sys/fcntl.h */
#ifndef __FCNTL_SYSCALLS_DECLARED
#define __FCNTL_SYSCALLS_DECLARED
+
+ /** Open or create a file named by name.
+
+ The file name may be one of:
+ - An absolute path beginning with '/'.
+ - A relative path beginning with "." or ".." or a directory name
+ - A file name
+ - A mapped path which begins with a name followed by a colon, ':'.
+
+ Mapped paths are use to refer to specific mass storage volumes or devices.
+ In a Shell-hosted environment, the map command will list valid map names
+ for both file system and block devices. Mapped paths can also refer to
+ devices such as the UEFI console. Supported UEFI console mapped paths are:
+ - stdin: Standard Input (from the System Table)
+ - stdout: Standard Output (from the System Table)
+ - stderr: Standard Error Output (from the System Table)
+
+ @param[in] name
+ @param[in] oflags
+ @param[in] mode
+
+ @return
+ **/
int open (const char *name, int oflags, int mode);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int creat (const char *, mode_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int fcntl (int, int, ...);
#endif // __FCNTL_SYSCALLS_DECLARED
/* These system calls are also declared in stat.h */
#ifndef __STAT_SYSCALLS_DECLARED
#define __STAT_SYSCALLS_DECLARED
+
+ /**
+ @param[in]
+
+ @return
+ **/
int mkdir (const char *, mode_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int fstat (int, struct stat *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int lstat (const char *, struct stat *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int stat (const char *, void *);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int chmod (const char *, mode_t);
#endif // __STAT_SYSCALLS_DECLARED
// These are also declared in sys/types.h
#ifndef __OFF_T_SYSCALLS_DECLARED
#define __OFF_T_SYSCALLS_DECLARED
+
+ /**
+ @param[in]
+
+ @return
+ **/
off_t lseek (int, off_t, int);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int truncate (const char *, off_t);
+
+ /**
+ @param[in]
+
+ @return
+ **/
int ftruncate (int, off_t); // IEEE Std 1003.1b-93
#endif /* __OFF_T_SYSCALLS_DECLARED */
/* EFI-specific Functions. */
-int DeleteOnClose(int fd); /* Mark an open file to be deleted when closed. */
+
+ /**
+ @param[in]
+
+ @return
+ **/
+ int DeleteOnClose(int fd); /* Mark an open file to be deleted when closed. */
/* Find and reserve a free File Descriptor.
@@ -97,7 +344,7 @@ int DeleteOnClose(int fd); /* Mark an open file to be deleted when clos @return Returns -1 if there are no free FDs. Otherwise returns the
found fd.
*/
-int FindFreeFD (int MinFd);
+ int FindFreeFD (int MinFd);
/* Validate that fd refers to a valid file descriptor.
IsOpen is interpreted as follows:
@@ -108,15 +355,26 @@ int FindFreeFD (int MinFd); @retval TRUE fd is VALID
@retval FALSE fd is INVALID
*/
-BOOLEAN ValidateFD (int fd, int IsOpen);
+ BOOLEAN ValidateFD (int fd, int IsOpen);
-char *getcwd (char *, size_t);
-int chdir (const char *);
-/* These system calls don't YET have EFI implementations. */
-int access (const char *path, int amode);
-int reboot (int, char *);
+ /**
+ @param[in]
+
+ @return
+ **/
+ char *getcwd (char *, size_t);
+ /**
+ @param[in]
+
+ @return
+ **/
+ int chdir (const char *);
+
+/* These system calls don't YET have EFI implementations. */
+ int access (const char *path, int amode);
+ int reboot (int, char *);
__END_DECLS
#endif /* _EFI_SYS_CALL_H */
diff --git a/StdLib/Include/sys/dirent.h b/StdLib/Include/sys/dirent.h index 373664d..14c67ae 100644 --- a/StdLib/Include/sys/dirent.h +++ b/StdLib/Include/sys/dirent.h @@ -68,7 +68,7 @@ struct dirent { // on the file system volume.
UINT64 Attribute; // The time the file was created.
struct timespec CreateTime; // The time when the file was last accessed.
- struct timespec LastAccessTime; // The time when the file’s contents were last modified.
+ struct timespec LastAccessTime; // The time when the file's contents were last modified.
struct timespec ModificationTime; // The attribute bits for the file. See below.
CHAR16 FileName[1]; // The Null-terminated name of the file.
};
diff --git a/StdLib/Include/sys/signal.h b/StdLib/Include/sys/signal.h index 6f21fcd..e93b2ab 100644 --- a/StdLib/Include/sys/signal.h +++ b/StdLib/Include/sys/signal.h @@ -1,19 +1,30 @@ -/**
-Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
-This program and the accompanying materials are licensed and made available under
-the terms and conditions of the BSD License that accompanies this distribution.
-The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php.
+/** @file
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+ Implementation and Platform specific portion of <signal.h>.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _SYS_SIGNAL_H
#define _SYS_SIGNAL_H
#include <sys/EfiCdefs.h>
#include <machine/signal.h>
+/** The actual (default) signal numbers are assigned using an anonymous enum
+ so that the compiler can do the work of assigning values. This helps
+ ensure that the developer should never have to renumber the signals or
+ figure out what number to assign to a new signal.
+
+ Properly constructed programs will NEVER depend upon signal numbers being
+ in a particular order or having a particular value. All that is guaranteed
+ is that each signal number is distinct, positive, and non-zero.
+**/
enum {
__SigInt = 1,
__SigIll,
@@ -36,6 +47,7 @@ enum { /** The type of a signal handler function. **/
typedef void __sighandler_t(int);
+__BEGIN_DECLS
/** The signal function associates a "signal handler" with a signal number.
For historical reasons; programs expect signal to be declared
@@ -49,8 +61,8 @@ typedef void __sighandler_t(int); the specified signal sig. Otherwise, a value of SIG_ERR is
returned and a positive value is stored in errno.
*/
-__BEGIN_DECLS
__sighandler_t *signal(int sig, __sighandler_t *func);
+
__END_DECLS
#endif /* _SYS_SIGNAL_H */
diff --git a/StdLib/Include/time.h b/StdLib/Include/time.h index a0ebbb9..ecef1e2 100644 --- a/StdLib/Include/time.h +++ b/StdLib/Include/time.h @@ -33,6 +33,40 @@ if Daylight Saving Time is not in effect, and negative if the information
is not available.
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL
+ CLOCKS_PER_SEC The number of values per second returned by the clock function.
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ clock_t Arithmetic type capable of representing a time from the clock function.
+ time_t Arithmetic type capable of representing a time.
+ struct tm Holds the components of a calendar time; or broken-down time.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+ @verbatim
+ ############### Time Manipulation Functions
+ clock_t clock (void);
+ double difftime (time_t time1, time_t time0);
+ time_t mktime (struct tm *timeptr);
+ time_t time (time_t *timer);
+
+ ################# Time Conversion Functions
+ char * asctime (const struct tm *timeptr);
+ char * ctime (const time_t *timer);
+ struct tm * gmtime (const time_t *timer);
+ time_t timegm (struct tm*);
+ struct tm * localtime (const time_t *timer);
+ size_t strftime (char * __restrict s, size_t maxsize,
+ const char * __restrict format,
+ const struct tm * __restrict timeptr);
+ char * strptime (const char *, const char * format, struct tm*);
+ @endverbatim
+
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
@@ -41,7 +75,6 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
**/
#ifndef _TIME_H
#define _TIME_H
@@ -55,26 +88,25 @@ #undef _BSD_SIZE_T_
#endif
-/** An arithmetic type capable of representing values returned by clock(); **/
#ifdef _EFI_CLOCK_T
+ /** An arithmetic type capable of representing values returned by clock(); **/
typedef _EFI_CLOCK_T clock_t;
#undef _EFI_CLOCK_T
#endif
-/** An arithmetic type capable of representing values returned as calendar time
- values, such as that returned by mktime();
-**/
#ifdef _EFI_TIME_T
+ /** An arithmetic type capable of representing values returned as calendar time
+ values, such as that returned by mktime();
+ **/
typedef _EFI_TIME_T time_t;
#undef _EFI_TIME_T
#endif
-/** Value added to tm_year to get the full year value. TM_YEAR_BASE + 110 --> 2010
-**/
+/** Value added to tm_year to get the full year value. TM_YEAR_BASE + 110 --> 2010 **/
#define TM_YEAR_BASE 1900
-/** Values for the tm_wday member of struct tm.
- @{
+/** @{
+ Values for the tm_wday member of struct tm.
**/
#define TM_SUNDAY 0
#define TM_MONDAY 1
@@ -83,10 +115,10 @@ #define TM_THURSDAY 4
#define TM_FRIDAY 5
#define TM_SATURDAY 6
-/** @} **/
+/*@}*/
-/** Values for the tm_mon member of struct tm.
- @{
+/** @{
+ Values for the tm_mon member of struct tm.
**/
#define TM_JANUARY 0
#define TM_FEBRUARY 1
@@ -100,7 +132,7 @@ #define TM_OCTOBER 9
#define TM_NOVEMBER 10
#define TM_DECEMBER 11
-/** @} **/
+/*@}*/
/** A structure holding the components of a calendar time, called the
broken-down time. The first nine (9) members are as mandated by the
@@ -133,17 +165,21 @@ struct tm { the macro CLOCKS_PER_SEC. If the processor time used is not
available or its value cannot be represented, the function
returns the value (clock_t)(-1).
-
- On IA32 or X64 platforms, the value returned is the number of
- CPU TimeStamp Counter ticks since the appliation started.
**/
clock_t clock(void);
-/**
+/** Compute the difference between two calendar times: time1 - time0.
+
+ @param[in] time1 An arithmetic calendar time.
+ @param[in] time2 Another arithmetic calendar time.
+
+ @return The difference between the two times expressed in seconds.
**/
double difftime(time_t time1, time_t time0);
-/** The mktime function converts the broken-down time, expressed as local time,
+/** Convert a broken-down time into an arithmetic calendar time.
+
+ The mktime function converts the broken-down time, expressed as local time,
in the structure pointed to by timeptr into a calendar time value with the
same encoding as that of the values returned by the time function. The
original values of the tm_wday and tm_yday components of the structure are
@@ -155,6 +191,8 @@ double difftime(time_t time1, time_t time0); the final value of tm_mday is not set until tm_mon and tm_year
are determined.
+ @param[in] timeptr Pointer to a broken-down time to be converted.
+
@return The mktime function returns the specified calendar time encoded
as a value of type time_t. If the calendar time cannot be
represented, the function returns the value (time_t)(-1).
@@ -163,7 +201,10 @@ time_t mktime(struct tm *timeptr); /** The time function determines the current calendar time.
- The encoding of the value is unspecified.
+ The encoding of the value is unspecified and undocumented.
+
+ @param[out] timer An optional pointer to an object in which to
+ store the calendar time.
@return The time function returns the implementation's best approximation
of the current calendar time. The value (time_t)(-1) is returned
@@ -176,23 +217,33 @@ time_t time(time_t *timer); /* ################# Time Conversion Functions ########################## */
/** The asctime function converts the broken-down time in the structure pointed
- to by timeptr into a string in the form
+ to by timeptr into a string in the form<BR>
+ @verbatim
Sun Sep 16 01:03:52 1973\n\0
+ @endverbatim
+
+ @param[in] timeptr A pointer to a broken-down time to convert.
@return The asctime function returns a pointer to the string.
**/
char * asctime(const struct tm *timeptr);
-/** The ctime function converts the calendar time pointed to by timer to local
+/** The ctime function converts the calendar time pointed to by timer to a local
time in the form of a string. It is equivalent to asctime(localtime(timer))
+ @param[in] timer Pointer to a calendar time value to convert into a
+ string representation.
+
@return The ctime function returns the pointer returned by the asctime
function with that broken-down time as argument.
**/
char * ctime(const time_t *timer);
/** The gmtime function converts the calendar time pointed to by timer into a
- brokendown time, expressed as UTC.
+ broken-down time, expressed as UTC.
+
+ @param[in] timer Pointer to a calendar time value to convert into a
+ broken-down time.
@return The gmtime function returns a pointer to the broken-down time,
or a null pointer if the specified time cannot be converted to UTC.
@@ -201,6 +252,9 @@ struct tm * gmtime(const time_t *timer); /** The timegm function is the opposite of gmtime.
+ @param[in] tm Pointer to a broken-down time to convert into a
+ calendar time.
+
@return The calendar time expressed as UTC.
**/
time_t timegm(struct tm*);
@@ -208,6 +262,8 @@ time_t timegm(struct tm*); /** The localtime function converts the calendar time pointed to by timer into
a broken-down time, expressed as local time.
+ @param[in] timer Pointer to a calendar time value to be converted.
+
@return The localtime function returns a pointer to the broken-down time,
or a null pointer if the specified time cannot be converted to
local time.
diff --git a/StdLib/Include/wchar.h b/StdLib/Include/wchar.h index bab02b0..d8e15ca 100644 --- a/StdLib/Include/wchar.h +++ b/StdLib/Include/wchar.h @@ -9,15 +9,155 @@ in this file causes copying to take place between objects that overlap, the
behavior is undefined.
- Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
+ The following macros are defined in this file:<BR>
+ @verbatim
+ NULL Actually defined in <sys/EfiCdefs.h>
+ WCHAR_MIN Minimum value of a wide char.
+ WCHAR_MAX Maximum value of a wide char.
+ WEOF Wide char version of end-of-file.
+ @endverbatim
+
+ The following types are defined in this file:<BR>
+ @verbatim
+ size_t Unsigned integer type of the result of the sizeof operator.
+ wchar_t Type of wide characters.
+ wint_t Type capable of holding all wchar_t values and WEOF.
+ mbstate_t Type of object holding multibyte conversion state.
+ struct tm Incomplete declaration of the broken-down time structure.
+ @endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### Formatted Input/Output Functions
+ int fwprintf (FILE * __restrict stream,
+ const wchar_t * __restrict format, ...);
+ int fwscanf (FILE * __restrict stream,
+ const wchar_t * __restrict format, ...);
+ int swprintf (wchar_t * __restrict s, size_t n,
+ const wchar_t * __restrict format, ...);
+ int swscanf (const wchar_t * __restrict s,
+ const wchar_t * __restrict format, ...);
+ int vfwprintf (FILE * __restrict stream,
+ const wchar_t * __restrict format, va_list arg);
+ int vfwscanf (FILE * __restrict stream,
+ const wchar_t * __restrict format, va_list arg);
+ int vswprintf (wchar_t * __restrict s, size_t n,
+ const wchar_t * __restrict format, va_list arg);
+ int vswscanf (const wchar_t * __restrict s,
+ const wchar_t * __restrict format, va_list arg);
+ int vwprintf (const wchar_t * __restrict format, va_list arg);
+ int vwscanf (const wchar_t * __restrict format, va_list arg);
+ int wprintf (const wchar_t * __restrict format, ...);
+ int wscanf (const wchar_t * __restrict format, ...);
+
+ ################### Input/Output Functions
+ wint_t fgetwc (FILE *stream);
+ wchar_t *fgetws (wchar_t * __restrict S, int n,
+ FILE * __restrict stream);
+ wint_t fputwc (wchar_t c, FILE *stream);
+ int fputws (const wchar_t * __restrict S,
+ FILE * __restrict stream);
+ int fwide (FILE *stream, int mode);
+ wint_t getwc (FILE *stream);
+ wint_t getwchar (void);
+ wint_t putwc (wchar_t c, FILE *stream);
+ wint_t putwchar (wchar_t c);
+ wint_t ungetwc (wint_t c, FILE *stream);
+
+ ################### Numeric Conversions
+ double wcstod (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ float wcstof (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ long double wcstold (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr);
+ long int wcstol (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ long long int wcstoll (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ unsigned long int wcstoul (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+ unsigned long long int wcstoull (const wchar_t * __restrict nptr,
+ wchar_t ** __restrict endptr, int base);
+
+ ####################### String Copying
+ wchar_t *wcscpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2);
+ wchar_t *wcsncpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ wchar_t *wmemcpy (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n);
+
+ ################### String Concatenation
+ wchar_t *wcscat (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2);
+ wchar_t *wcsncat (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+
+ ##################### String Comparison
+ int wcscmp (const wchar_t *s1, const wchar_t *s2);
+ int wcscoll (const wchar_t *s1, const wchar_t *s2);
+ int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n);
+ size_t wcsxfrm (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2, size_t n);
+ int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n);
+
+ ##################### String Searching
+ wchar_t *wcschr (const wchar_t *S, wchar_t c);
+ size_t wcscspn (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcsrchr (const wchar_t *S, wchar_t c);
+ size_t wcsspn (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);
+ wchar_t *wcstok (wchar_t * __restrict s1,
+ const wchar_t * __restrict s2,
+ wchar_t ** __restrict ptr);
+ wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n);
+
+ ################### String Manipulation
+ size_t wcslen (const wchar_t *S);
+ wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n);
+
+ ################# Date and Time Conversion
+ size_t wcsftime (wchar_t * __restrict S, size_t maxsize,
+ const wchar_t * __restrict format,
+ const struct tm * __restrict timeptr);
+
+ ############# Multibyte <--> Wide Character Conversion
+ wint_t btowc (int c);
+ int wctob (wint_t c);
+ int mbsinit (const mbstate_t *ps);
+
+ ####### Restartable Multibyte <--> Wide Character Conversion
+ size_t mbrlen (const char * __restrict S, size_t n,
+ mbstate_t * __restrict ps);
+ size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S,
+ size_t n, mbstate_t * __restrict ps);
+ size_t wcrtomb (char * __restrict S, wchar_t wc,
+ mbstate_t * __restrict ps);
+ size_t mbsrtowcs (wchar_t * __restrict dst,
+ const char ** __restrict src, size_t len,
+ mbstate_t * __restrict ps);
+ size_t wcsrtombs (char * __restrict dst,
+ const wchar_t ** __restrict src,
+ size_t len, mbstate_t * __restrict ps);
+@endverbatim
+
+ @note Properly constructed programs will take the following into consideration:
+ - wchar_t and wint_t may be the same integer type.
+ - WEOF might be a different value than that of EOF.
+ - WEOF might not be negative.
+ - mbstate_t objects are not intended to be inspected by programs.
+
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
the terms and conditions of the BSD License that accompanies this distribution.
The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
+ http://opensource.org/licenses/bsd-license.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
**/
#ifndef _WCHAR_H
#define _WCHAR_H
@@ -32,253 +172,974 @@ #endif
#ifdef _EFI_SIZE_T_
- typedef _EFI_SIZE_T_ size_t;
+ typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */
#undef _BSD_SIZE_T_
#undef _EFI_SIZE_T_
#endif
#ifndef __cplusplus
#ifdef _EFI_WCHAR_T
- typedef _EFI_WCHAR_T wchar_t;
+ /** An integer type capable of representing all distinct codes in the
+ UCS-2 encoding supported by UEFI.
+ **/
+ typedef _EFI_WCHAR_T wchar_t;
#undef _BSD_WCHAR_T_
#undef _EFI_WCHAR_T
#endif
#endif
-/* mbstate_t is an opaque object, that must not be an array type, used to keep
- conversion state during multibyte stream conversions.
- */
#ifdef _BSD_MBSTATE_T_
+ /** mbstate_t is an opaque object, that is not an array type, used to keep
+ conversion state during multibyte stream conversions.
+ */
typedef _BSD_MBSTATE_T_ mbstate_t;
#undef _BSD_MBSTATE_T_
#endif
-/* wint_t is an integer type unchanged by default argument promotions that can
- hold any value corresponding to members of the extended character set, as
- well as at least one value that does not correspond to any member of the
- extended character set: WEOF.
-*/
#ifdef _EFI_WINT_T
- typedef _EFI_WINT_T wint_t;
+ /** wint_t is an integer type unchanged by default argument promotions that can
+ hold any value corresponding to members of the extended character set, as
+ well as at least one value that does not correspond to any member of the
+ extended character set: WEOF.
+ */
+ typedef _EFI_WINT_T wint_t;
#undef _BSD_WINT_T_
#undef _EFI_WINT_T
#endif
-/* Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
- a maximum value defined by __USHRT_MAX (65535 on IA processors).
-*/
#ifndef WCHAR_MIN
- #define WCHAR_MIN 0
- #define WCHAR_MAX __USHRT_MAX
-#endif
-
-/* limits of wint_t */
-#ifndef WINT_MIN
- #define WINT_MIN _EFI_WINT_MIN /* wint_t */
- #define WINT_MAX _EFI_WINT_MAX /* wint_t */
+ /** @{
+ Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
+ a maximum value defined by __USHRT_MAX (65535 on IA processors).
+ */
+ #define WCHAR_MIN 0
+ #define WCHAR_MAX __USHRT_MAX
+ /*@}*/
#endif
-/* WEOF expands to a constant expression of type wint_t whose value does not
- correspond to any member of the extended character set. It is accepted
- (and returned) by several functions, declared in this file, to indicate
- end-of-file, that is, no more input from a stream. It is also used as a
- wide character value that does not correspond to any member of the
- extended character set.
-*/
#ifndef WEOF
+ /** WEOF expands to a constant expression of type wint_t whose value does not
+ correspond to any member of the extended character set. It is accepted
+ (and returned) by several functions, declared in this file, to indicate
+ end-of-file, that is, no more input from a stream. It is also used as a
+ wide character value that does not correspond to any member of the
+ extended character set.
+ */
#define WEOF ((wint_t)-1)
#endif
-/* tm is declared here as an incomplete structure type. The full structure
- declaration is in <time.h>.
+/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
+#ifndef WINT_MIN
+ #define WINT_MIN _EFI_WINT_MIN /* wint_t */
+ #define WINT_MAX _EFI_WINT_MAX /* wint_t */
+#endif
+
+/** Type struct tm is declared here as an incomplete structure type for use as an argument
+ type by the wcsftime function. The full structure declaration is in <time.h>.
*/
struct tm;
/* ############### Formatted Input/Output Functions ##################### */
-/**
-The fwprintf function writes output to the stream pointed to by stream, under
-control of the wide string pointed to by format that specifies how subsequent arguments
-are converted for output. If there are insufficient arguments for the format, the behavior
-is undefined. If the format is exhausted while arguments remain, the excess arguments
-are evaluated (as always) but are otherwise ignored. The fwprintf function returns
-when the end of the format string is encountered.
-
-The fwprintf function returns the number of wide characters transmitted, or a negative
-value if an output or encoding error occurred.
+/** The fwprintf function writes output to the stream pointed to by stream,
+ under control of the wide string pointed to by format that specifies how
+ subsequent arguments are converted for output. If there are insufficient
+ arguments for the format, the behavior is undefined. If the format is
+ exhausted while arguments remain, the excess arguments are evaluated
+ (as always) but are otherwise ignored. The fwprintf function returns
+ when the end of the format string is encountered.
+
+ The format is composed of zero or more directives: ordinary wide characters
+ (not %), which are copied unchanged to the output stream; and conversion
+ specifications, each of which results in fetching zero or more subsequent
+ arguments, converting them, if applicable, according to the corresponding
+ conversion specifier, and then writing the result to the output stream.
+
+ Each conversion specification is introduced by the wide character %. After
+ the %, the following appear in sequence:
+ * Zero or more flags (in any order) that modify the meaning of the
+ conversion specification.
+ * An optional minimum field width. If the converted value has fewer wide
+ characters than the field width, it is padded with spaces (by default)
+ on the left (or right, if the left adjustment flag, described later,
+ has been given) to the field width. The field width takes the form of
+ an asterisk * (described later) or a nonnegative decimal integer.
+ * An optional precision that gives the minimum number of digits to appear
+ for the d, i, o, u, x, and X conversions, the number of digits to
+ appear after the decimal-point wide character for e, E, f, and F
+ conversions, the maximum number of significant digits for the g and G
+ conversions, or the maximum number of wide characters to be written
+ for s conversions. The precision takes the form of a period (.)
+ followed either by an asterisk * (described later) or by an optional
+ decimal integer; if only the period is specified, the precision is
+ taken as zero. If a precision appears with any other conversion
+ specifier, the behavior is undefined.
+ * An optional length modifier that specifies the size of the argument.
+ * A conversion specifier wide character that specifies the type of
+ conversion to be applied.
+
+ As noted above, a field width, or precision, or both, may be indicated by
+ an asterisk. In this case, an int argument supplies the field width or
+ precision. The arguments specifying field width, or precision, or both,
+ must appear (in that order) before the argument (if any) to be converted.
+ A negative field width argument is taken as a - flag followed by a positive
+ field width. A negative precision argument is taken as if the precision
+ were omitted.
+
+ The flag wide characters and their meanings are:<BR>
+ - The result of the conversion is left-justified within the field.
+ (It is right-justified if this flag is not specified.)
+ + The result of a signed conversion always begins with a plus or minus
+ sign. (It begins with a sign only when a negative value is converted
+ if this flag is not specified.)
+ space If the first wide character of a signed conversion is not a sign, or
+ if a signed conversion results in no wide characters, a space is
+ prefixed to the result. If the space and + flags both appear, the
+ space flag is ignored.
+ # The result is converted to an "alternative form". For o conversion,
+ it increases the precision, if and only if necessary, to force the
+ first digit of the result to be a zero (if the value and precision
+ are both 0, a single 0 is printed). For x (or X) conversion, a
+ nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
+ and G conversions, the result of converting a floating-point number
+ always contains a decimal-point wide character, even if no digits
+ follow it. (Normally, a decimal-point wide character appears in the
+ result of these conversions only if a digit follows it.) For g and G
+ conversions, trailing zeros are not removed from the result. For
+ other conversions, the behavior is undefined.
+ 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
+ (following any indication of sign or base) are used to pad to the
+ field width rather than performing space padding, except when
+ converting an infinity or NaN. If the 0 and - flags both appear,
+ the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
+ precision is specified, the 0 flag is ignored. For other conversions,
+ the behavior is undefined.
+
+ The length modifiers and their meanings are:<BR>
+ hh Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a signed char or unsigned char argument (the argument
+ will have been promoted according to the integer promotions, but its
+ value shall be converted to signed char or unsigned char before
+ printing); or that a following n conversion specifier applies to a
+ pointer to a signed char argument.
+ h Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a short int or unsigned short int argument (the argument
+ will have been promoted according to the integer promotions, but its
+ value shall be converted to short int or unsigned short int before
+ printing); or that a following n conversion specifier applies to a
+ pointer to a short int argument.
+ l (ell) Specifies that a following d, i, o, u, x, or X conversion
+ specifier applies to a long int or unsigned long int argument;
+ that a following n conversion specifier applies to a pointer to a
+ long int argument; that a following c conversion specifier
+ applies to a wint_t argument; that a following s conversion
+ specifier applies to a pointer to a wchar_t argument; or has no
+ effect on a following e, E, f, F, g, or G conversion specifier.
+ ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
+ specifier applies to a long long int or unsigned long long int
+ argument; or that a following n conversion specifier applies
+ to a pointer to a long long int argument.
+ j Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to an intmax_t or uintmax_t argument; or that a following
+ n conversion specifier applies to a pointer to an intmax_t argument.
+ z Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a size_t or the corresponding signed integer type
+ argument; or that a following n conversion specifier applies to a
+ pointer to a signed integer type corresponding to size_t argument.
+ t Specifies that a following d, i, o, u, x, or X conversion specifier
+ applies to a ptrdiff_t or the corresponding unsigned integer type
+ argument; or that a following n conversion specifier applies to a
+ pointer to a ptrdiff_t argument.
+ L Specifies that a following a, A, e, E, f, F, g, or G conversion
+ specifier applies to a long double argument.
+
+ If a length modifier appears with any conversion specifier other than as
+ specified above, the behavior is undefined.
+
+ The conversion specifiers and their meanings are:<BR>
+ d,i The int argument is converted to signed decimal in the
+ style [-]dddd. The precision specifies the minimum number of digits
+ to appear; if the value being converted can be represented in fewer
+ digits, it is expanded with leading zeros. The default precision
+ is 1. The result of converting a zero value with a precision of
+ zero is no wide characters.
+ o,u,x,X The unsigned int argument is converted to unsigned octal (o),
+ unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
+ the style dddd; the letters abcdef are used for x conversion and
+ the letters ABCDEF for X conversion. The precision specifies the
+ minimum number of digits to appear; if the value being converted
+ can be represented in fewer digits, it is expanded with leading
+ zeros. The default precision is 1. The result of converting a zero
+ value with a precision of zero is no wide characters.
+ f,F A double argument representing a floating-point number is converted
+ to decimal notation in the style [-]ddd.ddd, where the number of
+ digits after the decimal-point wide character is equal to the
+ precision specification. If the precision is missing, it is taken
+ as 6; if the precision is zero and the # flag is not specified, no
+ decimal-point wide character appears. If a decimal-point wide
+ character appears, at least one digit appears before it. The value
+ is rounded to the appropriate number of digits.<BR>
+ A double argument representing an infinity is converted to [-]inf.
+ A double argument representing a NaN is converted to [-]nan.
+ The F conversion specifier produces INF or NAN instead
+ of inf or nan, respectively.
+ e,E A double argument representing a floating-point number is converted
+ in the style [-]d.ddd e +/- dd, where there is one digit (which is
+ nonzero if the argument is nonzero) before the decimal-point wide
+ character and the number of digits after it is equal to the
+ precision; if the precision is missing, it is taken as 6; if the
+ precision is zero and the # flag is not specified, no decimal-point
+ wide character appears. The value is rounded to the appropriate
+ number of digits. The E conversion specifier produces a number with
+ E instead of e introducing the exponent. The exponent always
+ contains at least two digits, and only as many more digits as
+ necessary to represent the exponent. If the value is zero, the
+ exponent is zero. A double argument representing an infinity or NaN
+ is converted in the style of an f or F conversion specifier.
+ g,G A double argument representing a floating-point number is converted
+ in style f or e (or in style F or E in the case of a G conversion
+ specifier), depending on the value converted and the precision.
+ Let P equal the precision if nonzero, 6 if the precision is
+ omitted, or 1 if the precision is zero. Then, if a conversion with
+ style E would have an exponent of X:
+ - if P > X = -4, the conversion is with style f (or F) and
+ precision P - (X + 1).
+ - otherwise, the conversion is with style e (or E) and
+ precision P - 1.
+ Finally, unless the # flag is used, any trailing zeros are removed
+ from the fractional portion of the result and the decimal-point
+ wide character is removed if there is no fractional portion
+ remaining. A double argument representing an infinity or NaN is
+ converted in the style of an f or F conversion specifier.
+ c If no l length modifier is present, the int argument is converted
+ to a wide character as if by calling btowc and the resulting wide
+ character is written. If an l length modifier is present, the
+ wint_t argument is converted to wchar_t and written.
+ s If no l length modifier is present, the argument shall be a pointer
+ to the initial element of a character array containing a multibyte
+ character sequence beginning in the initial shift state. Characters
+ from the array are converted as if by repeated calls to the mbrtowc
+ function, with the conversion state described by an mbstate_t
+ object initialized to zero before the first multibyte character is
+ converted, and written up to (but not including) the terminating
+ null wide character. If the precision is specified, no more than
+ that many wide characters are written. If the precision is not
+ specified or is greater than the size of the converted array, the
+ converted array shall contain a null wide character.<BR>
+ If an l length modifier is present, the argument shall be a pointer
+ to the initial element of an array of wchar_t type. Wide characters
+ from the array are written up to (but not including) a terminating
+ null wide character. If the precision is specified, no more than
+ that many wide characters are written. If the precision is not
+ specified or is greater than the size of the array, the array
+ shall contain a null wide character.
+ p The argument shall be a pointer to void. The value of the pointer
+ is converted to a sequence of printing wide characters, in an
+ implementation-defined manner.
+ n The argument shall be a pointer to signed integer into which is
+ written the number of wide characters written to the output stream
+ so far by this call to fwprintf. No argument is converted, but one
+ is consumed. If the conversion specification includes any flags, a
+ field width, or a precision, the behavior is undefined.
+ % A % wide character is written. No argument is converted. The
+ complete conversion specification is %%.
+
+
+ @param[in] stream An open File specifier to which the output is sent.
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments.
+ @param ... Variable number of parameters as required by format.
+
+ @return The fwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
**/
int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-/**
-The fwscanf function reads input from the stream pointed to by stream, under
-control of the wide string pointed to by format that specifies the admissible input
-sequences and how they are to be converted for assignment, using subsequent arguments
-as pointers to the objects to receive the converted input. If there are insufficient
-arguments for the format, the behavior is undefined. If the format is exhausted while
-arguments remain, the excess arguments are evaluated (as always) but are otherwise
-ignored.
-
-The fwscanf function returns the value of the macro EOF if an input failure occurs
-before any conversion. Otherwise, the function returns the number of input items
-assigned, which can be fewer than provided for, or even zero, in the event of an early
-matching failure.
+/** The fwscanf function reads input from the stream pointed to by stream,
+ under control of the wide string pointed to by format that specifies
+ the admissible input sequences and how they are to be converted for
+ assignment, using subsequent arguments as pointers to the objects to
+ receive the converted input. If there are insufficient arguments for
+ the format, the behavior is undefined. If the format is exhausted while
+ arguments remain, the excess arguments are evaluated (as always) but are
+ otherwise ignored.
+
+ The format is composed of zero or more directives: one or more white-space
+ wide characters, an ordinary wide character (neither % nor a white-space
+ wide character), or a conversion specification. Each conversion
+ specification is introduced by the wide character %. After the %, the
+ following appear in sequence:
+ - An optional assignment-suppressing wide character *.
+ - An optional decimal integer greater than zero that specifies the
+ maximum field width (in wide characters).
+ - An optional length modifier that specifies the size of the receiving object.
+ - A conversion specifier wide character that specifies the type of
+ conversion to be applied.
+
+ The fwscanf function executes each directive of the format in turn. If a
+ directive fails, as detailed below, the function returns. Failures are
+ described as input failures (due to the occurrence of an encoding error
+ or the unavailability of input characters), or matching failures
+ (due to inappropriate input).
+
+ A directive composed of white-space wide character(s) is executed by
+ reading input up to the first non-white-space wide character (which remains
+ unread), or until no more wide characters can be read.
+
+ A directive that is an ordinary wide character is executed by reading the
+ next wide character of the stream. If that wide character differs from the
+ directive, the directive fails and the differing and subsequent wide
+ characters remain unread. Similarly, if end-of-file, an encoding error, or
+ a read error prevents a wide character from being read, the directive fails.
+
+ A directive that is a conversion specification defines a set of matching
+ input sequences, as described below for each specifier. A conversion
+ specification is executed in the following steps:
+ - Input white-space wide characters (as specified by the iswspace
+ function) are skipped, unless the specification includes
+ a [, c, or n specifier.
+ - An input item is read from the stream, unless the specification
+ includes an n specifier. An input item is defined as the longest
+ sequence of input wide characters which does not exceed any specified
+ field width and which is, or is a prefix of, a matching input sequence.
+ The first wide character, if any, after the input item remains unread.
+ If the length of the input item is zero, the execution of the directive
+ fails; this condition is a matching failure unless end-of-file, an
+ encoding error, or a read error prevented input from the stream, in
+ which case it is an input failure.
+ - Except in the case of a % specifier, the input item (or, in the case of
+ a %n directive, the count of input wide characters) is converted to a
+ type appropriate to the conversion specifier. If the input item is not
+ a matching sequence, the execution of the directive fails: this
+ condition is a matching failure. Unless assignment suppression was
+ indicated by a *, the result of the conversion is placed in the object
+ pointed to by the first argument following the format argument that has
+ not already received a conversion result. If this object does not have
+ an appropriate type, or if the result of the conversion cannot be
+ represented in the object, the behavior is undefined.
+
+ The length modifiers and their meanings are:<BR>
+ hh Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to signed char
+ or unsigned char.
+ h Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to short int
+ or unsigned short int.
+ l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to long int or
+ unsigned long int; that a following e, E, f, F, g, or G conversion
+ specifier applies to an argument with type pointer to double; or
+ that a following c, s, or [ conversion specifier applies to an
+ argument with type pointer to wchar_t.
+ ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type
+ pointer to long long int or unsigned long long int.
+ j Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to intmax_t
+ or uintmax_t.
+ z Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to size_t or the
+ corresponding signed integer type.
+ t Specifies that a following d, i, o, u, x, X, or n conversion
+ specifier applies to an argument with type pointer to ptrdiff_t or
+ the corresponding unsigned integer type.
+ L Specifies that a following e, E, f, F, g, or G conversion specifier
+ applies to an argument with type pointer to long double.
+
+ If a length modifier appears with any conversion specifier other than as
+ specified above, the behavior is undefined.
+
+ The conversion specifiers and their meanings are:<BR>
+ d Matches an optionally signed decimal integer, whose format is the
+ same as expected for the subject sequence of the wcstol function
+ with the value 10 for the base argument. The corresponding argument
+ shall be a pointer to signed integer.
+ i Matches an optionally signed integer, whose format is the same as
+ expected for the subject sequence of the wcstol function with the
+ value 0 for the base argument. The corresponding argument shall be
+ a pointer to signed integer.
+ o Matches an optionally signed octal integer, whose format is the
+ same as expected for the subject sequence of the wcstoul function
+ with the value 8 for the base argument. The corresponding argument
+ shall be a pointer to unsigned integer.
+ u Matches an optionally signed decimal integer, whose format is the
+ same as expected for the subject sequence of the wcstoul function
+ with the value 10 for the base argument. The corresponding argument
+ shall be a pointer to unsigned integer.
+ x Matches an optionally signed hexadecimal integer, whose format is
+ the same as expected for the subject sequence of the wcstoul
+ function with the value 16 for the base argument. The corresponding
+ argument shall be a pointer to unsigned integer.
+ e,f,g Matches an optionally signed floating-point number, infinity, or
+ NaN, whose format is the same as expected for the subject sequence
+ of the wcstod function. The corresponding argument shall be a
+ pointer to float.
+ c Matches a sequence of wide characters of exactly the number
+ specified by the field width (1 if no field width is present in the
+ directive).<BR>
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence. No null
+ character is added.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of
+ wchar_t large enough to accept the sequence.
+ No null wide character is added.
+ s Matches a sequence of non-white-space wide characters.
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence and a
+ terminating null character, which will be added automatically.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of wchar_t
+ large enough to accept the sequence and the terminating null wide
+ character, which will be added automatically.
+ [ Matches a nonempty sequence of wide characters from a set of
+ expected characters (the scanset).<BR>
+ If no l length modifier is present, characters from the input field
+ are converted as if by repeated calls to the wcrtomb function, with
+ the conversion state described by an mbstate_t object initialized
+ to zero before the first wide character is converted. The
+ corresponding argument shall be a pointer to the initial element of
+ a character array large enough to accept the sequence and a
+ terminating null character, which will be added automatically.<BR>
+ If an l length modifier is present, the corresponding argument
+ shall be a pointer to the initial element of an array of wchar_t
+ large enough to accept the sequence and the terminating null wide
+ character, which will be added automatically.<BR>
+ The conversion specifier includes all subsequent wide characters
+ in the format string, up to and including the matching right
+ bracket (]). The wide characters between the brackets
+ (the scanlist) compose the scanset, unless the wide character after
+ the left bracket is a circumflex (^), in which case the scanset
+ contains all wide characters that do not appear in the scanlist
+ between the circumflex and the right bracket. If the conversion
+ specifier begins with [] or [^], the right bracket wide character
+ is in the scanlist and the next following right bracket wide
+ character is the matching right bracket that ends the specification;
+ otherwise the first following right bracket wide character is the
+ one that ends the specification. If a - wide character is in the
+ scanlist and is not the first, nor the second where the first wide
+ character is a ^, nor the last character,
+ the - is added to the scanset.
+ p Matches the set of sequences produced by the %p conversion of the
+ fwprintf function. The corresponding argument is a pointer to a
+ pointer to void. The input item is converted to a pointer value. If
+ the input item is a value converted earlier during the same program
+ execution, the pointer that results will compare equal to that
+ value.
+ n No input is consumed. The corresponding argument is a pointer to
+ signed integer into which is to be written the number of wide
+ characters read from the input stream so far by this call to the
+ fwscanf function. Execution of a %n directive does not increment
+ the assignment count returned at the completion of execution of the
+ fwscanf function. No argument is converted, but one is consumed.
+ % Matches a single % wide character; no conversion or assignment
+ occurs. The complete conversion specification shall be %%.
+
+ The conversion specifiers E, F, G, and X are also valid and behave the same
+ as, respectively, e, f, g, and x.
+
+ Trailing white space (including new-line wide characters) is left unread
+ unless matched by a directive. The success of literal matches and
+ suppressed assignments is not directly determinable other than via
+ the %n directive.
+
+ @param[in] stream An open File specifier from which the input is read.
+ @param[in] format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The fwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ function returns the number of input items assigned, which can be
+ fewer than provided for, or even zero, in the event of an early
+ matching failure.
**/
int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);
-/**
-The swprintf function is equivalent to fwprintf, except that the argument s
-specifies an array of wide characters into which the generated output is to be written,
-rather than written to a stream. No more than n wide characters are written, including a
-terminating null wide character, which is always added (unless n is zero).
-
-The swprintf function returns the number of wide characters written in the array, not
-counting the terminating null wide character, or a neg ative value if an encoding error
-occurred or if n or more wide characters were requested to be written.
+/** Formatted wide-character output to a buffer.
+
+ The swprintf function is equivalent to fwprintf, except that the argument s
+ specifies an array of wide characters into which the generated output is to
+ be written, rather than written to a stream. No more than n wide characters
+ are written, including a terminating null wide character, which is always
+ added (unless n is zero).
+
+ @param[out] s A pointer to the array to receive the formatted output.
+ @param[in] n Maximum number of characters to write into buffer s.
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments. Copied and
+ converted characters are written to the array pointed
+ to by s.
+ @param ... Variable number of parameters as required by format.
+
+ @return The swprintf function returns the number of wide characters
+ written in the array, not counting the terminating null wide
+ character, or a negative value if an encoding error occurred or
+ if n or more wide characters were requested to be written.
**/
int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);
-/**
+/** Formatted wide input from a string.
+
+ The swscanf function is equivalent to fwscanf, except that the argument
+ Buff specifies a wide string from which the input is to be obtained, rather
+ than from a stream. Reaching the end of the wide string is equivalent to
+ encountering end-of-file for the fwscanf function.
+
+ @param[in] Buff Pointer to the string from which to obtain input.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The swscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ swscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int swscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, ...);
-
-/**
+int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);
+
+/** Print formatted values from an argument list.
+
+The vfwprintf function is equivalent to fwprintf, with the variable argument list
+replaced by Args, which shall have been initialized by the va_start macro (and
+possibly subsequent va_arg calls). The vfwprintf function does not invoke the
+va_end macro.
+
+ @param[in] Stream The output stream to receive the formatted output.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vfwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding
+ error occurred.
**/
-int vfwprintf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input from a stream.
+
+ The vfwscanf function is equivalent to fwscanf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro (and possibly subsequent va_arg calls). The vfwscanf function does
+ not invoke the va_end macro.
+
+ @param[in] Stream The input stream.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vfwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vfwscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vfwscanf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted print, to a buffer, from an argument list.
+
+ The vswprintf function is equivalent to swprintf, with the variable
+ argument list replaced by Args, which must have been initialized by the
+ va_start macro (and possibly subsequent va_arg calls). The vswprintf
+ function does not invoke the va_end macro.
+
+ @param[in] S A pointer to the array to receive the formatted output.
+ @param[in] N Maximum number of characters to write into array S.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[in] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vswprintf function returns the number of wide characters
+ written in the array, not counting the terminating null wide
+ character, or a neg ative value if an encoding error occurred or
+ if n or more wide characters were requested to be generated.
**/
-int vswprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, va_list arg);
-
-/**
+int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input from a string, using an argument list.
+
+ The vswscanf function is equivalent to swscanf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro. The vswscanf function does not invoke the va_end macro.
+
+ @param[in] S Pointer to the string from which to obtain input.
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vswscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vswscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vswscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, va_list arg);
+int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);
-/**
-**/
-int vwprintf(const wchar_t * __restrict format, va_list arg);
+/** Formatted print, to stdout, from an argument list.
-/**
+ The vwprintf function is equivalent to wprintf, with the variable argument
+ list replaced by Args, which must have been initialized by the va_start
+ macro. The vwprintf function does not invoke the va_end macro.
+
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vwprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
+**/
+int vwprintf(const wchar_t * __restrict Format, va_list Args);
+
+/** Formatted input, from stdin, to an argument list.
+
+ The vwscanf function is equivalent to wscanf, with the variable argument
+ list replaced by arg, which shall have been initialized by the va_start
+ macro. The vwscanf function does not invoke the va_end macro.
+
+ @param[in] Format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments.
+ @param[out] Args A list of arguments, initialized by the va_start macro
+ and accessed using the va_arg macro, used to satisfy
+ the directives in the Format string.
+
+ @return The vwscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ vwscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
-int vwscanf(const wchar_t * __restrict format, va_list arg);
+int vwscanf(const wchar_t * __restrict Format, va_list Args);
-/**
+/** Formatted print to stdout.
+
+ The wprintf function is equivalent to fwprintf with the argument stdout
+ specifying the output stream.
+
+ @param[in] format A wide character sequence containing characters
+ to be copied unchanged, and conversion specifiers
+ which convert their associated arguments.
+ @param ... Variable number of parameters as required by format.
+
+ @return The wprintf function returns the number of wide characters
+ transmitted, or a negative value if an output or encoding error
+ occurred.
**/
-int wprintf(const wchar_t * __restrict format, ...);
+int wprintf(const wchar_t * __restrict Format, ...);
-/**
+/** Formatted input from stdin.
+
+ The wscanf function is equivalent to fwscanf with the argument stdin
+ specifying the input stream.
+
+ @param[in] format A wide character sequence containing characters
+ to be matched against, and conversion specifiers
+ which convert their associated arguments. Converted
+ items are stored according to their associated arguments.
+ @param ... Variable number of parameters, as required by format,
+ specifying the objects to receive the converted input.
+
+ @return The wscanf function returns the value of the macro EOF if an
+ input failure occurs before any conversion. Otherwise, the
+ wscanf function returns the number of input items assigned,
+ which can be fewer than provided for, or even zero, in the event
+ of an early matching failure.
**/
int wscanf(const wchar_t * __restrict format, ...);
/* ################### Input/Output Functions ########################### */
-/**
-**/
-wint_t fgetwc(FILE *stream);
+/** Get a character from an input Stream.
-/**
+If the end-of-file indicator for the input stream pointed to by stream is not set and a
+next wide character is present, the fgetwc function obtains that wide character as a
+wchar_t converted to a wint_t and advances the associated file position indicator for
+the stream (if defined).
+
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
+file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
+the fgetwc function returns the next wide character from the input stream pointed to by
+stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
+function returns WEOF. If an encoding error occurs (including too few bytes), the value of
+the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
**/
-wchar_t *fgetws(wchar_t * __restrict s, int n, FILE * __restrict stream);
+wint_t fgetwc(FILE *Stream);
+
+/** Read a string from an input stream into a buffer.
+
+ The fgetws function reads at most one less than the number of
+ wide characters specified by n from the stream pointed to by
+ stream into the array pointed to by s. No additional wide
+ characters are read after a new-line wide character (which is
+ retained) or after end-of-file. A null wide character is written
+ immediately after the last wide character read into the array.
+
+ @param[out] S A pointer to the array to receive the input string.
+ @param[in] Limit The maximum number of characters to put into Buff,
+ including the terminating null character.
+ @param[in] Stream An input stream from which to obtain a character.
+
+ @return The fgetws function returns S if successful. If end-of-file is
+ encountered and no characters have been read into the array, the
+ contents of the array remain unchanged and a null pointer is
+ returned. If a read or encoding error occurs during the
+ operation, the array contents are indeterminate and a
+ null pointer is returned.
+**/
+wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);
-/**
+/** Write a character to an output stream.
+
+The fputwc function writes the wide character specified by c to the output stream
+pointed to by stream, at the position indicated by the associated file position indicator
+for the stream (if defined), and advances the indicator appropriately. If the file cannot
+support positioning requests, or if the stream was opened with append mode, the
+character is appended to the output stream.
+
+ @param[in] C The character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The fputwc function returns the wide character written. If a write error occurs, the
+error indicator for the stream is set and fputwc returns WEOF. If an encoding error
+occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
**/
-wint_t fputwc(wchar_t c, FILE *stream);
+wint_t fputwc(wchar_t C, FILE *Stream);
-/**
+/** Write a string to an output stream.
+
+The fputws function writes the wide string pointed to by S to the stream pointed to by
+Stream. The terminating null wide character is not written.
+
+ @param[in] String The character string to be written to Stream.
+ @param[in] Stream The output stream that String is to be written to.
+
+ @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it
+returns a nonnegative value.
**/
-int fputws(const wchar_t * __restrict s, FILE * __restrict stream);
+int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);
-/**
+/** Query or set a stream's orientation.
+
+The fwide function determines the orientation of the stream pointed to by stream. If
+Mode is greater than zero, the function first attempts to make the stream wide oriented. If
+Mode is less than zero, the function first attempts to make the stream byte oriented.
+Otherwise, Mode is zero and the function does not alter the orientation of the stream.
+
+ @param[in] Stream The stream to be queried.
+ @param[in] Mode Control value selecting between quering or setting
+ the Stream's orientation.
+ @return The fwide function returns a value greater than zero if, after the call, the stream has
+wide orientation, a value less than zero if the stream has byte orientation, or zero if the
+stream has no orientation.
**/
-int fwide(FILE *stream, int mode);
+int fwide(FILE *Stream, int Mode);
-/**
+/** Get a character from an input stream.
+
+The getwc function is equivalent to fgetwc, except that if it is implemented as a
+macro, it may evaluate Stream more than once, so the argument should never be an
+expression with side effects.
+
+ @param[in] Stream The stream to be read.
+
+ @return The getwc function returns the next wide character from the input stream pointed to by
+stream, or WEOF.
**/
-wint_t getwc(FILE *stream);
+wint_t getwc(FILE *Stream);
-/**
+/** Get a character from stdin.
+
+ The getwchar function is equivalent to getwc with the argument stdin.
+
+ @return The getwchar function returns the next wide character from the
+ input stream pointed to by stdin, or WEOF.
**/
wint_t getwchar(void);
-/**
-**/
-wint_t putwc(wchar_t c, FILE *stream);
+/** Write a character to an output stream.
-/**
-**/
-wint_t putwchar(wchar_t c);
+The putwc function is equivalent to fputwc, except that if it is implemented as a
+macro, it may evaluate Stream more than once, so the Stream argument should never be an
+expression with side effects.
-/**
+ @param[in] C The wide character to be written to Stream.
+ @param[in] Stream The output stream that C is to be written to.
+
+ @return The putwc function returns the wide character written, or WEOF.
**/
-wint_t ungetwc(wint_t c, FILE *stream);
+wint_t putwc(wchar_t C, FILE *Stream);
-/* ################### Numeric Conversions ########################### */
+/** Write a character to stdout.
-/**
-**/
-double wcstod(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
+The putwchar function is equivalent to putwc with the second argument stdout.
-/**
-**/
-float wcstof(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
+ @param[in] C The wide character to be written to stdout.
-/**
+ @return The putwchar function returns the character written, or WEOF.
**/
-long double wcstold(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);
-
-/**
+wint_t putwchar(wchar_t C);
+
+/** Return a character to the input Stream as if it had not been read.
+
+The ungetwc function pushes the wide character specified by C back onto the input
+stream pointed to by Stream. Pushed-back wide characters will be returned by
+subsequent reads on that stream in the reverse order of their pushing. A successful
+intervening call (with the stream pointed to by Stream) to a file positioning function
+(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
+stream. The external storage corresponding to the stream is unchanged.
+
+One wide character of pushback is guaranteed, even if the call to the ungetwc function
+follows just after a call to a formatted wide character input function fwscanf,
+vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
+on the same stream without an intervening read or file positioning operation on that
+stream, the operation may fail.
+
+If the value of C equals that of the macro WEOF, the operation fails and the input stream is
+unchanged.
+
+A successful call to the ungetwc function clears the end-of-file indicator for the stream.
+The value of the file position indicator for the stream after reading or discarding all
+pushed-back wide characters is the same as it was before the wide characters were pushed
+back. For a text or binary stream, the value of its file position indicator after a successful
+call to the ungetwc function is unspecified until all pushed-back wide characters are
+read or discarded.
+
+ @param[in] C The wide character to push back onto the Stream.
+ @param[in] Stream The output stream that C is to be pushed back onto.
+
+ @return The ungetwc function returns the character pushed back,
+ or WEOF if the operation fails.
**/
-long int wcstol( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+wint_t ungetwc(wint_t C, FILE *Stream);
-/**
-**/
-long long int wcstoll( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+/* ################### Numeric Conversions ########################### */
-/**
+/** @{
+The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
+string pointed to by nptr to double, float, and long double representation,
+respectively. First, they decompose the input string into three parts: an initial, possibly
+empty, sequence of white-space wide characters (as specified by the iswspace
+function), a subject sequence resembling a floating-point constant or representing an
+infinity or NaN; and a final wide string of one or more unrecognized wide characters,
+including the terminating null wide character of the input wide string. Then, they attempt
+to convert the subject sequence to a floating-point number, and return the result.
+
+ @param[in] Nptr Pointer to the string to convert to a floating-point value.
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer
+ to the final wide string.
+
+The functions return the converted value, if any. If no conversion could be performed,
+zero is returned. If the correct value is outside the range of representable values, plus or
+minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
+type and sign of the value), and the value of the macro ERANGE is stored in errno. If
+the result underflows (7.12.1), the functions return a value whose magnitude is no greater
+than the smallest normalized positive number in the return type. A pointer to the
+final wide string is stored in the object pointed to by endptr, provided that endptr is
+not a null pointer.
**/
-unsigned long int wcstoul( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
-
-/**
+double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
+/*@}*/
+
+/** @{
+The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
+portion of the wide string pointed to by nptr to long int, long long int,
+unsigned long int, and unsigned long long int representation,
+respectively. First, they decompose the input string into three parts: an initial, possibly
+empty, sequence of white-space wide characters (as specified by the iswspace
+function), a subject sequence resembling an integer represented in some radix determined
+by the value of base, and a final wide string of one or more unrecognized wide
+characters, including the terminating null wide character of the input wide string. Then,
+they attempt to convert the subject sequence to an integer, and return the result.
+
+ @param[in] Nptr Pointer to the string to convert to a floating-point value.
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer
+ to the final wide string.
+ @param[in] Base Base, 0 to 36, of the value represented by the string
+ pointed to by Nptr.
+
+ @return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
+value, if any. If no conversion could be performed, zero is returned. If the correct value
+is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
+LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
+sign of the value, if any), and the value of the macro ERANGE is stored in errno.
**/
-unsigned long long int wcstoull( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);
+long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
+/*@}*/
/* ####################### String Copying ############################### */
-/** The wcscpy function copies the wide string pointed to by s2 (including the
- terminating null wide character) into the array pointed to by s1.
+/** The wcscpy function copies the wide string pointed to by Src (including the
+ terminating null wide character) into the array pointed to by Dest.
- @return The wcscpy function returns the value of s1.
+ @return The wcscpy function returns the value of Dest.
**/
-wchar_t *wcscpy(wchar_t * __restrict s1, const wchar_t * __restrict s2);
+wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** The wcsncpy function copies not more than n wide characters (those that
follow a null wide character are not copied) from the array pointed to by
- s2 to the array pointed to by s1.
+ Src to the array pointed to by Dest.
- If the array pointed to by s2 is a wide string that is shorter than n wide
+ If the array pointed to by Src is a wide string that is shorter than n wide
characters, null wide characters are appended to the copy in the array
- pointed to by s1, until n wide characters in all have been written.
+ pointed to by Dest, until n wide characters in all have been written.
- @return The wcsncpy function returns the value of s1.
+ @return The wcsncpy function returns the value of Dest.
**/
-wchar_t *wcsncpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemcpy function copies n wide characters from the object pointed to by
- s2 to the object pointed to by s1.
+ Src to the object pointed to by Dest.
- Use this function if you know that s1 and s2 DO NOT Overlap. Otherwise,
+ Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,
use wmemmove.
- @return The wmemcpy function returns the value of s1.
+ @return The wmemcpy function returns the value of Dest.
**/
-wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/** The wmemmove function copies n wide characters from the object pointed to by
- s2 to the object pointed to by s1. The objects pointed to by s1 and s2 are
+ Src to the object pointed to by Dest. The objects pointed to by Dest and Src are
allowed to overlap.
Because the UEFI BaseMemoryLib function CopyMem explicitly handles
@@ -286,33 +1147,33 @@ wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t implemented identically.
For programming clarity, it is recommended that you use wmemcpy if you know
- that s1 and s2 DO NOT Overlap. If s1 and s2 might possibly overlap, then
+ that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then
use wmemmove.
- @return The wmemmove function returns the value of s1.
+ @return The wmemmove function returns the value of Dest.
**/
-wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);
+wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);
/* ################### String Concatenation ########################## */
-/** The wcscat function appends a copy of the wide string pointed to by s2
+/** The wcscat function appends a copy of the wide string pointed to by Src
(including the terminating null wide character) to the end of the wide
- string pointed to by s1. The initial wide character of s2 overwrites the
- null wide character at the end of s1.
+ string pointed to by Dest. The initial wide character of Src overwrites the
+ null wide character at the end of Dest.
- @return The wcscat function returns the value of s1.
+ @return The wcscat function returns the value of Dest.
**/
-wchar_t *wcscat(wchar_t * __restrict s1, const wchar_t * __restrict s2);
+wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);
/** The wcsncat function appends not more than n wide characters (a null wide
character and those that follow it are not appended) from the array pointed
- to by s2 to the end of the wide string pointed to by s1. The initial wide
- character of s2 overwrites the null wide character at the end of s1.
+ to by Src to the end of the wide string pointed to by Dest. The initial wide
+ character of Src overwrites the null wide character at the end of Dest.
A terminating null wide character is always appended to the result.
- @return The wcsncat function returns the value of s1.
+ @return The wcsncat function returns the value of Dest.
**/
-wchar_t *wcsncat(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);
+wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);
/* ##################### String Comparison ############################# */
@@ -377,15 +1238,15 @@ int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n); /* ##################### String Searching ############################## */
-/** The wcschr function locates the first occurrence of c in the wide string
- pointed to by s. The terminating null wide character is considered to be
+/** The wcschr function locates the first occurrence of C in the wide string
+ pointed to by S. The terminating null wide character is considered to be
part of the wide string.
@return The wcschr function returns a pointer to the located wide
character, or a null pointer if the wide character does not occur
in the wide string.
**/
-wchar_t *wcschr(const wchar_t *s, wchar_t c);
+wchar_t *wcschr(const wchar_t *S, wchar_t C);
/** The wcscspn function computes the length of the maximum initial segment of
the wide string pointed to by s1 which consists entirely of wide characters
@@ -405,14 +1266,14 @@ size_t wcscspn(const wchar_t *s1, const wchar_t *s2); **/
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
-/** The wcsrchr function locates the last occurrence of c in the wide string
- pointed to by s. The terminating null wide character is considered to be
+/** The wcsrchr function locates the last occurrence of C in the wide string
+ pointed to by S. The terminating null wide character is considered to be
part of the wide string.
@return The wcsrchr function returns a pointer to the wide character,
- or a null pointer if c does not occur in the wide string.
+ or a null pointer if C does not occur in the wide string.
**/
-wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
+wchar_t *wcsrchr(const wchar_t *S, wchar_t C);
/** The wcsspn function computes the length of the maximum initial segment of
the wide string pointed to by s1 which consists entirely of wide characters
@@ -469,53 +1330,72 @@ wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); **/
wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);
-/** The wmemchr function locates the first occurrence of c in the initial n
- wide characters of the object pointed to by s.
+/** The wmemchr function locates the first occurrence of C in the initial n
+ wide characters of the object pointed to by S.
@return The wmemchr function returns a pointer to the located wide
character, or a null pointer if the wide character does not occur
in the object.
**/
-wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);
+wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n);
/* ################### String Manipulation ############################# */
-/** The wcslen function computes the length of the wide string pointed to by s.
+/** The wcslen function computes the length of the wide string pointed to by S.
@return The wcslen function returns the number of wide characters that
precede the terminating null wide character.
**/
-size_t wcslen(const wchar_t *s);
+size_t wcslen(const wchar_t *S);
-/** The wmemset function copies the value of c into each of the first n wide
- characters of the object pointed to by s.
+/** The wmemset function copies the value of C into each of the first n wide
+ characters of the object pointed to by S.
- @return The wmemset function returns the value of s.
+ @return The wmemset function returns the value of S.
**/
-wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
+wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n);
/* ################# Date and Time Conversion ########################### */
/**
+The wcsftime function is equivalent to the strftime function, except that:
+ - The argument s points to the initial element of an array of wide characters into which
+the generated output is to be placed.
+ - The argument maxsize indicates the limiting number of wide characters.
+ - The argument format is a wide string and the conversion specifiers are replaced by
+corresponding sequences of wide characters.
+ - The return value indicates the number of wide characters.
+
+If the total number of resulting wide characters including the terminating null wide
+character is not more than maxsize, the wcsftime function returns the number of
+wide characters placed into the array pointed to by s not including the terminating null
+wide character. Otherwise, zero is returned and the contents of the array are
+indeterminate.
**/
-size_t wcsftime(wchar_t * __restrict s, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
+size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);
/* ############# Multibyte <--> Wide Character Conversion ############### */
-/**
+/** The btowc function determines whether C constitutes a valid single-byte
+ character in the initial shift state.
+
+ @return The btowc function returns WEOF if c has the value EOF or if
+ (unsigned char)C does not constitute a valid single-byte
+ character in the initial shift state. Otherwise, it returns the
+ wide character representation of that character.
**/
-wint_t btowc(int c);
+wint_t btowc(int C);
-/** The wctob function determines whether c corresponds to a member of the extended
+/** The wctob function determines whether C corresponds to a member of the extended
character set whose multibyte character representation is a single byte when in the initial
shift state.
- @return The wctob function returns EOF if c does not correspond to a multibyte
+ @return The wctob function returns EOF if C does not correspond to a multibyte
character with length one in the initial shift state. Otherwise, it
returns the single-byte representation of that character as an
unsigned char converted to an int.
**/
-int wctob(wint_t c);
+int wctob(wint_t C);
/** If ps is not a null pointer, the mbsinit function determines whether the
pointed-to mbstate_t object describes an initial conversion state.
@@ -528,19 +1408,98 @@ int mbsinit(const mbstate_t *ps); /* ####### Restartable Multibyte <--> Wide Character Conversion ######### */
-/**
+/** The mbrlen function is equivalent to the call:<BR>
+@verbatim
+ mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
+@endverbatim
+ where internal is the mbstate_t object for the mbrlen function, except that
+ the expression designated by ps is evaluated only once.
+
+ @return The mbrlen function returns a value between zero and n,
+ inclusive, (size_t)(-2), or (size_t)(-1).
**/
-size_t mbrlen(const char * __restrict s, size_t n, mbstate_t * __restrict ps);
+size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
+If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
+@verbatim
+ mbrtowc(NULL, "", 1, ps)
+@endverbatim
+
+In this case, the values of the parameters pwc and n are ignored.
+
+If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
+the byte pointed to by S to determine the number of bytes needed to complete the next
+multibyte character (including any shift sequences). If the function determines that the
+next multibyte character is complete and valid, it determines the value of the
+corresponding wide character and then, if pwc is not a null pointer, stores that value in
+the object pointed to by pwc. If the corresponding wide character is the null wide
+character, the resulting state described is the initial conversion state.
+
+ @retval 0 if the next n or fewer bytes complete the multibyte
+ character that corresponds to the null wide
+ character (which is the value stored).
+ @retval between_1_and_n_inclusive if the next n or fewer bytes complete
+ a valid multibyte character (which is the value
+ stored); the value returned is the number of bytes
+ that complete the multibyte character.
+ @retval (size_t)(-2) if the next n bytes contribute to an incomplete
+ (but potentially valid) multibyte character, and
+ all n bytes have been processed (no value is stored).
+ @retval (size_t)(-1) if an encoding error occurs, in which case the next
+ n or fewer bytes do not contribute to a complete and
+ valid multibyte character (no value is stored); the
+ value of the macro EILSEQ is stored in errno, and
+ the conversion state is unspecified.
**/
-size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict s, size_t n, mbstate_t * __restrict ps);
+size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);
/**
+If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
+@verbatim
+ wcrtomb(buf, L'\0', ps)
+@endverbatim
+where buf is an internal buffer.
+
+If S is not a null pointer, the wcrtomb function determines the number of bytes needed
+to represent the multibyte character that corresponds to the wide character given by wc
+(including any shift sequences), and stores the multibyte character representation in the
+array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
+wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
+to restore the initial shift state; the resulting state described is the initial conversion state.
+
+ @return The wcrtomb function returns the number of bytes stored in the
+ array object (including any shift sequences). When wc is not a
+ valid wide character, an encoding error occurs: the function
+ stores the value of the macro EILSEQ in errno and
+ returns (size_t)(-1); the conversion state is unspecified.
**/
-size_t wcrtomb(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps);
+size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);
/**
+The mbsrtowcs function converts a sequence of multibyte characters that begins in the
+conversion state described by the object pointed to by ps, from the array indirectly
+pointed to by src into a sequence of corresponding wide characters. If dst is not a null
+pointer, the converted characters are stored into the array pointed to by dst. Conversion
+continues up to and including a terminating null character, which is also stored.
+Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
+not form a valid multibyte character, or (if dst is not a null pointer) when len wide
+characters have been stored into the array pointed to by dst. Each conversion takes
+place as if by a call to the mbrtowc function.
+
+If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
+pointer (if conversion stopped due to reaching a terminating null character) or the address
+just past the last multibyte character converted (if any). If conversion stopped due to
+reaching a terminating null character and if dst is not a null pointer, the resulting state
+described is the initial conversion state.
+
+ @return If the input conversion encounters a sequence of bytes that do
+ not form a valid multibyte character, an encoding error occurs:
+ the mbsrtowcs function stores the value of the macro EILSEQ in
+ errno and returns (size_t)(-1); the conversion state is
+ unspecified. Otherwise, it returns the number of multibyte
+ characters successfully converted, not including the terminating
+ null character (if any).
**/
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);
diff --git a/StdLib/Include/wctype.h b/StdLib/Include/wctype.h index 3df726a..eac084c 100644 --- a/StdLib/Include/wctype.h +++ b/StdLib/Include/wctype.h @@ -1,5 +1,46 @@ /** @file
- Wide character classification functions and macros.
+ Wide character classification and mapping utilities.
+
+ The following macros are defined in this file:<BR>
+@verbatim
+ WEOF Wide char version of end-of-file.
+@endverbatim
+
+ The following types are defined in this file:<BR>
+@verbatim
+ wint_t Type capable of holding all wchar_t values and WEOF.
+ wctrans_t A type for holding locale-specific character mappings.
+ wctype_t Type for holding locale-specific character classifications.
+@endverbatim
+
+ The following functions are declared in this file:<BR>
+@verbatim
+ ############### Wide Character Classification Functions
+ int iswalnum (wint_t);
+ int iswalpha (wint_t);
+ int iswcntrl (wint_t);
+ int iswdigit (wint_t);
+ int iswgraph (wint_t);
+ int iswlower (wint_t);
+ int iswprint (wint_t);
+ int iswpunct (wint_t);
+ int iswblank (wint_t);
+ int iswspace (wint_t);
+ int iswupper (wint_t);
+ int iswxdigit (wint_t);
+
+ ############### Extensible Wide Character Classification Functions
+ wctype_t wctype (const char *);
+ int iswctype (wint_t, wctype_t);
+
+ ############### Wide Character Case Mapping Utilities
+ wint_t towlower (wint_t);
+ wint_t towupper (wint_t);
+
+ ############### Extensible Wide Character Case Mapping Utilities
+ wctrans_t wctrans (const char *);
+ wint_t towctrans (wint_t, wctrans_t);
+@endverbatim
Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available under
@@ -45,44 +86,258 @@ #include <machine/ansi.h>
#ifdef _EFI_WINT_T
+ /** wint_t is an integer type unchanged by default argument promotions that can
+ hold any value corresponding to members of the extended character set, as
+ well as at least one value that does not correspond to any member of the
+ extended character set: WEOF.
+ */
typedef _EFI_WINT_T wint_t;
#undef _BSD_WINT_T_
#undef _EFI_WINT_T
#endif
#ifdef _BSD_WCTRANS_T_
-typedef wint_t (*wctrans_t)(wint_t);
-#undef _BSD_WCTRANS_T_
+ /** A scalar type for holding locale-specific character mappings. */
+ typedef wint_t (*wctrans_t)(wint_t);
+ #undef _BSD_WCTRANS_T_
#endif
#ifdef _BSD_WCTYPE_T_
-typedef _BSD_WCTYPE_T_ wctype_t;
-#undef _BSD_WCTYPE_T_
+ /** A scalar type capable of holding values representing locale-specific
+ character classifications. */
+ typedef _BSD_WCTYPE_T_ wctype_t;
+ #undef _BSD_WCTYPE_T_
#endif
#ifndef WEOF
-#define WEOF ((wint_t)-1)
+ /** WEOF expands to a constant expression of type wint_t whose value does not
+ correspond to any member of the extended character set. It is accepted
+ (and returned) by several functions, declared in this file, to indicate
+ end-of-file, that is, no more input from a stream. It is also used as a
+ wide character value that does not correspond to any member of the
+ extended character set.
+ */
+ #define WEOF ((wint_t)-1)
#endif
__BEGIN_DECLS
-int /*EFIAPI*/ iswalnum(wint_t);
-int /*EFIAPI*/ iswalpha(wint_t);
-int /*EFIAPI*/ iswcntrl(wint_t);
-int /*EFIAPI*/ iswctype(wint_t, wctype_t);
-int /*EFIAPI*/ iswdigit(wint_t);
-int /*EFIAPI*/ iswgraph(wint_t);
-int /*EFIAPI*/ iswlower(wint_t);
-int /*EFIAPI*/ iswprint(wint_t);
-int /*EFIAPI*/ iswpunct(wint_t);
-int /*EFIAPI*/ iswblank(wint_t);
-int /*EFIAPI*/ iswspace(wint_t);
-int /*EFIAPI*/ iswupper(wint_t);
-int /*EFIAPI*/ iswxdigit(wint_t);
-wint_t /*EFIAPI*/ towctrans(wint_t, wctrans_t);
-wint_t /*EFIAPI*/ towlower(wint_t);
-wint_t /*EFIAPI*/ towupper(wint_t);
-wctrans_t /*EFIAPI*/ wctrans(const char *);
-wctype_t /*EFIAPI*/ wctype(const char *);
+ /** Test for any wide character for which iswalpha or iswdigit is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswalnum (wint_t WC);
+
+ /** Test for any wide character for which iswupper or iswlower is TRUE,
+ OR, a locale-specific character where none of iswcntrl, iswdigit,
+ iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswalpha (wint_t WC);
+
+ /** Test for any wide control character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswcntrl (wint_t WC);
+
+ /** Test if the value of WC is a wide character that corresponds to a decimal digit.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswdigit (wint_t WC);
+
+ /** Test for wide characters for which iswprint is TRUE and iswspace is FALSE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswgraph (wint_t WC);
+
+ /** The iswlower function tests for any wide character that corresponds to a
+ lowercase letter or is one of a locale-specific set of wide characters
+ for which none of iswcntrl, iswdigit, iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswlower (wint_t WC);
+
+ /** Test for any printing wide character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswprint (wint_t WC);
+
+ /** The iswpunct function tests for any printing wide character that is one
+ of a locale-specific set of punctuation wide characters for which
+ neither iswspace nor iswalnum is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswpunct (wint_t WC);
+
+ /** Test for standard blank characters or locale-specific characters
+ for which iswspace is TRUE and are used to separate words within a line
+ of text. In the "C" locale, iswblank only returns TRUE for the standard
+ blank characters space (L' ') and horizontal tab (L'\t').
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswblank (wint_t WC);
+
+ /** The iswspace function tests for any wide character that corresponds to a
+ locale-specific set of white-space wide characters for which none of
+ iswalnum, iswgraph, or iswpunct is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswspace (wint_t WC);
+
+ /** Tests for any wide character that corresponds to an uppercase letter or
+ is one of a locale-specific set of wide characters for which none of
+ iswcntrl, iswdigit, iswpunct, or iswspace is TRUE.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswupper (wint_t WC);
+
+ /** The iswxdigit function tests for any wide character that corresponds to a
+ hexadecimal-digit character.
+
+ @param[in] WC The wide character to be classified.
+
+ @return Returns non-zero (TRUE) if and only if the value of WC conforms
+ to the classification described for this function.
+ */
+ int iswxdigit (wint_t WC);
+
+ /** Construct a value that describes a class of wide characters, identified
+ by the string pointed to by Desc. The constructed value is suitable for
+ use as the second argument to the iswctype function.
+
+ The following strings name classes of wide characters that the iswctype
+ function is able to test against. These strings are valid in all locales
+ as Desc arguments to wctype().
+ - "alnum"
+ - "alpha"
+ - "blank"
+ - "cntrl"
+ - "digit"
+ - "graph"
+ - "lower"
+ - "print"
+ - "punct"
+ - "space"
+ - "upper"
+ - "xdigit
+
+ @param[in] Desc A pointer to a multibyte character string naming a
+ class of wide characters.
+
+ @return If Desc identifies a valid class of wide characters in the
+ current locale, the wctype function returns a nonzero value that
+ is valid as the second argument to the iswctype function;
+ otherwise, it returns zero.
+ */
+ wctype_t wctype (const char *Desc);
+
+ /** Determine whether the wide character WC has the property described by Wct.
+
+ @param[in] WC The wide character to be classified.
+ @param[in] Wct A value describing a class of wide characters.
+
+ @return The iswctype function returns nonzero (TRUE) if and only if the
+ value of the wide character WC has the property described by Wct.
+ */
+ int iswctype (wint_t WC, wctype_t Wct);
+
+ /** Convert an uppercase letter to a corresponding lowercase letter.
+
+ @param[in] WC The wide character to be converted.
+
+ @return If the argument is a wide character for which iswupper is TRUE
+ and there are one or more corresponding wide characters, as
+ specified by the current locale, for which iswlower is TRUE, the
+ towlower function returns one of the corresponding wide
+ characters (always the same one for any given locale); otherwise,
+ the argument is returned unchanged.
+ */
+ wint_t towlower (wint_t WC);
+
+ /** Convert a lowercase letter to a corresponding uppercase letter.
+
+ @param[in] WC The wide character to be converted.
+
+ @return If the argument is a wide character for which iswlower is TRUE
+ and there are one or more corresponding wide characters, as
+ specified by the current locale, for which iswupper is TRUE, the
+ towupper function returns one of the corresponding wide
+ characters (always the same one for any given locale); otherwise,
+ the argument is returned unchanged.
+ */
+ wint_t towupper (wint_t WC);
+
+ /** Construct a value that describes a mapping between wide characters
+ identified by the string argument, S.
+
+ The strings listed below are valid in all locales as the S argument to
+ the wctrans function.
+ - "tolower"
+ - "toupper"
+
+ @param[in] S A pointer to a multibyte character string naming a
+ mapping between wide characters.
+
+ @return If S identifies a valid mapping of wide characters in the current
+ locale, the wctrans function returns a nonzero value that is
+ valid as the second argument to the towctrans function;
+ otherwise, it returns zero.
+ */
+ wctrans_t wctrans (const char *S);
+
+ /** Map the wide character WC using the mapping described by WTr. The current
+ locale will be the same as during the call to wctrans that returned
+ the value WTr.
+
+ @param[in] WC The wide character to be converted.
+ @param[in] WTr A value describing a mapping of wide characters in the
+ current locale.
+
+ @return Returns the mapped value of WC using the mapping selected by WTr.
+ */
+ wint_t towctrans (wint_t WC, wctrans_t WTr);
__END_DECLS
#endif /* _WCTYPE_H_ */
diff --git a/StdLib/LibC/Stdio/Stdio.inf b/StdLib/LibC/Stdio/Stdio.inf index 6edc886..1b8852e 100644 --- a/StdLib/LibC/Stdio/Stdio.inf +++ b/StdLib/LibC/Stdio/Stdio.inf @@ -143,4 +143,4 @@ # Nasty things could happen if you do.
#
[BuildOptions]
- GCC:*_*_*_CC_FLAGS = -fno-builtin -Wno-pointer-to-int-cast -Wno-int-to-pointer-cast
+ GCC:*_*_*_CC_FLAGS = -fno-builtin -Wno-pointer-to-int-cast -Wno-int-to-pointer-cast -Wno-format
diff --git a/StdLib/LibC/Stdio/fgetpos.c b/StdLib/LibC/Stdio/fgetpos.c index 61d6f75..8dd0fd6 100644 --- a/StdLib/LibC/Stdio/fgetpos.c +++ b/StdLib/LibC/Stdio/fgetpos.c @@ -56,7 +56,7 @@ fgetpos(FILE *fp, fpos_t *pos) _DIAGASSERT(fp != NULL);
_DIAGASSERT(pos != NULL);
- if(fp == NULL) {
+ if((fp == NULL) || (pos == NULL)) {
errno = EINVAL;
return (EOF);
}
diff --git a/StdLib/LibC/Stdio/vfwprintf.c b/StdLib/LibC/Stdio/vfwprintf.c index 0554edb..f5cf394 100644 --- a/StdLib/LibC/Stdio/vfwprintf.c +++ b/StdLib/LibC/Stdio/vfwprintf.c @@ -1003,7 +1003,12 @@ reswitch: switch (ch) { mbs = initial;
mbseqlen = wcrtomb(buf,
- (wchar_t)GETARG(wint_t), &mbs);
+ /* The compiler "knows" that wint_t may be smaller than an int so
+ it warns about it when used as the type argument to va_arg().
+ Since any type of parameter smaller than an int is promoted to an int on a
+ function call, we must call GETARG with type int instead of wint_t.
+ */
+ (wchar_t)GETARG(int), &mbs);
if (mbseqlen == (size_t)-1) {
fp->_flags |= __SERR;
goto error;
@@ -1015,7 +1020,7 @@ reswitch: switch (ch) { }
#else
if (flags & LONGINT)
- *buf = (wchar_t)GETARG(wint_t);
+ *buf = (wchar_t)GETARG(int);
else
*buf = (wchar_t)btowc(GETARG(int));
size = 1;
@@ -1915,7 +1920,7 @@ done: (*argtable) [n].pvoidarg = va_arg (ap, void *);
break;
case T_WINT:
- (*argtable) [n].wintarg = va_arg (ap, wint_t);
+ (*argtable) [n].wintarg = va_arg (ap, int);
break;
case TP_WCHAR:
(*argtable) [n].pwchararg = va_arg (ap, wchar_t *);
diff --git a/StdLib/LibC/Time/gettimeofday.c b/StdLib/LibC/Time/gettimeofday.c index b26d157..1de6dfa 100644 --- a/StdLib/LibC/Time/gettimeofday.c +++ b/StdLib/LibC/Time/gettimeofday.c @@ -10,7 +10,7 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- * Copyright (c) 1995, 1996, 1997 Kungliga Tekniska Högskolan
+ * Copyright (c) 1995, 1996, 1997 Kungliga Tekniska Hogskolan
* (Royal Institute of Technology, Stockholm, Sweden).
* All rights reserved.
*
diff --git a/StdLib/PosixLib/Glob/LibGlob.inf b/StdLib/PosixLib/Glob/LibGlob.inf index fab4730..0640438 100644 --- a/StdLib/PosixLib/Glob/LibGlob.inf +++ b/StdLib/PosixLib/Glob/LibGlob.inf @@ -23,7 +23,7 @@ #
-# VALID_ARCHITECTURES = IA32 X64 IPF EBC
+# VALID_ARCHITECTURES = IA32 X64 IPF
#
[Sources.common]
@@ -40,8 +40,7 @@ MemoryAllocationLib
ShellLib
BaseLib
+ LibC
LibStdio
LibStdLib
LibString
-
-[Pcd]
diff --git a/StdLib/PosixLib/Glob/glob.c b/StdLib/PosixLib/Glob/glob.c index dec78d8..a6a2dc1 100644 --- a/StdLib/PosixLib/Glob/glob.c +++ b/StdLib/PosixLib/Glob/glob.c @@ -23,6 +23,15 @@ * gl_matchc:
* Number of matches in the current invocation of glob.
*
+ Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
+ This program and the accompanying materials are licensed and made available under
+ the terms and conditions of the BSD License that accompanies this distribution.
+ The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
* Copyright (c) 1989, 1993
* The Regents of the University of California. All rights reserved.
*
@@ -56,8 +65,10 @@ glob.c 8.3 (Berkeley) 10/13/93
NetBSD: glob.c,v 1.23.4.1 2010/07/19 18:14:08 riz Exp
*/
-#pragma warning ( disable : 4244 )
-#pragma warning ( disable : 4018 )
+#if defined(_MSC_VER)
+ #pragma warning ( disable : 4244 )
+ #pragma warning ( disable : 4018 )
+#endif
#include <LibConfig.h>
|