in this file causes copying to take place between objects that overlap, the\r
behavior is undefined.\r
\r
- Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>\r
+ The following macros are defined in this file:<BR>\r
+ @verbatim\r
+ NULL Actually defined in <sys/EfiCdefs.h>\r
+ WCHAR_MIN Minimum value of a wide char.\r
+ WCHAR_MAX Maximum value of a wide char.\r
+ WEOF Wide char version of end-of-file.\r
+ @endverbatim\r
+\r
+ The following types are defined in this file:<BR>\r
+ @verbatim\r
+ size_t Unsigned integer type of the result of the sizeof operator.\r
+ wchar_t Type of wide characters.\r
+ wint_t Type capable of holding all wchar_t values and WEOF.\r
+ mbstate_t Type of object holding multibyte conversion state.\r
+ struct tm Incomplete declaration of the broken-down time structure.\r
+ @endverbatim\r
+\r
+ The following functions are declared in this file:<BR>\r
+@verbatim\r
+ ############### Formatted Input/Output Functions\r
+ int fwprintf (FILE * __restrict stream,\r
+ const wchar_t * __restrict format, ...);\r
+ int fwscanf (FILE * __restrict stream,\r
+ const wchar_t * __restrict format, ...);\r
+ int swprintf (wchar_t * __restrict s, size_t n,\r
+ const wchar_t * __restrict format, ...);\r
+ int swscanf (const wchar_t * __restrict s,\r
+ const wchar_t * __restrict format, ...);\r
+ int vfwprintf (FILE * __restrict stream,\r
+ const wchar_t * __restrict format, va_list arg);\r
+ int vfwscanf (FILE * __restrict stream,\r
+ const wchar_t * __restrict format, va_list arg);\r
+ int vswprintf (wchar_t * __restrict s, size_t n,\r
+ const wchar_t * __restrict format, va_list arg);\r
+ int vswscanf (const wchar_t * __restrict s,\r
+ const wchar_t * __restrict format, va_list arg);\r
+ int vwprintf (const wchar_t * __restrict format, va_list arg);\r
+ int vwscanf (const wchar_t * __restrict format, va_list arg);\r
+ int wprintf (const wchar_t * __restrict format, ...);\r
+ int wscanf (const wchar_t * __restrict format, ...);\r
+\r
+ ################### Input/Output Functions\r
+ wint_t fgetwc (FILE *stream);\r
+ wchar_t *fgetws (wchar_t * __restrict S, int n,\r
+ FILE * __restrict stream);\r
+ wint_t fputwc (wchar_t c, FILE *stream);\r
+ int fputws (const wchar_t * __restrict S,\r
+ FILE * __restrict stream);\r
+ int fwide (FILE *stream, int mode);\r
+ wint_t getwc (FILE *stream);\r
+ wint_t getwchar (void);\r
+ wint_t putwc (wchar_t c, FILE *stream);\r
+ wint_t putwchar (wchar_t c);\r
+ wint_t ungetwc (wint_t c, FILE *stream);\r
+\r
+ ################### Numeric Conversions\r
+ double wcstod (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr);\r
+ float wcstof (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr);\r
+ long double wcstold (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr);\r
+ long int wcstol (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr, int base);\r
+ long long int wcstoll (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr, int base);\r
+ unsigned long int wcstoul (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr, int base);\r
+ unsigned long long int wcstoull (const wchar_t * __restrict nptr,\r
+ wchar_t ** __restrict endptr, int base);\r
+\r
+ ####################### String Copying\r
+ wchar_t *wcscpy (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2);\r
+ wchar_t *wcsncpy (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2, size_t n);\r
+ wchar_t *wmemcpy (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2, size_t n);\r
+ wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n);\r
+\r
+ ################### String Concatenation\r
+ wchar_t *wcscat (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2);\r
+ wchar_t *wcsncat (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2, size_t n);\r
+\r
+ ##################### String Comparison\r
+ int wcscmp (const wchar_t *s1, const wchar_t *s2);\r
+ int wcscoll (const wchar_t *s1, const wchar_t *s2);\r
+ int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n);\r
+ size_t wcsxfrm (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2, size_t n);\r
+ int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n);\r
+\r
+ ##################### String Searching\r
+ wchar_t *wcschr (const wchar_t *S, wchar_t c);\r
+ size_t wcscspn (const wchar_t *s1, const wchar_t *s2);\r
+ wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2);\r
+ wchar_t *wcsrchr (const wchar_t *S, wchar_t c);\r
+ size_t wcsspn (const wchar_t *s1, const wchar_t *s2);\r
+ wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);\r
+ wchar_t *wcstok (wchar_t * __restrict s1,\r
+ const wchar_t * __restrict s2,\r
+ wchar_t ** __restrict ptr);\r
+ wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n);\r
+\r
+ ################### String Manipulation\r
+ size_t wcslen (const wchar_t *S);\r
+ wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n);\r
+\r
+ ################# Date and Time Conversion\r
+ size_t wcsftime (wchar_t * __restrict S, size_t maxsize,\r
+ const wchar_t * __restrict format,\r
+ const struct tm * __restrict timeptr);\r
+\r
+ ############# Multibyte <--> Wide Character Conversion\r
+ wint_t btowc (int c);\r
+ int wctob (wint_t c);\r
+ int mbsinit (const mbstate_t *ps);\r
+\r
+ ####### Restartable Multibyte <--> Wide Character Conversion\r
+ size_t mbrlen (const char * __restrict S, size_t n,\r
+ mbstate_t * __restrict ps);\r
+ size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S,\r
+ size_t n, mbstate_t * __restrict ps);\r
+ size_t wcrtomb (char * __restrict S, wchar_t wc,\r
+ mbstate_t * __restrict ps);\r
+ size_t mbsrtowcs (wchar_t * __restrict dst,\r
+ const char ** __restrict src, size_t len,\r
+ mbstate_t * __restrict ps);\r
+ size_t wcsrtombs (char * __restrict dst,\r
+ const wchar_t ** __restrict src,\r
+ size_t len, mbstate_t * __restrict ps);\r
+@endverbatim\r
+\r
+ @note Properly constructed programs will take the following into consideration:\r
+ - wchar_t and wint_t may be the same integer type.\r
+ - WEOF might be a different value than that of EOF.\r
+ - WEOF might not be negative.\r
+ - mbstate_t objects are not intended to be inspected by programs.\r
+\r
+ Copyright (c) 2010 - 2014, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php.\r
+ http://opensource.org/licenses/bsd-license.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
-\r
**/\r
#ifndef _WCHAR_H\r
#define _WCHAR_H\r
#endif\r
\r
#ifdef _EFI_SIZE_T_\r
- typedef _EFI_SIZE_T_ size_t;\r
+ typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */\r
#undef _BSD_SIZE_T_\r
#undef _EFI_SIZE_T_\r
#endif\r
\r
#ifndef __cplusplus\r
#ifdef _EFI_WCHAR_T\r
- typedef _EFI_WCHAR_T wchar_t;\r
+ /** An integer type capable of representing all distinct codes in the\r
+ UCS-2 encoding supported by UEFI.\r
+ **/\r
+ typedef _EFI_WCHAR_T wchar_t;\r
#undef _BSD_WCHAR_T_\r
#undef _EFI_WCHAR_T\r
#endif\r
#endif\r
\r
-/* mbstate_t is an opaque object, that must not be an array type, used to keep\r
- conversion state during multibyte stream conversions.\r
- */\r
#ifdef _BSD_MBSTATE_T_\r
+ /** mbstate_t is an opaque object, that is not an array type, used to keep\r
+ conversion state during multibyte stream conversions.\r
+ */\r
typedef _BSD_MBSTATE_T_ mbstate_t;\r
#undef _BSD_MBSTATE_T_\r
#endif\r
\r
-/* wint_t is an integer type unchanged by default argument promotions that can\r
- hold any value corresponding to members of the extended character set, as\r
- well as at least one value that does not correspond to any member of the\r
- extended character set: WEOF.\r
-*/\r
#ifdef _EFI_WINT_T\r
- typedef _EFI_WINT_T wint_t;\r
+ /** wint_t is an integer type unchanged by default argument promotions that can\r
+ hold any value corresponding to members of the extended character set, as\r
+ well as at least one value that does not correspond to any member of the\r
+ extended character set: WEOF.\r
+ */\r
+ typedef _EFI_WINT_T wint_t;\r
#undef _BSD_WINT_T_\r
#undef _EFI_WINT_T\r
#endif\r
\r
-/* Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and\r
- a maximum value defined by __USHRT_MAX (65535 on IA processors).\r
-*/\r
#ifndef WCHAR_MIN\r
- #define WCHAR_MIN 0\r
- #define WCHAR_MAX __USHRT_MAX\r
-#endif\r
-\r
-/* limits of wint_t */\r
-#ifndef WINT_MIN\r
- #define WINT_MIN _EFI_WINT_MIN /* wint_t */\r
- #define WINT_MAX _EFI_WINT_MAX /* wint_t */\r
+ /** @{\r
+ Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and\r
+ a maximum value defined by __USHRT_MAX (65535 on IA processors).\r
+ */\r
+ #define WCHAR_MIN 0\r
+ #define WCHAR_MAX __USHRT_MAX\r
+ /*@}*/\r
#endif\r
\r
-/* WEOF expands to a constant expression of type wint_t whose value does not\r
- correspond to any member of the extended character set. It is accepted\r
- (and returned) by several functions, declared in this file, to indicate\r
- end-of-file, that is, no more input from a stream. It is also used as a\r
- wide character value that does not correspond to any member of the\r
- extended character set.\r
-*/\r
#ifndef WEOF\r
+ /** WEOF expands to a constant expression of type wint_t whose value does not\r
+ correspond to any member of the extended character set. It is accepted\r
+ (and returned) by several functions, declared in this file, to indicate\r
+ end-of-file, that is, no more input from a stream. It is also used as a\r
+ wide character value that does not correspond to any member of the\r
+ extended character set.\r
+ */\r
#define WEOF ((wint_t)-1)\r
#endif\r
\r
-/* tm is declared here as an incomplete structure type. The full structure\r
- declaration is in <time.h>.\r
+/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */\r
+#ifndef WINT_MIN\r
+ #define WINT_MIN _EFI_WINT_MIN /* wint_t */\r
+ #define WINT_MAX _EFI_WINT_MAX /* wint_t */\r
+#endif\r
+\r
+/** Type struct tm is declared here as an incomplete structure type for use as an argument\r
+ type by the wcsftime function. The full structure declaration is in <time.h>.\r
*/\r
struct tm;\r
\r
/* ############### Formatted Input/Output Functions ##################### */\r
\r
-/**\r
-The fwprintf function writes output to the stream pointed to by stream, under\r
-control of the wide string pointed to by format that specifies how subsequent arguments\r
-are converted for output. If there are insufficient arguments for the format, the behavior\r
-is undefined. If the format is exhausted while arguments remain, the excess arguments\r
-are evaluated (as always) but are otherwise ignored. The fwprintf function returns\r
-when the end of the format string is encountered.\r
-\r
-The fwprintf function returns the number of wide characters transmitted, or a negative\r
-value if an output or encoding error occurred.\r
+/** The fwprintf function writes output to the stream pointed to by stream,\r
+ under control of the wide string pointed to by format that specifies how\r
+ subsequent arguments are converted for output. If there are insufficient\r
+ arguments for the format, the behavior is undefined. If the format is\r
+ exhausted while arguments remain, the excess arguments are evaluated\r
+ (as always) but are otherwise ignored. The fwprintf function returns\r
+ when the end of the format string is encountered.\r
+\r
+ The format is composed of zero or more directives: ordinary wide characters\r
+ (not %), which are copied unchanged to the output stream; and conversion\r
+ specifications, each of which results in fetching zero or more subsequent\r
+ arguments, converting them, if applicable, according to the corresponding\r
+ conversion specifier, and then writing the result to the output stream.\r
+\r
+ Each conversion specification is introduced by the wide character %. After\r
+ the %, the following appear in sequence:\r
+ * Zero or more flags (in any order) that modify the meaning of the\r
+ conversion specification.\r
+ * An optional minimum field width. If the converted value has fewer wide\r
+ characters than the field width, it is padded with spaces (by default)\r
+ on the left (or right, if the left adjustment flag, described later,\r
+ has been given) to the field width. The field width takes the form of\r
+ an asterisk * (described later) or a nonnegative decimal integer.\r
+ * An optional precision that gives the minimum number of digits to appear\r
+ for the d, i, o, u, x, and X conversions, the number of digits to\r
+ appear after the decimal-point wide character for e, E, f, and F\r
+ conversions, the maximum number of significant digits for the g and G\r
+ conversions, or the maximum number of wide characters to be written\r
+ for s conversions. The precision takes the form of a period (.)\r
+ followed either by an asterisk * (described later) or by an optional\r
+ decimal integer; if only the period is specified, the precision is\r
+ taken as zero. If a precision appears with any other conversion\r
+ specifier, the behavior is undefined.\r
+ * An optional length modifier that specifies the size of the argument.\r
+ * A conversion specifier wide character that specifies the type of\r
+ conversion to be applied.\r
+\r
+ As noted above, a field width, or precision, or both, may be indicated by\r
+ an asterisk. In this case, an int argument supplies the field width or\r
+ precision. The arguments specifying field width, or precision, or both,\r
+ must appear (in that order) before the argument (if any) to be converted.\r
+ A negative field width argument is taken as a - flag followed by a positive\r
+ field width. A negative precision argument is taken as if the precision\r
+ were omitted.\r
+\r
+ The flag wide characters and their meanings are:<BR>\r
+ - The result of the conversion is left-justified within the field.\r
+ (It is right-justified if this flag is not specified.)\r
+ + The result of a signed conversion always begins with a plus or minus\r
+ sign. (It begins with a sign only when a negative value is converted\r
+ if this flag is not specified.)\r
+ space If the first wide character of a signed conversion is not a sign, or\r
+ if a signed conversion results in no wide characters, a space is\r
+ prefixed to the result. If the space and + flags both appear, the\r
+ space flag is ignored.\r
+ # The result is converted to an "alternative form". For o conversion,\r
+ it increases the precision, if and only if necessary, to force the\r
+ first digit of the result to be a zero (if the value and precision\r
+ are both 0, a single 0 is printed). For x (or X) conversion, a\r
+ nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,\r
+ and G conversions, the result of converting a floating-point number\r
+ always contains a decimal-point wide character, even if no digits\r
+ follow it. (Normally, a decimal-point wide character appears in the\r
+ result of these conversions only if a digit follows it.) For g and G\r
+ conversions, trailing zeros are not removed from the result. For\r
+ other conversions, the behavior is undefined.\r
+ 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros\r
+ (following any indication of sign or base) are used to pad to the\r
+ field width rather than performing space padding, except when\r
+ converting an infinity or NaN. If the 0 and - flags both appear,\r
+ the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a\r
+ precision is specified, the 0 flag is ignored. For other conversions,\r
+ the behavior is undefined.\r
+\r
+ The length modifiers and their meanings are:<BR>\r
+ hh Specifies that a following d, i, o, u, x, or X conversion specifier\r
+ applies to a signed char or unsigned char argument (the argument\r
+ will have been promoted according to the integer promotions, but its\r
+ value shall be converted to signed char or unsigned char before\r
+ printing); or that a following n conversion specifier applies to a\r
+ pointer to a signed char argument.\r
+ h Specifies that a following d, i, o, u, x, or X conversion specifier\r
+ applies to a short int or unsigned short int argument (the argument\r
+ will have been promoted according to the integer promotions, but its\r
+ value shall be converted to short int or unsigned short int before\r
+ printing); or that a following n conversion specifier applies to a\r
+ pointer to a short int argument.\r
+ l (ell) Specifies that a following d, i, o, u, x, or X conversion\r
+ specifier applies to a long int or unsigned long int argument;\r
+ that a following n conversion specifier applies to a pointer to a\r
+ long int argument; that a following c conversion specifier\r
+ applies to a wint_t argument; that a following s conversion\r
+ specifier applies to a pointer to a wchar_t argument; or has no\r
+ effect on a following e, E, f, F, g, or G conversion specifier.\r
+ ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion\r
+ specifier applies to a long long int or unsigned long long int\r
+ argument; or that a following n conversion specifier applies\r
+ to a pointer to a long long int argument.\r
+ j Specifies that a following d, i, o, u, x, or X conversion specifier\r
+ applies to an intmax_t or uintmax_t argument; or that a following\r
+ n conversion specifier applies to a pointer to an intmax_t argument.\r
+ z Specifies that a following d, i, o, u, x, or X conversion specifier\r
+ applies to a size_t or the corresponding signed integer type\r
+ argument; or that a following n conversion specifier applies to a\r
+ pointer to a signed integer type corresponding to size_t argument.\r
+ t Specifies that a following d, i, o, u, x, or X conversion specifier\r
+ applies to a ptrdiff_t or the corresponding unsigned integer type\r
+ argument; or that a following n conversion specifier applies to a\r
+ pointer to a ptrdiff_t argument.\r
+ L Specifies that a following a, A, e, E, f, F, g, or G conversion\r
+ specifier applies to a long double argument.\r
+\r
+ If a length modifier appears with any conversion specifier other than as\r
+ specified above, the behavior is undefined.\r
+\r
+ The conversion specifiers and their meanings are:<BR>\r
+ d,i The int argument is converted to signed decimal in the\r
+ style [-]dddd. The precision specifies the minimum number of digits\r
+ to appear; if the value being converted can be represented in fewer\r
+ digits, it is expanded with leading zeros. The default precision\r
+ is 1. The result of converting a zero value with a precision of\r
+ zero is no wide characters.\r
+ o,u,x,X The unsigned int argument is converted to unsigned octal (o),\r
+ unsigned decimal (u), or unsigned hexadecimal notation (x or X) in\r
+ the style dddd; the letters abcdef are used for x conversion and\r
+ the letters ABCDEF for X conversion. The precision specifies the\r
+ minimum number of digits to appear; if the value being converted\r
+ can be represented in fewer digits, it is expanded with leading\r
+ zeros. The default precision is 1. The result of converting a zero\r
+ value with a precision of zero is no wide characters.\r
+ f,F A double argument representing a floating-point number is converted\r
+ to decimal notation in the style [-]ddd.ddd, where the number of\r
+ digits after the decimal-point wide character is equal to the\r
+ precision specification. If the precision is missing, it is taken\r
+ as 6; if the precision is zero and the # flag is not specified, no\r
+ decimal-point wide character appears. If a decimal-point wide\r
+ character appears, at least one digit appears before it. The value\r
+ is rounded to the appropriate number of digits.<BR>\r
+ A double argument representing an infinity is converted to [-]inf.\r
+ A double argument representing a NaN is converted to [-]nan.\r
+ The F conversion specifier produces INF or NAN instead\r
+ of inf or nan, respectively.\r
+ e,E A double argument representing a floating-point number is converted\r
+ in the style [-]d.ddd e +/- dd, where there is one digit (which is\r
+ nonzero if the argument is nonzero) before the decimal-point wide\r
+ character and the number of digits after it is equal to the\r
+ precision; if the precision is missing, it is taken as 6; if the\r
+ precision is zero and the # flag is not specified, no decimal-point\r
+ wide character appears. The value is rounded to the appropriate\r
+ number of digits. The E conversion specifier produces a number with\r
+ E instead of e introducing the exponent. The exponent always\r
+ contains at least two digits, and only as many more digits as\r
+ necessary to represent the exponent. If the value is zero, the\r
+ exponent is zero. A double argument representing an infinity or NaN\r
+ is converted in the style of an f or F conversion specifier.\r
+ g,G A double argument representing a floating-point number is converted\r
+ in style f or e (or in style F or E in the case of a G conversion\r
+ specifier), depending on the value converted and the precision.\r
+ Let P equal the precision if nonzero, 6 if the precision is\r
+ omitted, or 1 if the precision is zero. Then, if a conversion with\r
+ style E would have an exponent of X:\r
+ - if P > X = -4, the conversion is with style f (or F) and\r
+ precision P - (X + 1).\r
+ - otherwise, the conversion is with style e (or E) and\r
+ precision P - 1.\r
+ Finally, unless the # flag is used, any trailing zeros are removed\r
+ from the fractional portion of the result and the decimal-point\r
+ wide character is removed if there is no fractional portion\r
+ remaining. A double argument representing an infinity or NaN is\r
+ converted in the style of an f or F conversion specifier.\r
+ c If no l length modifier is present, the int argument is converted\r
+ to a wide character as if by calling btowc and the resulting wide\r
+ character is written. If an l length modifier is present, the\r
+ wint_t argument is converted to wchar_t and written.\r
+ s If no l length modifier is present, the argument shall be a pointer\r
+ to the initial element of a character array containing a multibyte\r
+ character sequence beginning in the initial shift state. Characters\r
+ from the array are converted as if by repeated calls to the mbrtowc\r
+ function, with the conversion state described by an mbstate_t\r
+ object initialized to zero before the first multibyte character is\r
+ converted, and written up to (but not including) the terminating\r
+ null wide character. If the precision is specified, no more than\r
+ that many wide characters are written. If the precision is not\r
+ specified or is greater than the size of the converted array, the\r
+ converted array shall contain a null wide character.<BR>\r
+ If an l length modifier is present, the argument shall be a pointer\r
+ to the initial element of an array of wchar_t type. Wide characters\r
+ from the array are written up to (but not including) a terminating\r
+ null wide character. If the precision is specified, no more than\r
+ that many wide characters are written. If the precision is not\r
+ specified or is greater than the size of the array, the array\r
+ shall contain a null wide character.\r
+ p The argument shall be a pointer to void. The value of the pointer\r
+ is converted to a sequence of printing wide characters, in an\r
+ implementation-defined manner.\r
+ n The argument shall be a pointer to signed integer into which is\r
+ written the number of wide characters written to the output stream\r
+ so far by this call to fwprintf. No argument is converted, but one\r
+ is consumed. If the conversion specification includes any flags, a\r
+ field width, or a precision, the behavior is undefined.\r
+ % A % wide character is written. No argument is converted. The\r
+ complete conversion specification is %%.\r
+\r
+\r
+ @param[in] stream An open File specifier to which the output is sent.\r
+ @param[in] format A wide character sequence containing characters\r
+ to be copied unchanged, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param ... Variable number of parameters as required by format.\r
+\r
+ @return The fwprintf function returns the number of wide characters\r
+ transmitted, or a negative value if an output or encoding error\r
+ occurred.\r
**/\r
int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);\r
\r
-/**\r
-The fwscanf function reads input from the stream pointed to by stream, under\r
-control of the wide string pointed to by format that specifies the admissible input\r
-sequences and how they are to be converted for assignment, using subsequent arguments\r
-as pointers to the objects to receive the converted input. If there are insufficient\r
-arguments for the format, the behavior is undefined. If the format is exhausted while\r
-arguments remain, the excess arguments are evaluated (as always) but are otherwise\r
-ignored.\r
-\r
-The fwscanf function returns the value of the macro EOF if an input failure occurs\r
-before any conversion. Otherwise, the function returns the number of input items\r
-assigned, which can be fewer than provided for, or even zero, in the event of an early\r
-matching failure.\r
+/** The fwscanf function reads input from the stream pointed to by stream,\r
+ under control of the wide string pointed to by format that specifies\r
+ the admissible input sequences and how they are to be converted for\r
+ assignment, using subsequent arguments as pointers to the objects to\r
+ receive the converted input. If there are insufficient arguments for\r
+ the format, the behavior is undefined. If the format is exhausted while\r
+ arguments remain, the excess arguments are evaluated (as always) but are\r
+ otherwise ignored.\r
+\r
+ The format is composed of zero or more directives: one or more white-space\r
+ wide characters, an ordinary wide character (neither % nor a white-space\r
+ wide character), or a conversion specification. Each conversion\r
+ specification is introduced by the wide character %. After the %, the\r
+ following appear in sequence:\r
+ - An optional assignment-suppressing wide character *.\r
+ - An optional decimal integer greater than zero that specifies the\r
+ maximum field width (in wide characters).\r
+ - An optional length modifier that specifies the size of the receiving object.\r
+ - A conversion specifier wide character that specifies the type of\r
+ conversion to be applied.\r
+\r
+ The fwscanf function executes each directive of the format in turn. If a\r
+ directive fails, as detailed below, the function returns. Failures are\r
+ described as input failures (due to the occurrence of an encoding error\r
+ or the unavailability of input characters), or matching failures\r
+ (due to inappropriate input).\r
+\r
+ A directive composed of white-space wide character(s) is executed by\r
+ reading input up to the first non-white-space wide character (which remains\r
+ unread), or until no more wide characters can be read.\r
+\r
+ A directive that is an ordinary wide character is executed by reading the\r
+ next wide character of the stream. If that wide character differs from the\r
+ directive, the directive fails and the differing and subsequent wide\r
+ characters remain unread. Similarly, if end-of-file, an encoding error, or\r
+ a read error prevents a wide character from being read, the directive fails.\r
+\r
+ A directive that is a conversion specification defines a set of matching\r
+ input sequences, as described below for each specifier. A conversion\r
+ specification is executed in the following steps:\r
+ - Input white-space wide characters (as specified by the iswspace\r
+ function) are skipped, unless the specification includes\r
+ a [, c, or n specifier.\r
+ - An input item is read from the stream, unless the specification\r
+ includes an n specifier. An input item is defined as the longest\r
+ sequence of input wide characters which does not exceed any specified\r
+ field width and which is, or is a prefix of, a matching input sequence.\r
+ The first wide character, if any, after the input item remains unread.\r
+ If the length of the input item is zero, the execution of the directive\r
+ fails; this condition is a matching failure unless end-of-file, an\r
+ encoding error, or a read error prevented input from the stream, in\r
+ which case it is an input failure.\r
+ - Except in the case of a % specifier, the input item (or, in the case of\r
+ a %n directive, the count of input wide characters) is converted to a\r
+ type appropriate to the conversion specifier. If the input item is not\r
+ a matching sequence, the execution of the directive fails: this\r
+ condition is a matching failure. Unless assignment suppression was\r
+ indicated by a *, the result of the conversion is placed in the object\r
+ pointed to by the first argument following the format argument that has\r
+ not already received a conversion result. If this object does not have\r
+ an appropriate type, or if the result of the conversion cannot be\r
+ represented in the object, the behavior is undefined.\r
+\r
+ The length modifiers and their meanings are:<BR>\r
+ hh Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to signed char\r
+ or unsigned char.\r
+ h Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to short int\r
+ or unsigned short int.\r
+ l (ell) Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to long int or\r
+ unsigned long int; that a following e, E, f, F, g, or G conversion\r
+ specifier applies to an argument with type pointer to double; or\r
+ that a following c, s, or [ conversion specifier applies to an\r
+ argument with type pointer to wchar_t.\r
+ ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type\r
+ pointer to long long int or unsigned long long int.\r
+ j Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to intmax_t\r
+ or uintmax_t.\r
+ z Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to size_t or the\r
+ corresponding signed integer type.\r
+ t Specifies that a following d, i, o, u, x, X, or n conversion\r
+ specifier applies to an argument with type pointer to ptrdiff_t or\r
+ the corresponding unsigned integer type.\r
+ L Specifies that a following e, E, f, F, g, or G conversion specifier\r
+ applies to an argument with type pointer to long double.\r
+\r
+ If a length modifier appears with any conversion specifier other than as\r
+ specified above, the behavior is undefined.\r
+\r
+ The conversion specifiers and their meanings are:<BR>\r
+ d Matches an optionally signed decimal integer, whose format is the\r
+ same as expected for the subject sequence of the wcstol function\r
+ with the value 10 for the base argument. The corresponding argument\r
+ shall be a pointer to signed integer.\r
+ i Matches an optionally signed integer, whose format is the same as\r
+ expected for the subject sequence of the wcstol function with the\r
+ value 0 for the base argument. The corresponding argument shall be\r
+ a pointer to signed integer.\r
+ o Matches an optionally signed octal integer, whose format is the\r
+ same as expected for the subject sequence of the wcstoul function\r
+ with the value 8 for the base argument. The corresponding argument\r
+ shall be a pointer to unsigned integer.\r
+ u Matches an optionally signed decimal integer, whose format is the\r
+ same as expected for the subject sequence of the wcstoul function\r
+ with the value 10 for the base argument. The corresponding argument\r
+ shall be a pointer to unsigned integer.\r
+ x Matches an optionally signed hexadecimal integer, whose format is\r
+ the same as expected for the subject sequence of the wcstoul\r
+ function with the value 16 for the base argument. The corresponding\r
+ argument shall be a pointer to unsigned integer.\r
+ e,f,g Matches an optionally signed floating-point number, infinity, or\r
+ NaN, whose format is the same as expected for the subject sequence\r
+ of the wcstod function. The corresponding argument shall be a\r
+ pointer to float.\r
+ c Matches a sequence of wide characters of exactly the number\r
+ specified by the field width (1 if no field width is present in the\r
+ directive).<BR>\r
+ If no l length modifier is present, characters from the input field\r
+ are converted as if by repeated calls to the wcrtomb function, with\r
+ the conversion state described by an mbstate_t object initialized\r
+ to zero before the first wide character is converted. The\r
+ corresponding argument shall be a pointer to the initial element of\r
+ a character array large enough to accept the sequence. No null\r
+ character is added.<BR>\r
+ If an l length modifier is present, the corresponding argument\r
+ shall be a pointer to the initial element of an array of\r
+ wchar_t large enough to accept the sequence.\r
+ No null wide character is added.\r
+ s Matches a sequence of non-white-space wide characters.\r
+ If no l length modifier is present, characters from the input field\r
+ are converted as if by repeated calls to the wcrtomb function, with\r
+ the conversion state described by an mbstate_t object initialized\r
+ to zero before the first wide character is converted. The\r
+ corresponding argument shall be a pointer to the initial element of\r
+ a character array large enough to accept the sequence and a\r
+ terminating null character, which will be added automatically.<BR>\r
+ If an l length modifier is present, the corresponding argument\r
+ shall be a pointer to the initial element of an array of wchar_t\r
+ large enough to accept the sequence and the terminating null wide\r
+ character, which will be added automatically.\r
+ [ Matches a nonempty sequence of wide characters from a set of\r
+ expected characters (the scanset).<BR>\r
+ If no l length modifier is present, characters from the input field\r
+ are converted as if by repeated calls to the wcrtomb function, with\r
+ the conversion state described by an mbstate_t object initialized\r
+ to zero before the first wide character is converted. The\r
+ corresponding argument shall be a pointer to the initial element of\r
+ a character array large enough to accept the sequence and a\r
+ terminating null character, which will be added automatically.<BR>\r
+ If an l length modifier is present, the corresponding argument\r
+ shall be a pointer to the initial element of an array of wchar_t\r
+ large enough to accept the sequence and the terminating null wide\r
+ character, which will be added automatically.<BR>\r
+ The conversion specifier includes all subsequent wide characters\r
+ in the format string, up to and including the matching right\r
+ bracket (]). The wide characters between the brackets\r
+ (the scanlist) compose the scanset, unless the wide character after\r
+ the left bracket is a circumflex (^), in which case the scanset\r
+ contains all wide characters that do not appear in the scanlist\r
+ between the circumflex and the right bracket. If the conversion\r
+ specifier begins with [] or [^], the right bracket wide character\r
+ is in the scanlist and the next following right bracket wide\r
+ character is the matching right bracket that ends the specification;\r
+ otherwise the first following right bracket wide character is the\r
+ one that ends the specification. If a - wide character is in the\r
+ scanlist and is not the first, nor the second where the first wide\r
+ character is a ^, nor the last character,\r
+ the - is added to the scanset.\r
+ p Matches the set of sequences produced by the %p conversion of the\r
+ fwprintf function. The corresponding argument is a pointer to a\r
+ pointer to void. The input item is converted to a pointer value. If\r
+ the input item is a value converted earlier during the same program\r
+ execution, the pointer that results will compare equal to that\r
+ value.\r
+ n No input is consumed. The corresponding argument is a pointer to\r
+ signed integer into which is to be written the number of wide\r
+ characters read from the input stream so far by this call to the\r
+ fwscanf function. Execution of a %n directive does not increment\r
+ the assignment count returned at the completion of execution of the\r
+ fwscanf function. No argument is converted, but one is consumed.\r
+ % Matches a single % wide character; no conversion or assignment\r
+ occurs. The complete conversion specification shall be %%.\r
+\r
+ The conversion specifiers E, F, G, and X are also valid and behave the same\r
+ as, respectively, e, f, g, and x.\r
+\r
+ Trailing white space (including new-line wide characters) is left unread\r
+ unless matched by a directive. The success of literal matches and\r
+ suppressed assignments is not directly determinable other than via\r
+ the %n directive.\r
+\r
+ @param[in] stream An open File specifier from which the input is read.\r
+ @param[in] format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments. Converted\r
+ items are stored according to their associated arguments.\r
+ @param ... Variable number of parameters, as required by format,\r
+ specifying the objects to receive the converted input.\r
+\r
+ @return The fwscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ function returns the number of input items assigned, which can be\r
+ fewer than provided for, or even zero, in the event of an early\r
+ matching failure.\r
**/\r
int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);\r
\r
-/**\r
-The swprintf function is equivalent to fwprintf, except that the argument s\r
-specifies an array of wide characters into which the generated output is to be written,\r
-rather than written to a stream. No more than n wide characters are written, including a\r
-terminating null wide character, which is always added (unless n is zero).\r
-\r
-The swprintf function returns the number of wide characters written in the array, not\r
-counting the terminating null wide character, or a neg ative value if an encoding error\r
-occurred or if n or more wide characters were requested to be written.\r
+/** Formatted wide-character output to a buffer.\r
+\r
+ The swprintf function is equivalent to fwprintf, except that the argument s\r
+ specifies an array of wide characters into which the generated output is to\r
+ be written, rather than written to a stream. No more than n wide characters\r
+ are written, including a terminating null wide character, which is always\r
+ added (unless n is zero).\r
+\r
+ @param[out] s A pointer to the array to receive the formatted output.\r
+ @param[in] n Maximum number of characters to write into buffer s.\r
+ @param[in] format A wide character sequence containing characters\r
+ to be copied unchanged, and conversion specifiers\r
+ which convert their associated arguments. Copied and\r
+ converted characters are written to the array pointed\r
+ to by s.\r
+ @param ... Variable number of parameters as required by format.\r
+\r
+ @return The swprintf function returns the number of wide characters\r
+ written in the array, not counting the terminating null wide\r
+ character, or a negative value if an encoding error occurred or\r
+ if n or more wide characters were requested to be written.\r
**/\r
int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);\r
\r
-/**\r
+/** Formatted wide input from a string.\r
+\r
+ The swscanf function is equivalent to fwscanf, except that the argument\r
+ Buff specifies a wide string from which the input is to be obtained, rather\r
+ than from a stream. Reaching the end of the wide string is equivalent to\r
+ encountering end-of-file for the fwscanf function.\r
+\r
+ @param[in] Buff Pointer to the string from which to obtain input.\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[out] ... Variable number of parameters, as required by format,\r
+ specifying the objects to receive the converted input.\r
+\r
+ @return The swscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ swscanf function returns the number of input items assigned,\r
+ which can be fewer than provided for, or even zero, in the event\r
+ of an early matching failure.\r
**/\r
-int swscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, ...);\r
-\r
-/**\r
+int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);\r
+\r
+/** Print formatted values from an argument list.\r
+\r
+The vfwprintf function is equivalent to fwprintf, with the variable argument list\r
+replaced by Args, which shall have been initialized by the va_start macro (and\r
+possibly subsequent va_arg calls). The vfwprintf function does not invoke the\r
+va_end macro.\r
+\r
+ @param[in] Stream The output stream to receive the formatted output.\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[in] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vfwprintf function returns the number of wide characters\r
+ transmitted, or a negative value if an output or encoding\r
+ error occurred.\r
**/\r
-int vfwprintf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);\r
-\r
-/**\r
+int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);\r
+\r
+/** Formatted input from a stream.\r
+\r
+ The vfwscanf function is equivalent to fwscanf, with the variable argument\r
+ list replaced by Args, which must have been initialized by the va_start\r
+ macro (and possibly subsequent va_arg calls). The vfwscanf function does\r
+ not invoke the va_end macro.\r
+\r
+ @param[in] Stream The input stream.\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[in] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vfwscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ vfwscanf function returns the number of input items assigned,\r
+ which can be fewer than provided for, or even zero, in the event\r
+ of an early matching failure.\r
**/\r
-int vfwscanf(FILE * __restrict stream, const wchar_t * __restrict format, va_list arg);\r
-\r
-/**\r
+int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);\r
+\r
+/** Formatted print, to a buffer, from an argument list.\r
+\r
+ The vswprintf function is equivalent to swprintf, with the variable\r
+ argument list replaced by Args, which must have been initialized by the\r
+ va_start macro (and possibly subsequent va_arg calls). The vswprintf\r
+ function does not invoke the va_end macro.\r
+\r
+ @param[in] S A pointer to the array to receive the formatted output.\r
+ @param[in] N Maximum number of characters to write into array S.\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[in] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vswprintf function returns the number of wide characters\r
+ written in the array, not counting the terminating null wide\r
+ character, or a neg ative value if an encoding error occurred or\r
+ if n or more wide characters were requested to be generated.\r
**/\r
-int vswprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, va_list arg);\r
-\r
-/**\r
+int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);\r
+\r
+/** Formatted input from a string, using an argument list.\r
+\r
+ The vswscanf function is equivalent to swscanf, with the variable argument\r
+ list replaced by Args, which must have been initialized by the va_start\r
+ macro. The vswscanf function does not invoke the va_end macro.\r
+\r
+ @param[in] S Pointer to the string from which to obtain input.\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[out] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vswscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ vswscanf function returns the number of input items assigned,\r
+ which can be fewer than provided for, or even zero, in the event\r
+ of an early matching failure.\r
**/\r
-int vswscanf(const wchar_t * __restrict s, const wchar_t * __restrict format, va_list arg);\r
+int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);\r
\r
-/**\r
-**/\r
-int vwprintf(const wchar_t * __restrict format, va_list arg);\r
+/** Formatted print, to stdout, from an argument list.\r
\r
-/**\r
+ The vwprintf function is equivalent to wprintf, with the variable argument\r
+ list replaced by Args, which must have been initialized by the va_start\r
+ macro. The vwprintf function does not invoke the va_end macro.\r
+\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[out] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vwprintf function returns the number of wide characters\r
+ transmitted, or a negative value if an output or encoding error\r
+ occurred.\r
**/\r
-int vwscanf(const wchar_t * __restrict format, va_list arg);\r
+int vwprintf(const wchar_t * __restrict Format, va_list Args);\r
+\r
+/** Formatted input, from stdin, to an argument list.\r
+\r
+ The vwscanf function is equivalent to wscanf, with the variable argument\r
+ list replaced by arg, which shall have been initialized by the va_start\r
+ macro. The vwscanf function does not invoke the va_end macro.\r
+\r
+ @param[in] Format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param[out] Args A list of arguments, initialized by the va_start macro\r
+ and accessed using the va_arg macro, used to satisfy\r
+ the directives in the Format string.\r
+\r
+ @return The vwscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ vwscanf function returns the number of input items assigned,\r
+ which can be fewer than provided for, or even zero, in the event\r
+ of an early matching failure.\r
+**/\r
+int vwscanf(const wchar_t * __restrict Format, va_list Args);\r
\r
-/**\r
+/** Formatted print to stdout.\r
+\r
+ The wprintf function is equivalent to fwprintf with the argument stdout\r
+ specifying the output stream.\r
+\r
+ @param[in] format A wide character sequence containing characters\r
+ to be copied unchanged, and conversion specifiers\r
+ which convert their associated arguments.\r
+ @param ... Variable number of parameters as required by format.\r
+\r
+ @return The wprintf function returns the number of wide characters\r
+ transmitted, or a negative value if an output or encoding error\r
+ occurred.\r
**/\r
-int wprintf(const wchar_t * __restrict format, ...);\r
+int wprintf(const wchar_t * __restrict Format, ...);\r
\r
-/**\r
+/** Formatted input from stdin.\r
+\r
+ The wscanf function is equivalent to fwscanf with the argument stdin\r
+ specifying the input stream.\r
+\r
+ @param[in] format A wide character sequence containing characters\r
+ to be matched against, and conversion specifiers\r
+ which convert their associated arguments. Converted\r
+ items are stored according to their associated arguments.\r
+ @param ... Variable number of parameters, as required by format,\r
+ specifying the objects to receive the converted input.\r
+\r
+ @return The wscanf function returns the value of the macro EOF if an\r
+ input failure occurs before any conversion. Otherwise, the\r
+ wscanf function returns the number of input items assigned,\r
+ which can be fewer than provided for, or even zero, in the event\r
+ of an early matching failure.\r
**/\r
int wscanf(const wchar_t * __restrict format, ...);\r
\r
/* ################### Input/Output Functions ########################### */\r
\r
\r
-/**\r
-**/\r
-wint_t fgetwc(FILE *stream);\r
+/** Get a character from an input Stream.\r
\r
-/**\r
+If the end-of-file indicator for the input stream pointed to by stream is not set and a\r
+next wide character is present, the fgetwc function obtains that wide character as a\r
+wchar_t converted to a wint_t and advances the associated file position indicator for\r
+the stream (if defined).\r
+\r
+ @param[in] Stream An input stream from which to obtain a character.\r
+\r
+ @return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-\r
+file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,\r
+the fgetwc function returns the next wide character from the input stream pointed to by\r
+stream. If a read error occurs, the error indicator for the stream is set and the fgetwc\r
+function returns WEOF. If an encoding error occurs (including too few bytes), the value of\r
+the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.\r
**/\r
-wchar_t *fgetws(wchar_t * __restrict s, int n, FILE * __restrict stream);\r
+wint_t fgetwc(FILE *Stream);\r
+\r
+/** Read a string from an input stream into a buffer.\r
+\r
+ The fgetws function reads at most one less than the number of\r
+ wide characters specified by n from the stream pointed to by\r
+ stream into the array pointed to by s. No additional wide\r
+ characters are read after a new-line wide character (which is\r
+ retained) or after end-of-file. A null wide character is written\r
+ immediately after the last wide character read into the array.\r
+\r
+ @param[out] S A pointer to the array to receive the input string.\r
+ @param[in] Limit The maximum number of characters to put into Buff,\r
+ including the terminating null character.\r
+ @param[in] Stream An input stream from which to obtain the string.\r
+\r
+ @return The fgetws function returns S if successful. If end-of-file is\r
+ encountered and no characters have been read into the array, the\r
+ contents of the array remain unchanged and a null pointer is\r
+ returned. If a read or encoding error occurs during the\r
+ operation, the array contents are indeterminate and a\r
+ null pointer is returned.\r
+**/\r
+wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);\r
\r
-/**\r
+/** Write a character to an output stream.\r
+\r
+The fputwc function writes the wide character specified by c to the output stream\r
+pointed to by stream, at the position indicated by the associated file position indicator\r
+for the stream (if defined), and advances the indicator appropriately. If the file cannot\r
+support positioning requests, or if the stream was opened with append mode, the\r
+character is appended to the output stream.\r
+\r
+ @param[in] C The character to be written to Stream.\r
+ @param[in] Stream The output stream that C is to be written to.\r
+\r
+ @return The fputwc function returns the wide character written. If a write error occurs, the\r
+error indicator for the stream is set and fputwc returns WEOF. If an encoding error\r
+occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.\r
**/\r
-wint_t fputwc(wchar_t c, FILE *stream);\r
+wint_t fputwc(wchar_t C, FILE *Stream);\r
\r
-/**\r
+/** Write a string to an output stream.\r
+\r
+The fputws function writes the wide string pointed to by S to the stream pointed to by\r
+Stream. The terminating null wide character is not written.\r
+\r
+ @param[in] String The character string to be written to Stream.\r
+ @param[in] Stream The output stream that String is to be written to.\r
+\r
+ @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it\r
+returns a nonnegative value.\r
**/\r
-int fputws(const wchar_t * __restrict s, FILE * __restrict stream);\r
+int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);\r
\r
-/**\r
+/** Query or set a stream's orientation.\r
+\r
+The fwide function determines the orientation of the stream pointed to by stream. If\r
+Mode is greater than zero, the function first attempts to make the stream wide oriented. If\r
+Mode is less than zero, the function first attempts to make the stream byte oriented.\r
+Otherwise, Mode is zero and the function does not alter the orientation of the stream.\r
+\r
+ @param[in] Stream The stream to be queried.\r
+ @param[in] Mode Control value selecting between quering or setting\r
+ the Stream's orientation.\r
+ @return The fwide function returns a value greater than zero if, after the call, the stream has\r
+wide orientation, a value less than zero if the stream has byte orientation, or zero if the\r
+stream has no orientation.\r
**/\r
-int fwide(FILE *stream, int mode);\r
+int fwide(FILE *Stream, int Mode);\r
\r
-/**\r
+/** Get a character from an input stream.\r
+\r
+The getwc function is equivalent to fgetwc, except that if it is implemented as a\r
+macro, it may evaluate Stream more than once, so the argument should never be an\r
+expression with side effects.\r
+\r
+ @param[in] Stream The stream to be read.\r
+\r
+ @return The getwc function returns the next wide character from the input stream pointed to by\r
+stream, or WEOF.\r
**/\r
-wint_t getwc(FILE *stream);\r
+wint_t getwc(FILE *Stream);\r
\r
-/**\r
+/** Get a character from stdin.\r
+\r
+ The getwchar function is equivalent to getwc with the argument stdin.\r
+\r
+ @return The getwchar function returns the next wide character from the\r
+ input stream pointed to by stdin, or WEOF.\r
**/\r
wint_t getwchar(void);\r
\r
-/**\r
-**/\r
-wint_t putwc(wchar_t c, FILE *stream);\r
+/** Write a character to an output stream.\r
\r
-/**\r
-**/\r
-wint_t putwchar(wchar_t c);\r
+The putwc function is equivalent to fputwc, except that if it is implemented as a\r
+macro, it may evaluate Stream more than once, so the Stream argument should never be an\r
+expression with side effects.\r
\r
-/**\r
+ @param[in] C The wide character to be written to Stream.\r
+ @param[in] Stream The output stream that C is to be written to.\r
+\r
+ @return The putwc function returns the wide character written, or WEOF.\r
**/\r
-wint_t ungetwc(wint_t c, FILE *stream);\r
+wint_t putwc(wchar_t C, FILE *Stream);\r
\r
-/* ################### Numeric Conversions ########################### */\r
+/** Write a character to stdout.\r
\r
-/**\r
-**/\r
-double wcstod(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
+The putwchar function is equivalent to putwc with the second argument stdout.\r
\r
-/**\r
-**/\r
-float wcstof(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
+ @param[in] C The wide character to be written to stdout.\r
\r
-/**\r
+ @return The putwchar function returns the character written, or WEOF.\r
**/\r
-long double wcstold(const wchar_t * __restrict nptr, wchar_t ** __restrict endptr);\r
-\r
-/**\r
+wint_t putwchar(wchar_t C);\r
+\r
+/** Return a character to the input Stream as if it had not been read.\r
+\r
+The ungetwc function pushes the wide character specified by C back onto the input\r
+stream pointed to by Stream. Pushed-back wide characters will be returned by\r
+subsequent reads on that stream in the reverse order of their pushing. A successful\r
+intervening call (with the stream pointed to by Stream) to a file positioning function\r
+(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the\r
+stream. The external storage corresponding to the stream is unchanged.\r
+\r
+One wide character of pushback is guaranteed, even if the call to the ungetwc function\r
+follows just after a call to a formatted wide character input function fwscanf,\r
+vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times\r
+on the same stream without an intervening read or file positioning operation on that\r
+stream, the operation may fail.\r
+\r
+If the value of C equals that of the macro WEOF, the operation fails and the input stream is\r
+unchanged.\r
+\r
+A successful call to the ungetwc function clears the end-of-file indicator for the stream.\r
+The value of the file position indicator for the stream after reading or discarding all\r
+pushed-back wide characters is the same as it was before the wide characters were pushed\r
+back. For a text or binary stream, the value of its file position indicator after a successful\r
+call to the ungetwc function is unspecified until all pushed-back wide characters are\r
+read or discarded.\r
+\r
+ @param[in] C The wide character to push back onto the Stream.\r
+ @param[in] Stream The output stream that C is to be pushed back onto.\r
+\r
+ @return The ungetwc function returns the character pushed back,\r
+ or WEOF if the operation fails.\r
**/\r
-long int wcstol( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
+wint_t ungetwc(wint_t C, FILE *Stream);\r
\r
-/**\r
-**/\r
-long long int wcstoll( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
+/* ################### Numeric Conversions ########################### */\r
\r
-/**\r
+/** @{\r
+The wcstod, wcstof, and wcstold functions convert the initial portion of the wide\r
+string pointed to by nptr to double, float, and long double representation,\r
+respectively. First, they decompose the input string into three parts: an initial, possibly\r
+empty, sequence of white-space wide characters (as specified by the iswspace\r
+function), a subject sequence resembling a floating-point constant or representing an\r
+infinity or NaN; and a final wide string of one or more unrecognized wide characters,\r
+including the terminating null wide character of the input wide string. Then, they attempt\r
+to convert the subject sequence to a floating-point number, and return the result.\r
+\r
+ @param[in] Nptr Pointer to the string to convert to a floating-point value.\r
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer\r
+ to the final wide string.\r
+\r
+The functions return the converted value, if any. If no conversion could be performed,\r
+zero is returned. If the correct value is outside the range of representable values, plus or\r
+minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return\r
+type and sign of the value), and the value of the macro ERANGE is stored in errno. If\r
+the result underflows (7.12.1), the functions return a value whose magnitude is no greater\r
+than the smallest normalized positive number in the return type. A pointer to the\r
+final wide string is stored in the object pointed to by endptr, provided that endptr is\r
+not a null pointer.\r
**/\r
-unsigned long int wcstoul( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
-\r
-/**\r
+double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);\r
+float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);\r
+long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);\r
+/*@}*/\r
+\r
+/** @{\r
+The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial\r
+portion of the wide string pointed to by nptr to long int, long long int,\r
+unsigned long int, and unsigned long long int representation,\r
+respectively. First, they decompose the input string into three parts: an initial, possibly\r
+empty, sequence of white-space wide characters (as specified by the iswspace\r
+function), a subject sequence resembling an integer represented in some radix determined\r
+by the value of base, and a final wide string of one or more unrecognized wide\r
+characters, including the terminating null wide character of the input wide string. Then,\r
+they attempt to convert the subject sequence to an integer, and return the result.\r
+\r
+ @param[in] Nptr Pointer to the string to convert.\r
+ @param[in] EndPtr Optional pointer to an object in which to store a pointer\r
+ to the final wide string.\r
+ @param[in] Base Base, 0 to 36, of the value represented by the string\r
+ pointed to by Nptr.\r
+\r
+ @return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted\r
+value, if any. If no conversion could be performed, zero is returned. If the correct value\r
+is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,\r
+LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type\r
+sign of the value, if any), and the value of the macro ERANGE is stored in errno.\r
**/\r
-unsigned long long int wcstoull( const wchar_t * __restrict nptr, wchar_t ** __restrict endptr, int base);\r
+long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);\r
+long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);\r
+unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);\r
+unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);\r
+/*@}*/\r
\r
/* ####################### String Copying ############################### */\r
\r
-/** The wcscpy function copies the wide string pointed to by s2 (including the\r
- terminating null wide character) into the array pointed to by s1.\r
+/** The wcscpy function copies the wide string pointed to by Src (including the\r
+ terminating null wide character) into the array pointed to by Dest.\r
\r
- @return The wcscpy function returns the value of s1.\r
+ @return The wcscpy function returns the value of Dest.\r
**/\r
-wchar_t *wcscpy(wchar_t * __restrict s1, const wchar_t * __restrict s2);\r
+wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);\r
\r
/** The wcsncpy function copies not more than n wide characters (those that\r
follow a null wide character are not copied) from the array pointed to by\r
- s2 to the array pointed to by s1.\r
+ Src to the array pointed to by Dest.\r
\r
- If the array pointed to by s2 is a wide string that is shorter than n wide\r
+ If the array pointed to by Src is a wide string that is shorter than n wide\r
characters, null wide characters are appended to the copy in the array\r
- pointed to by s1, until n wide characters in all have been written.\r
+ pointed to by Dest, until n wide characters in all have been written.\r
\r
- @return The wcsncpy function returns the value of s1.\r
+ @return The wcsncpy function returns the value of Dest.\r
**/\r
-wchar_t *wcsncpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
+wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);\r
\r
/** The wmemcpy function copies n wide characters from the object pointed to by\r
- s2 to the object pointed to by s1.\r
+ Src to the object pointed to by Dest.\r
\r
- Use this function if you know that s1 and s2 DO NOT Overlap. Otherwise,\r
+ Use this function if you know that Dest and Src DO NOT Overlap. Otherwise,\r
use wmemmove.\r
\r
- @return The wmemcpy function returns the value of s1.\r
+ @return The wmemcpy function returns the value of Dest.\r
**/\r
-wchar_t *wmemcpy(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
+wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);\r
\r
/** The wmemmove function copies n wide characters from the object pointed to by\r
- s2 to the object pointed to by s1. The objects pointed to by s1 and s2 are\r
+ Src to the object pointed to by Dest. The objects pointed to by Dest and Src are\r
allowed to overlap.\r
\r
Because the UEFI BaseMemoryLib function CopyMem explicitly handles\r
implemented identically.\r
\r
For programming clarity, it is recommended that you use wmemcpy if you know\r
- that s1 and s2 DO NOT Overlap. If s1 and s2 might possibly overlap, then\r
+ that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then\r
use wmemmove.\r
\r
- @return The wmemmove function returns the value of s1.\r
+ @return The wmemmove function returns the value of Dest.\r
**/\r
-wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2, size_t n);\r
+wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);\r
\r
/* ################### String Concatenation ########################## */\r
\r
-/** The wcscat function appends a copy of the wide string pointed to by s2\r
+/** The wcscat function appends a copy of the wide string pointed to by Src\r
(including the terminating null wide character) to the end of the wide\r
- string pointed to by s1. The initial wide character of s2 overwrites the\r
- null wide character at the end of s1.\r
+ string pointed to by Dest. The initial wide character of Src overwrites the\r
+ null wide character at the end of Dest.\r
\r
- @return The wcscat function returns the value of s1.\r
+ @return The wcscat function returns the value of Dest.\r
**/\r
-wchar_t *wcscat(wchar_t * __restrict s1, const wchar_t * __restrict s2);\r
+wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);\r
\r
/** The wcsncat function appends not more than n wide characters (a null wide\r
character and those that follow it are not appended) from the array pointed\r
- to by s2 to the end of the wide string pointed to by s1. The initial wide\r
- character of s2 overwrites the null wide character at the end of s1.\r
+ to by Src to the end of the wide string pointed to by Dest. The initial wide\r
+ character of Src overwrites the null wide character at the end of Dest.\r
A terminating null wide character is always appended to the result.\r
\r
- @return The wcsncat function returns the value of s1.\r
+ @return The wcsncat function returns the value of Dest.\r
**/\r
-wchar_t *wcsncat(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);\r
+wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);\r
\r
/* ##################### String Comparison ############################# */\r
\r
\r
/* ##################### String Searching ############################## */\r
\r
-/** The wcschr function locates the first occurrence of c in the wide string\r
- pointed to by s. The terminating null wide character is considered to be\r
+/** The wcschr function locates the first occurrence of C in the wide string\r
+ pointed to by S. The terminating null wide character is considered to be\r
part of the wide string.\r
\r
@return The wcschr function returns a pointer to the located wide\r
character, or a null pointer if the wide character does not occur\r
in the wide string.\r
**/\r
-wchar_t *wcschr(const wchar_t *s, wchar_t c);\r
+wchar_t *wcschr(const wchar_t *S, wchar_t C);\r
\r
/** The wcscspn function computes the length of the maximum initial segment of\r
the wide string pointed to by s1 which consists entirely of wide characters\r
**/\r
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);\r
\r
-/** The wcsrchr function locates the last occurrence of c in the wide string\r
- pointed to by s. The terminating null wide character is considered to be\r
+/** The wcsrchr function locates the last occurrence of C in the wide string\r
+ pointed to by S. The terminating null wide character is considered to be\r
part of the wide string.\r
\r
@return The wcsrchr function returns a pointer to the wide character,\r
- or a null pointer if c does not occur in the wide string.\r
+ or a null pointer if C does not occur in the wide string.\r
**/\r
-wchar_t *wcsrchr(const wchar_t *s, wchar_t c);\r
+wchar_t *wcsrchr(const wchar_t *S, wchar_t C);\r
\r
/** The wcsspn function computes the length of the maximum initial segment of\r
the wide string pointed to by s1 which consists entirely of wide characters\r
**/\r
wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);\r
\r
-/** The wmemchr function locates the first occurrence of c in the initial n\r
- wide characters of the object pointed to by s.\r
+/** The wmemchr function locates the first occurrence of C in the initial n\r
+ wide characters of the object pointed to by S.\r
\r
@return The wmemchr function returns a pointer to the located wide\r
character, or a null pointer if the wide character does not occur\r
in the object.\r
**/\r
-wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);\r
+wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n);\r
\r
/* ################### String Manipulation ############################# */\r
\r
-/** The wcslen function computes the length of the wide string pointed to by s.\r
+/** The wcslen function computes the length of the wide string pointed to by S.\r
\r
@return The wcslen function returns the number of wide characters that\r
precede the terminating null wide character.\r
**/\r
-size_t wcslen(const wchar_t *s);\r
+size_t wcslen(const wchar_t *S);\r
\r
-/** The wmemset function copies the value of c into each of the first n wide\r
- characters of the object pointed to by s.\r
+/** The wmemset function copies the value of C into each of the first n wide\r
+ characters of the object pointed to by S.\r
\r
- @return The wmemset function returns the value of s.\r
+ @return The wmemset function returns the value of S.\r
**/\r
-wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);\r
+wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n);\r
\r
/* ################# Date and Time Conversion ########################### */\r
\r
/**\r
+The wcsftime function is equivalent to the strftime function, except that:\r
+ - The argument s points to the initial element of an array of wide characters into which\r
+the generated output is to be placed.\r
+ - The argument maxsize indicates the limiting number of wide characters.\r
+ - The argument format is a wide string and the conversion specifiers are replaced by\r
+corresponding sequences of wide characters.\r
+ - The return value indicates the number of wide characters.\r
+\r
+If the total number of resulting wide characters including the terminating null wide\r
+character is not more than maxsize, the wcsftime function returns the number of\r
+wide characters placed into the array pointed to by s not including the terminating null\r
+wide character. Otherwise, zero is returned and the contents of the array are\r
+indeterminate.\r
**/\r
-size_t wcsftime(wchar_t * __restrict s, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);\r
+size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);\r
\r
/* ############# Multibyte <--> Wide Character Conversion ############### */\r
\r
-/**\r
+/** The btowc function determines whether C constitutes a valid single-byte\r
+ character in the initial shift state.\r
+\r
+ @return The btowc function returns WEOF if c has the value EOF or if\r
+ (unsigned char)C does not constitute a valid single-byte\r
+ character in the initial shift state. Otherwise, it returns the\r
+ wide character representation of that character.\r
**/\r
-wint_t btowc(int c);\r
+wint_t btowc(int C);\r
\r
-/** The wctob function determines whether c corresponds to a member of the extended\r
+/** The wctob function determines whether C corresponds to a member of the extended\r
character set whose multibyte character representation is a single byte when in the initial\r
shift state.\r
\r
- @return The wctob function returns EOF if c does not correspond to a multibyte\r
+ @return The wctob function returns EOF if C does not correspond to a multibyte\r
character with length one in the initial shift state. Otherwise, it\r
returns the single-byte representation of that character as an\r
unsigned char converted to an int.\r
**/\r
-int wctob(wint_t c);\r
+int wctob(wint_t C);\r
\r
/** If ps is not a null pointer, the mbsinit function determines whether the\r
pointed-to mbstate_t object describes an initial conversion state.\r
\r
/* ####### Restartable Multibyte <--> Wide Character Conversion ######### */\r
\r
-/**\r
+/** The mbrlen function is equivalent to the call:<BR>\r
+@verbatim\r
+ mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)\r
+@endverbatim\r
+ where internal is the mbstate_t object for the mbrlen function, except that\r
+ the expression designated by ps is evaluated only once.\r
+\r
+ @param[in] s Pointer to a multibyte character sequence.\r
+ @param[in] n Maximum number of bytes to examine.\r
+ @param[in] pS Pointer to the conversion state object.\r
+\r
+ @retval 0 The next n or fewer characters complete a NUL.\r
+ @retval 1..n The number of bytes that complete the multibyte character.\r
+ @retval -2 The next n bytes contribute to an incomplete (but potentially valid) multibyte character.\r
+ @retval -1 An encoding error occurred.\r
**/\r
-size_t mbrlen(const char * __restrict s, size_t n, mbstate_t * __restrict ps);\r
-\r
-/**\r
+size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict pS);\r
+\r
+/** Restartable Multibyte to Wide character conversion.\r
+If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>\r
+@verbatim\r
+ mbrtowc(NULL, "", 1, ps)\r
+@endverbatim\r
+\r
+In this case, the values of the parameters pwc and n are ignored.\r
+\r
+If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with\r
+the byte pointed to by S to determine the number of bytes needed to complete the next\r
+multibyte character (including any shift sequences). If the function determines that the\r
+next multibyte character is complete and valid, it determines the value of the\r
+corresponding wide character and then, if pwc is not a null pointer, stores that value in\r
+the object pointed to by pwc. If the corresponding wide character is the null wide\r
+character, the resulting state described is the initial conversion state.\r
+\r
+ @retval 0 if the next n or fewer bytes complete the multibyte\r
+ character that corresponds to the null wide\r
+ character (which is the value stored).\r
+ @retval between_1_and_n_inclusive if the next n or fewer bytes complete\r
+ a valid multibyte character (which is the value\r
+ stored); the value returned is the number of bytes\r
+ that complete the multibyte character.\r
+ @retval (size_t)(-2) if the next n bytes contribute to an incomplete\r
+ (but potentially valid) multibyte character, and\r
+ all n bytes have been processed (no value is stored).\r
+ @retval (size_t)(-1) if an encoding error occurs, in which case the next\r
+ n or fewer bytes do not contribute to a complete and\r
+ valid multibyte character (no value is stored); the\r
+ value of the macro EILSEQ is stored in errno, and\r
+ the conversion state is unspecified.\r
**/\r
-size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict s, size_t n, mbstate_t * __restrict ps);\r
+size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);\r
\r
/**\r
+If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>\r
+@verbatim\r
+ wcrtomb(buf, L'\0', ps)\r
+@endverbatim\r
+where buf is an internal buffer.\r
+\r
+If S is not a null pointer, the wcrtomb function determines the number of bytes needed\r
+to represent the multibyte character that corresponds to the wide character given by wc\r
+(including any shift sequences), and stores the multibyte character representation in the\r
+array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If\r
+wc is a null wide character, a null byte is stored, preceded by any shift sequence needed\r
+to restore the initial shift state; the resulting state described is the initial conversion state.\r
+\r
+ @return The wcrtomb function returns the number of bytes stored in the\r
+ array object (including any shift sequences). When wc is not a\r
+ valid wide character, an encoding error occurs: the function\r
+ stores the value of the macro EILSEQ in errno and\r
+ returns (size_t)(-1); the conversion state is unspecified.\r
**/\r
-size_t wcrtomb(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps);\r
-\r
-/**\r
+size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);\r
+\r
+/** Convert a sequence of multibyte characters into a sequence of wide characters.\r
+ The mbsrtowcs function converts a sequence of multibyte characters that begins in the\r
+ conversion state described by the object pointed to by ps, from the array indirectly\r
+ pointed to by src into a sequence of corresponding wide characters. If dst is not a null\r
+ pointer, the converted characters are stored into the array pointed to by dst. Conversion\r
+ continues up to and including a terminating null character, which is also stored.\r
+ Conversion stops earlier in two cases: when a sequence of bytes is encountered that does\r
+ not form a valid multibyte character, or (if dst is not a null pointer) when len wide\r
+ characters have been stored into the array pointed to by dst. Each conversion takes\r
+ place as if by a call to the mbrtowc function.\r
+\r
+ If dst is not a null pointer, the pointer object pointed to by src is assigned either a null\r
+ pointer (if conversion stopped due to reaching a terminating null character) or the address\r
+ just past the last multibyte character converted (if any). If conversion stopped due to\r
+ reaching a terminating null character and if dst is not a null pointer, the resulting state\r
+ described is the initial conversion state.\r
+\r
+ @param[in] dst Destination for the Wide character sequence.\r
+ @param[in] src Pointer to Pointer to MBCS char. sequence to convert.\r
+ @param[in] len Length of dest, in WIDE characters.\r
+ @param[in] ps Pointer to the conversion state object to be used for this conversion.\r
+\r
+ @return If the input conversion encounters a sequence of bytes that do\r
+ not form a valid multibyte character, an encoding error occurs:\r
+ the mbsrtowcs function stores the value of the macro EILSEQ in\r
+ errno and returns (size_t)(-1); the conversion state is\r
+ unspecified. Otherwise, it returns the number of multibyte\r
+ characters successfully converted, not including the terminating\r
+ null character (if any).\r
**/\r
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);\r
\r
terminating null wide character, the resulting state described is the\r
initial conversion state.\r
\r
+ @param[in] dst Destination for the MBCS sequence.\r
+ @param[in] src Pointer to Pointer to wide char. sequence to convert.\r
+ @param[in] len Length of dest, in bytes.\r
+ @param[in] ps Pointer to the conversion state object to be used for this conversion.\r
+\r
@return If conversion stops because a wide character is reached that\r
does not correspond to a valid multibyte character, an\r
encoding error occurs: the wcsrtombs function stores the\r
projects / mirror_edk2.git / blobdiff