1 /** @file 2 Extended multibyte and wide character utilities. 3 4 Within this implementation, multibyte characters are represented using the 5 Unicode UTF-8 encoding and wide characters are represented using the 6 16-bit UCS-2 encoding. 7 8 Unless explicitly stated otherwise, if the execution of a function declared 9 in this file causes copying to take place between objects that overlap, the 10 behavior is undefined. 11 12 The following macros are defined in this file:<BR> 13 @verbatim 14 NULL Actually defined in <sys/EfiCdefs.h> 15 WCHAR_MIN Minimum value of a wide char. 16 WCHAR_MAX Maximum value of a wide char. 17 WEOF Wide char version of end-of-file. 18 @endverbatim 19 20 The following types are defined in this file:<BR> 21 @verbatim 22 size_t Unsigned integer type of the result of the sizeof operator. 23 wchar_t Type of wide characters. 24 wint_t Type capable of holding all wchar_t values and WEOF. 25 mbstate_t Type of object holding multibyte conversion state. 26 struct tm Incomplete declaration of the broken-down time structure. 27 @endverbatim 28 29 The following functions are declared in this file:<BR> 30 @verbatim 31 ############### Formatted Input/Output Functions 32 int fwprintf (FILE * __restrict stream, 33 const wchar_t * __restrict format, ...); 34 int fwscanf (FILE * __restrict stream, 35 const wchar_t * __restrict format, ...); 36 int swprintf (wchar_t * __restrict s, size_t n, 37 const wchar_t * __restrict format, ...); 38 int swscanf (const wchar_t * __restrict s, 39 const wchar_t * __restrict format, ...); 40 int vfwprintf (FILE * __restrict stream, 41 const wchar_t * __restrict format, va_list arg); 42 int vfwscanf (FILE * __restrict stream, 43 const wchar_t * __restrict format, va_list arg); 44 int vswprintf (wchar_t * __restrict s, size_t n, 45 const wchar_t * __restrict format, va_list arg); 46 int vswscanf (const wchar_t * __restrict s, 47 const wchar_t * __restrict format, va_list arg); 48 int vwprintf (const wchar_t * __restrict format, va_list arg); 49 int vwscanf (const wchar_t * __restrict format, va_list arg); 50 int wprintf (const wchar_t * __restrict format, ...); 51 int wscanf (const wchar_t * __restrict format, ...); 52 53 ################### Input/Output Functions 54 wint_t fgetwc (FILE *stream); 55 wchar_t *fgetws (wchar_t * __restrict S, int n, 56 FILE * __restrict stream); 57 wint_t fputwc (wchar_t c, FILE *stream); 58 int fputws (const wchar_t * __restrict S, 59 FILE * __restrict stream); 60 int fwide (FILE *stream, int mode); 61 wint_t getwc (FILE *stream); 62 wint_t getwchar (void); 63 wint_t putwc (wchar_t c, FILE *stream); 64 wint_t putwchar (wchar_t c); 65 wint_t ungetwc (wint_t c, FILE *stream); 66 67 ################### Numeric Conversions 68 double wcstod (const wchar_t * __restrict nptr, 69 wchar_t ** __restrict endptr); 70 float wcstof (const wchar_t * __restrict nptr, 71 wchar_t ** __restrict endptr); 72 long double wcstold (const wchar_t * __restrict nptr, 73 wchar_t ** __restrict endptr); 74 long int wcstol (const wchar_t * __restrict nptr, 75 wchar_t ** __restrict endptr, int base); 76 long long int wcstoll (const wchar_t * __restrict nptr, 77 wchar_t ** __restrict endptr, int base); 78 unsigned long int wcstoul (const wchar_t * __restrict nptr, 79 wchar_t ** __restrict endptr, int base); 80 unsigned long long int wcstoull (const wchar_t * __restrict nptr, 81 wchar_t ** __restrict endptr, int base); 82 83 ####################### String Copying 84 wchar_t *wcscpy (wchar_t * __restrict s1, 85 const wchar_t * __restrict s2); 86 wchar_t *wcsncpy (wchar_t * __restrict s1, 87 const wchar_t * __restrict s2, size_t n); 88 wchar_t *wmemcpy (wchar_t * __restrict s1, 89 const wchar_t * __restrict s2, size_t n); 90 wchar_t *wmemmove (wchar_t *s1, const wchar_t *s2, size_t n); 91 92 ################### String Concatenation 93 wchar_t *wcscat (wchar_t * __restrict s1, 94 const wchar_t * __restrict s2); 95 wchar_t *wcsncat (wchar_t * __restrict s1, 96 const wchar_t * __restrict s2, size_t n); 97 98 ##################### String Comparison 99 int wcscmp (const wchar_t *s1, const wchar_t *s2); 100 int wcscoll (const wchar_t *s1, const wchar_t *s2); 101 int wcsncmp (const wchar_t *s1, const wchar_t *s2, size_t n); 102 size_t wcsxfrm (wchar_t * __restrict s1, 103 const wchar_t * __restrict s2, size_t n); 104 int wmemcmp (const wchar_t *s1, const wchar_t *s2, size_t n); 105 106 ##################### String Searching 107 wchar_t *wcschr (const wchar_t *S, wchar_t c); 108 size_t wcscspn (const wchar_t *s1, const wchar_t *s2); 109 wchar_t *wcspbrk (const wchar_t *s1, const wchar_t *s2); 110 wchar_t *wcsrchr (const wchar_t *S, wchar_t c); 111 size_t wcsspn (const wchar_t *s1, const wchar_t *s2); 112 wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2); 113 wchar_t *wcstok (wchar_t * __restrict s1, 114 const wchar_t * __restrict s2, 115 wchar_t ** __restrict ptr); 116 wchar_t *wmemchr (const wchar_t *S, wchar_t c, size_t n); 117 118 ################### String Manipulation 119 size_t wcslen (const wchar_t *S); 120 wchar_t *wmemset (wchar_t *S, wchar_t c, size_t n); 121 122 ################# Date and Time Conversion 123 size_t wcsftime (wchar_t * __restrict S, size_t maxsize, 124 const wchar_t * __restrict format, 125 const struct tm * __restrict timeptr); 126 127 ############# Multibyte <--> Wide Character Conversion 128 wint_t btowc (int c); 129 int wctob (wint_t c); 130 int mbsinit (const mbstate_t *ps); 131 132 ####### Restartable Multibyte <--> Wide Character Conversion 133 size_t mbrlen (const char * __restrict S, size_t n, 134 mbstate_t * __restrict ps); 135 size_t mbrtowc (wchar_t * __restrict pwc, const char * __restrict S, 136 size_t n, mbstate_t * __restrict ps); 137 size_t wcrtomb (char * __restrict S, wchar_t wc, 138 mbstate_t * __restrict ps); 139 size_t mbsrtowcs (wchar_t * __restrict dst, 140 const char ** __restrict src, size_t len, 141 mbstate_t * __restrict ps); 142 size_t wcsrtombs (char * __restrict dst, 143 const wchar_t ** __restrict src, 144 size_t len, mbstate_t * __restrict ps); 145 @endverbatim 146 147 @note Properly constructed programs will take the following into consideration: 148 - wchar_t and wint_t may be the same integer type. 149 - WEOF might be a different value than that of EOF. 150 - WEOF might not be negative. 151 - mbstate_t objects are not intended to be inspected by programs. 152 153 Copyright (c) 2010 - 2014, Intel Corporation. All rights reserved.<BR> 154 This program and the accompanying materials are licensed and made available under 155 the terms and conditions of the BSD License that accompanies this distribution. 156 The full text of the license may be found at 157 http://opensource.org/licenses/bsd-license. 158 159 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 160 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 161 **/ 162 #ifndef _WCHAR_H 163 #define _WCHAR_H 164 #include <sys/EfiCdefs.h> 165 #include <machine/ansi.h> 166 #include <machine/limits.h> 167 #include <stdarg.h> 168 #include <stdio.h> 169 170 #if defined(_MSC_VER) 171 #pragma warning ( disable : 4142 ) 172 #endif 173 174 #ifdef _EFI_SIZE_T_ 175 typedef _EFI_SIZE_T_ size_t; /**< Unsigned integer type of the result of the sizeof operator. */ 176 #undef _BSD_SIZE_T_ 177 #undef _EFI_SIZE_T_ 178 #endif 179 180 #ifndef __cplusplus 181 #ifdef _EFI_WCHAR_T 182 /** An integer type capable of representing all distinct codes in the 183 UCS-2 encoding supported by UEFI. 184 **/ 185 typedef _EFI_WCHAR_T wchar_t; 186 #undef _BSD_WCHAR_T_ 187 #undef _EFI_WCHAR_T 188 #endif 189 #endif 190 191 #ifdef _BSD_MBSTATE_T_ 192 /** mbstate_t is an opaque object, that is not an array type, used to keep 193 conversion state during multibyte stream conversions. 194 */ 195 typedef _BSD_MBSTATE_T_ mbstate_t; 196 #undef _BSD_MBSTATE_T_ 197 #endif 198 199 #ifdef _EFI_WINT_T 200 /** wint_t is an integer type unchanged by default argument promotions that can 201 hold any value corresponding to members of the extended character set, as 202 well as at least one value that does not correspond to any member of the 203 extended character set: WEOF. 204 */ 205 typedef _EFI_WINT_T wint_t; 206 #undef _BSD_WINT_T_ 207 #undef _EFI_WINT_T 208 #endif 209 210 #ifndef WCHAR_MIN 211 /** @{ 212 Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and 213 a maximum value defined by __USHRT_MAX (65535 on IA processors). 214 */ 215 #define WCHAR_MIN 0 216 #define WCHAR_MAX __USHRT_MAX 217 /*@}*/ 218 #endif 219 220 #ifndef WEOF 221 /** WEOF expands to a constant expression of type wint_t whose value does not 222 correspond to any member of the extended character set. It is accepted 223 (and returned) by several functions, declared in this file, to indicate 224 end-of-file, that is, no more input from a stream. It is also used as a 225 wide character value that does not correspond to any member of the 226 extended character set. 227 */ 228 #define WEOF ((wint_t)-1) 229 #endif 230 231 /* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */ 232 #ifndef WINT_MIN 233 #define WINT_MIN _EFI_WINT_MIN /* wint_t */ 234 #define WINT_MAX _EFI_WINT_MAX /* wint_t */ 235 #endif 236 237 /** Type struct tm is declared here as an incomplete structure type for use as an argument 238 type by the wcsftime function. The full structure declaration is in <time.h>. 239 */ 240 struct tm; 241 242 /* ############### Formatted Input/Output Functions ##################### */ 243 244 /** The fwprintf function writes output to the stream pointed to by stream, 245 under control of the wide string pointed to by format that specifies how 246 subsequent arguments are converted for output. If there are insufficient 247 arguments for the format, the behavior is undefined. If the format is 248 exhausted while arguments remain, the excess arguments are evaluated 249 (as always) but are otherwise ignored. The fwprintf function returns 250 when the end of the format string is encountered. 251 252 The format is composed of zero or more directives: ordinary wide characters 253 (not %), which are copied unchanged to the output stream; and conversion 254 specifications, each of which results in fetching zero or more subsequent 255 arguments, converting them, if applicable, according to the corresponding 256 conversion specifier, and then writing the result to the output stream. 257 258 Each conversion specification is introduced by the wide character %. After 259 the %, the following appear in sequence: 260 * Zero or more flags (in any order) that modify the meaning of the 261 conversion specification. 262 * An optional minimum field width. If the converted value has fewer wide 263 characters than the field width, it is padded with spaces (by default) 264 on the left (or right, if the left adjustment flag, described later, 265 has been given) to the field width. The field width takes the form of 266 an asterisk * (described later) or a nonnegative decimal integer. 267 * An optional precision that gives the minimum number of digits to appear 268 for the d, i, o, u, x, and X conversions, the number of digits to 269 appear after the decimal-point wide character for e, E, f, and F 270 conversions, the maximum number of significant digits for the g and G 271 conversions, or the maximum number of wide characters to be written 272 for s conversions. The precision takes the form of a period (.) 273 followed either by an asterisk * (described later) or by an optional 274 decimal integer; if only the period is specified, the precision is 275 taken as zero. If a precision appears with any other conversion 276 specifier, the behavior is undefined. 277 * An optional length modifier that specifies the size of the argument. 278 * A conversion specifier wide character that specifies the type of 279 conversion to be applied. 280 281 As noted above, a field width, or precision, or both, may be indicated by 282 an asterisk. In this case, an int argument supplies the field width or 283 precision. The arguments specifying field width, or precision, or both, 284 must appear (in that order) before the argument (if any) to be converted. 285 A negative field width argument is taken as a - flag followed by a positive 286 field width. A negative precision argument is taken as if the precision 287 were omitted. 288 289 The flag wide characters and their meanings are:<BR> 290 - The result of the conversion is left-justified within the field. 291 (It is right-justified if this flag is not specified.) 292 + The result of a signed conversion always begins with a plus or minus 293 sign. (It begins with a sign only when a negative value is converted 294 if this flag is not specified.) 295 space If the first wide character of a signed conversion is not a sign, or 296 if a signed conversion results in no wide characters, a space is 297 prefixed to the result. If the space and + flags both appear, the 298 space flag is ignored. 299 # The result is converted to an "alternative form". For o conversion, 300 it increases the precision, if and only if necessary, to force the 301 first digit of the result to be a zero (if the value and precision 302 are both 0, a single 0 is printed). For x (or X) conversion, a 303 nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g, 304 and G conversions, the result of converting a floating-point number 305 always contains a decimal-point wide character, even if no digits 306 follow it. (Normally, a decimal-point wide character appears in the 307 result of these conversions only if a digit follows it.) For g and G 308 conversions, trailing zeros are not removed from the result. For 309 other conversions, the behavior is undefined. 310 0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros 311 (following any indication of sign or base) are used to pad to the 312 field width rather than performing space padding, except when 313 converting an infinity or NaN. If the 0 and - flags both appear, 314 the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a 315 precision is specified, the 0 flag is ignored. For other conversions, 316 the behavior is undefined. 317 318 The length modifiers and their meanings are:<BR> 319 hh Specifies that a following d, i, o, u, x, or X conversion specifier 320 applies to a signed char or unsigned char argument (the argument 321 will have been promoted according to the integer promotions, but its 322 value shall be converted to signed char or unsigned char before 323 printing); or that a following n conversion specifier applies to a 324 pointer to a signed char argument. 325 h Specifies that a following d, i, o, u, x, or X conversion specifier 326 applies to a short int or unsigned short int argument (the argument 327 will have been promoted according to the integer promotions, but its 328 value shall be converted to short int or unsigned short int before 329 printing); or that a following n conversion specifier applies to a 330 pointer to a short int argument. 331 l (ell) Specifies that a following d, i, o, u, x, or X conversion 332 specifier applies to a long int or unsigned long int argument; 333 that a following n conversion specifier applies to a pointer to a 334 long int argument; that a following c conversion specifier 335 applies to a wint_t argument; that a following s conversion 336 specifier applies to a pointer to a wchar_t argument; or has no 337 effect on a following e, E, f, F, g, or G conversion specifier. 338 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion 339 specifier applies to a long long int or unsigned long long int 340 argument; or that a following n conversion specifier applies 341 to a pointer to a long long int argument. 342 j Specifies that a following d, i, o, u, x, or X conversion specifier 343 applies to an intmax_t or uintmax_t argument; or that a following 344 n conversion specifier applies to a pointer to an intmax_t argument. 345 z Specifies that a following d, i, o, u, x, or X conversion specifier 346 applies to a size_t or the corresponding signed integer type 347 argument; or that a following n conversion specifier applies to a 348 pointer to a signed integer type corresponding to size_t argument. 349 t Specifies that a following d, i, o, u, x, or X conversion specifier 350 applies to a ptrdiff_t or the corresponding unsigned integer type 351 argument; or that a following n conversion specifier applies to a 352 pointer to a ptrdiff_t argument. 353 L Specifies that a following a, A, e, E, f, F, g, or G conversion 354 specifier applies to a long double argument. 355 356 If a length modifier appears with any conversion specifier other than as 357 specified above, the behavior is undefined. 358 359 The conversion specifiers and their meanings are:<BR> 360 d,i The int argument is converted to signed decimal in the 361 style [-]dddd. The precision specifies the minimum number of digits 362 to appear; if the value being converted can be represented in fewer 363 digits, it is expanded with leading zeros. The default precision 364 is 1. The result of converting a zero value with a precision of 365 zero is no wide characters. 366 o,u,x,X The unsigned int argument is converted to unsigned octal (o), 367 unsigned decimal (u), or unsigned hexadecimal notation (x or X) in 368 the style dddd; the letters abcdef are used for x conversion and 369 the letters ABCDEF for X conversion. The precision specifies the 370 minimum number of digits to appear; if the value being converted 371 can be represented in fewer digits, it is expanded with leading 372 zeros. The default precision is 1. The result of converting a zero 373 value with a precision of zero is no wide characters. 374 f,F A double argument representing a floating-point number is converted 375 to decimal notation in the style [-]ddd.ddd, where the number of 376 digits after the decimal-point wide character is equal to the 377 precision specification. If the precision is missing, it is taken 378 as 6; if the precision is zero and the # flag is not specified, no 379 decimal-point wide character appears. If a decimal-point wide 380 character appears, at least one digit appears before it. The value 381 is rounded to the appropriate number of digits.<BR> 382 A double argument representing an infinity is converted to [-]inf. 383 A double argument representing a NaN is converted to [-]nan. 384 The F conversion specifier produces INF or NAN instead 385 of inf or nan, respectively. 386 e,E A double argument representing a floating-point number is converted 387 in the style [-]d.ddd e +/- dd, where there is one digit (which is 388 nonzero if the argument is nonzero) before the decimal-point wide 389 character and the number of digits after it is equal to the 390 precision; if the precision is missing, it is taken as 6; if the 391 precision is zero and the # flag is not specified, no decimal-point 392 wide character appears. The value is rounded to the appropriate 393 number of digits. The E conversion specifier produces a number with 394 E instead of e introducing the exponent. The exponent always 395 contains at least two digits, and only as many more digits as 396 necessary to represent the exponent. If the value is zero, the 397 exponent is zero. A double argument representing an infinity or NaN 398 is converted in the style of an f or F conversion specifier. 399 g,G A double argument representing a floating-point number is converted 400 in style f or e (or in style F or E in the case of a G conversion 401 specifier), depending on the value converted and the precision. 402 Let P equal the precision if nonzero, 6 if the precision is 403 omitted, or 1 if the precision is zero. Then, if a conversion with 404 style E would have an exponent of X: 405 - if P > X = -4, the conversion is with style f (or F) and 406 precision P - (X + 1). 407 - otherwise, the conversion is with style e (or E) and 408 precision P - 1. 409 Finally, unless the # flag is used, any trailing zeros are removed 410 from the fractional portion of the result and the decimal-point 411 wide character is removed if there is no fractional portion 412 remaining. A double argument representing an infinity or NaN is 413 converted in the style of an f or F conversion specifier. 414 c If no l length modifier is present, the int argument is converted 415 to a wide character as if by calling btowc and the resulting wide 416 character is written. If an l length modifier is present, the 417 wint_t argument is converted to wchar_t and written. 418 s If no l length modifier is present, the argument shall be a pointer 419 to the initial element of a character array containing a multibyte 420 character sequence beginning in the initial shift state. Characters 421 from the array are converted as if by repeated calls to the mbrtowc 422 function, with the conversion state described by an mbstate_t 423 object initialized to zero before the first multibyte character is 424 converted, and written up to (but not including) the terminating 425 null wide character. If the precision is specified, no more than 426 that many wide characters are written. If the precision is not 427 specified or is greater than the size of the converted array, the 428 converted array shall contain a null wide character.<BR> 429 If an l length modifier is present, the argument shall be a pointer 430 to the initial element of an array of wchar_t type. Wide characters 431 from the array are written up to (but not including) a terminating 432 null wide character. If the precision is specified, no more than 433 that many wide characters are written. If the precision is not 434 specified or is greater than the size of the array, the array 435 shall contain a null wide character. 436 p The argument shall be a pointer to void. The value of the pointer 437 is converted to a sequence of printing wide characters, in an 438 implementation-defined manner. 439 n The argument shall be a pointer to signed integer into which is 440 written the number of wide characters written to the output stream 441 so far by this call to fwprintf. No argument is converted, but one 442 is consumed. If the conversion specification includes any flags, a 443 field width, or a precision, the behavior is undefined. 444 % A % wide character is written. No argument is converted. The 445 complete conversion specification is %%. 446 447 448 @param[in] stream An open File specifier to which the output is sent. 449 @param[in] format A wide character sequence containing characters 450 to be copied unchanged, and conversion specifiers 451 which convert their associated arguments. 452 @param ... Variable number of parameters as required by format. 453 454 @return The fwprintf function returns the number of wide characters 455 transmitted, or a negative value if an output or encoding error 456 occurred. 457 **/ 458 int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...); 459 460 /** The fwscanf function reads input from the stream pointed to by stream, 461 under control of the wide string pointed to by format that specifies 462 the admissible input sequences and how they are to be converted for 463 assignment, using subsequent arguments as pointers to the objects to 464 receive the converted input. If there are insufficient arguments for 465 the format, the behavior is undefined. If the format is exhausted while 466 arguments remain, the excess arguments are evaluated (as always) but are 467 otherwise ignored. 468 469 The format is composed of zero or more directives: one or more white-space 470 wide characters, an ordinary wide character (neither % nor a white-space 471 wide character), or a conversion specification. Each conversion 472 specification is introduced by the wide character %. After the %, the 473 following appear in sequence: 474 - An optional assignment-suppressing wide character *. 475 - An optional decimal integer greater than zero that specifies the 476 maximum field width (in wide characters). 477 - An optional length modifier that specifies the size of the receiving object. 478 - A conversion specifier wide character that specifies the type of 479 conversion to be applied. 480 481 The fwscanf function executes each directive of the format in turn. If a 482 directive fails, as detailed below, the function returns. Failures are 483 described as input failures (due to the occurrence of an encoding error 484 or the unavailability of input characters), or matching failures 485 (due to inappropriate input). 486 487 A directive composed of white-space wide character(s) is executed by 488 reading input up to the first non-white-space wide character (which remains 489 unread), or until no more wide characters can be read. 490 491 A directive that is an ordinary wide character is executed by reading the 492 next wide character of the stream. If that wide character differs from the 493 directive, the directive fails and the differing and subsequent wide 494 characters remain unread. Similarly, if end-of-file, an encoding error, or 495 a read error prevents a wide character from being read, the directive fails. 496 497 A directive that is a conversion specification defines a set of matching 498 input sequences, as described below for each specifier. A conversion 499 specification is executed in the following steps: 500 - Input white-space wide characters (as specified by the iswspace 501 function) are skipped, unless the specification includes 502 a [, c, or n specifier. 503 - An input item is read from the stream, unless the specification 504 includes an n specifier. An input item is defined as the longest 505 sequence of input wide characters which does not exceed any specified 506 field width and which is, or is a prefix of, a matching input sequence. 507 The first wide character, if any, after the input item remains unread. 508 If the length of the input item is zero, the execution of the directive 509 fails; this condition is a matching failure unless end-of-file, an 510 encoding error, or a read error prevented input from the stream, in 511 which case it is an input failure. 512 - Except in the case of a % specifier, the input item (or, in the case of 513 a %n directive, the count of input wide characters) is converted to a 514 type appropriate to the conversion specifier. If the input item is not 515 a matching sequence, the execution of the directive fails: this 516 condition is a matching failure. Unless assignment suppression was 517 indicated by a *, the result of the conversion is placed in the object 518 pointed to by the first argument following the format argument that has 519 not already received a conversion result. If this object does not have 520 an appropriate type, or if the result of the conversion cannot be 521 represented in the object, the behavior is undefined. 522 523 The length modifiers and their meanings are:<BR> 524 hh Specifies that a following d, i, o, u, x, X, or n conversion 525 specifier applies to an argument with type pointer to signed char 526 or unsigned char. 527 h Specifies that a following d, i, o, u, x, X, or n conversion 528 specifier applies to an argument with type pointer to short int 529 or unsigned short int. 530 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion 531 specifier applies to an argument with type pointer to long int or 532 unsigned long int; that a following e, E, f, F, g, or G conversion 533 specifier applies to an argument with type pointer to double; or 534 that a following c, s, or [ conversion specifier applies to an 535 argument with type pointer to wchar_t. 536 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion 537 specifier applies to an argument with type 538 pointer to long long int or unsigned long long int. 539 j Specifies that a following d, i, o, u, x, X, or n conversion 540 specifier applies to an argument with type pointer to intmax_t 541 or uintmax_t. 542 z Specifies that a following d, i, o, u, x, X, or n conversion 543 specifier applies to an argument with type pointer to size_t or the 544 corresponding signed integer type. 545 t Specifies that a following d, i, o, u, x, X, or n conversion 546 specifier applies to an argument with type pointer to ptrdiff_t or 547 the corresponding unsigned integer type. 548 L Specifies that a following e, E, f, F, g, or G conversion specifier 549 applies to an argument with type pointer to long double. 550 551 If a length modifier appears with any conversion specifier other than as 552 specified above, the behavior is undefined. 553 554 The conversion specifiers and their meanings are:<BR> 555 d Matches an optionally signed decimal integer, whose format is the 556 same as expected for the subject sequence of the wcstol function 557 with the value 10 for the base argument. The corresponding argument 558 shall be a pointer to signed integer. 559 i Matches an optionally signed integer, whose format is the same as 560 expected for the subject sequence of the wcstol function with the 561 value 0 for the base argument. The corresponding argument shall be 562 a pointer to signed integer. 563 o Matches an optionally signed octal integer, whose format is the 564 same as expected for the subject sequence of the wcstoul function 565 with the value 8 for the base argument. The corresponding argument 566 shall be a pointer to unsigned integer. 567 u Matches an optionally signed decimal integer, whose format is the 568 same as expected for the subject sequence of the wcstoul function 569 with the value 10 for the base argument. The corresponding argument 570 shall be a pointer to unsigned integer. 571 x Matches an optionally signed hexadecimal integer, whose format is 572 the same as expected for the subject sequence of the wcstoul 573 function with the value 16 for the base argument. The corresponding 574 argument shall be a pointer to unsigned integer. 575 e,f,g Matches an optionally signed floating-point number, infinity, or 576 NaN, whose format is the same as expected for the subject sequence 577 of the wcstod function. The corresponding argument shall be a 578 pointer to float. 579 c Matches a sequence of wide characters of exactly the number 580 specified by the field width (1 if no field width is present in the 581 directive).<BR> 582 If no l length modifier is present, characters from the input field 583 are converted as if by repeated calls to the wcrtomb function, with 584 the conversion state described by an mbstate_t object initialized 585 to zero before the first wide character is converted. The 586 corresponding argument shall be a pointer to the initial element of 587 a character array large enough to accept the sequence. No null 588 character is added.<BR> 589 If an l length modifier is present, the corresponding argument 590 shall be a pointer to the initial element of an array of 591 wchar_t large enough to accept the sequence. 592 No null wide character is added. 593 s Matches a sequence of non-white-space wide characters. 594 If no l length modifier is present, characters from the input field 595 are converted as if by repeated calls to the wcrtomb function, with 596 the conversion state described by an mbstate_t object initialized 597 to zero before the first wide character is converted. The 598 corresponding argument shall be a pointer to the initial element of 599 a character array large enough to accept the sequence and a 600 terminating null character, which will be added automatically.<BR> 601 If an l length modifier is present, the corresponding argument 602 shall be a pointer to the initial element of an array of wchar_t 603 large enough to accept the sequence and the terminating null wide 604 character, which will be added automatically. 605 [ Matches a nonempty sequence of wide characters from a set of 606 expected characters (the scanset).<BR> 607 If no l length modifier is present, characters from the input field 608 are converted as if by repeated calls to the wcrtomb function, with 609 the conversion state described by an mbstate_t object initialized 610 to zero before the first wide character is converted. The 611 corresponding argument shall be a pointer to the initial element of 612 a character array large enough to accept the sequence and a 613 terminating null character, which will be added automatically.<BR> 614 If an l length modifier is present, the corresponding argument 615 shall be a pointer to the initial element of an array of wchar_t 616 large enough to accept the sequence and the terminating null wide 617 character, which will be added automatically.<BR> 618 The conversion specifier includes all subsequent wide characters 619 in the format string, up to and including the matching right 620 bracket (]). The wide characters between the brackets 621 (the scanlist) compose the scanset, unless the wide character after 622 the left bracket is a circumflex (^), in which case the scanset 623 contains all wide characters that do not appear in the scanlist 624 between the circumflex and the right bracket. If the conversion 625 specifier begins with [] or [^], the right bracket wide character 626 is in the scanlist and the next following right bracket wide 627 character is the matching right bracket that ends the specification; 628 otherwise the first following right bracket wide character is the 629 one that ends the specification. If a - wide character is in the 630 scanlist and is not the first, nor the second where the first wide 631 character is a ^, nor the last character, 632 the - is added to the scanset. 633 p Matches the set of sequences produced by the %p conversion of the 634 fwprintf function. The corresponding argument is a pointer to a 635 pointer to void. The input item is converted to a pointer value. If 636 the input item is a value converted earlier during the same program 637 execution, the pointer that results will compare equal to that 638 value. 639 n No input is consumed. The corresponding argument is a pointer to 640 signed integer into which is to be written the number of wide 641 characters read from the input stream so far by this call to the 642 fwscanf function. Execution of a %n directive does not increment 643 the assignment count returned at the completion of execution of the 644 fwscanf function. No argument is converted, but one is consumed. 645 % Matches a single % wide character; no conversion or assignment 646 occurs. The complete conversion specification shall be %%. 647 648 The conversion specifiers E, F, G, and X are also valid and behave the same 649 as, respectively, e, f, g, and x. 650 651 Trailing white space (including new-line wide characters) is left unread 652 unless matched by a directive. The success of literal matches and 653 suppressed assignments is not directly determinable other than via 654 the %n directive. 655 656 @param[in] stream An open File specifier from which the input is read. 657 @param[in] format A wide character sequence containing characters 658 to be matched against, and conversion specifiers 659 which convert their associated arguments. Converted 660 items are stored according to their associated arguments. 661 @param ... Variable number of parameters, as required by format, 662 specifying the objects to receive the converted input. 663 664 @return The fwscanf function returns the value of the macro EOF if an 665 input failure occurs before any conversion. Otherwise, the 666 function returns the number of input items assigned, which can be 667 fewer than provided for, or even zero, in the event of an early 668 matching failure. 669 **/ 670 int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...); 671 672 /** Formatted wide-character output to a buffer. 673 674 The swprintf function is equivalent to fwprintf, except that the argument s 675 specifies an array of wide characters into which the generated output is to 676 be written, rather than written to a stream. No more than n wide characters 677 are written, including a terminating null wide character, which is always 678 added (unless n is zero). 679 680 @param[out] s A pointer to the array to receive the formatted output. 681 @param[in] n Maximum number of characters to write into buffer s. 682 @param[in] format A wide character sequence containing characters 683 to be copied unchanged, and conversion specifiers 684 which convert their associated arguments. Copied and 685 converted characters are written to the array pointed 686 to by s. 687 @param ... Variable number of parameters as required by format. 688 689 @return The swprintf function returns the number of wide characters 690 written in the array, not counting the terminating null wide 691 character, or a negative value if an encoding error occurred or 692 if n or more wide characters were requested to be written. 693 **/ 694 int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...); 695 696 /** Formatted wide input from a string. 697 698 The swscanf function is equivalent to fwscanf, except that the argument 699 Buff specifies a wide string from which the input is to be obtained, rather 700 than from a stream. Reaching the end of the wide string is equivalent to 701 encountering end-of-file for the fwscanf function. 702 703 @param[in] Buff Pointer to the string from which to obtain input. 704 @param[in] Format A wide character sequence containing characters 705 to be matched against, and conversion specifiers 706 which convert their associated arguments. 707 @param[out] ... Variable number of parameters, as required by format, 708 specifying the objects to receive the converted input. 709 710 @return The swscanf function returns the value of the macro EOF if an 711 input failure occurs before any conversion. Otherwise, the 712 swscanf function returns the number of input items assigned, 713 which can be fewer than provided for, or even zero, in the event 714 of an early matching failure. 715 **/ 716 int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...); 717 718 /** Print formatted values from an argument list. 719 720 The vfwprintf function is equivalent to fwprintf, with the variable argument list 721 replaced by Args, which shall have been initialized by the va_start macro (and 722 possibly subsequent va_arg calls). The vfwprintf function does not invoke the 723 va_end macro. 724 725 @param[in] Stream The output stream to receive the formatted output. 726 @param[in] Format A wide character sequence containing characters 727 to be matched against, and conversion specifiers 728 which convert their associated arguments. 729 @param[in] Args A list of arguments, initialized by the va_start macro 730 and accessed using the va_arg macro, used to satisfy 731 the directives in the Format string. 732 733 @return The vfwprintf function returns the number of wide characters 734 transmitted, or a negative value if an output or encoding 735 error occurred. 736 **/ 737 int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args); 738 739 /** Formatted input from a stream. 740 741 The vfwscanf function is equivalent to fwscanf, with the variable argument 742 list replaced by Args, which must have been initialized by the va_start 743 macro (and possibly subsequent va_arg calls). The vfwscanf function does 744 not invoke the va_end macro. 745 746 @param[in] Stream The input stream. 747 @param[in] Format A wide character sequence containing characters 748 to be matched against, and conversion specifiers 749 which convert their associated arguments. 750 @param[in] Args A list of arguments, initialized by the va_start macro 751 and accessed using the va_arg macro, used to satisfy 752 the directives in the Format string. 753 754 @return The vfwscanf function returns the value of the macro EOF if an 755 input failure occurs before any conversion. Otherwise, the 756 vfwscanf function returns the number of input items assigned, 757 which can be fewer than provided for, or even zero, in the event 758 of an early matching failure. 759 **/ 760 int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args); 761 762 /** Formatted print, to a buffer, from an argument list. 763 764 The vswprintf function is equivalent to swprintf, with the variable 765 argument list replaced by Args, which must have been initialized by the 766 va_start macro (and possibly subsequent va_arg calls). The vswprintf 767 function does not invoke the va_end macro. 768 769 @param[in] S A pointer to the array to receive the formatted output. 770 @param[in] N Maximum number of characters to write into array S. 771 @param[in] Format A wide character sequence containing characters 772 to be matched against, and conversion specifiers 773 which convert their associated arguments. 774 @param[in] Args A list of arguments, initialized by the va_start macro 775 and accessed using the va_arg macro, used to satisfy 776 the directives in the Format string. 777 778 @return The vswprintf function returns the number of wide characters 779 written in the array, not counting the terminating null wide 780 character, or a neg ative value if an encoding error occurred or 781 if n or more wide characters were requested to be generated. 782 **/ 783 int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args); 784 785 /** Formatted input from a string, using an argument list. 786 787 The vswscanf function is equivalent to swscanf, with the variable argument 788 list replaced by Args, which must have been initialized by the va_start 789 macro. The vswscanf function does not invoke the va_end macro. 790 791 @param[in] S Pointer to the string from which to obtain input. 792 @param[in] Format A wide character sequence containing characters 793 to be matched against, and conversion specifiers 794 which convert their associated arguments. 795 @param[out] Args A list of arguments, initialized by the va_start macro 796 and accessed using the va_arg macro, used to satisfy 797 the directives in the Format string. 798 799 @return The vswscanf function returns the value of the macro EOF if an 800 input failure occurs before any conversion. Otherwise, the 801 vswscanf function returns the number of input items assigned, 802 which can be fewer than provided for, or even zero, in the event 803 of an early matching failure. 804 **/ 805 int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args); 806 807 /** Formatted print, to stdout, from an argument list. 808 809 The vwprintf function is equivalent to wprintf, with the variable argument 810 list replaced by Args, which must have been initialized by the va_start 811 macro. The vwprintf function does not invoke the va_end macro. 812 813 @param[in] Format A wide character sequence containing characters 814 to be matched against, and conversion specifiers 815 which convert their associated arguments. 816 @param[out] Args A list of arguments, initialized by the va_start macro 817 and accessed using the va_arg macro, used to satisfy 818 the directives in the Format string. 819 820 @return The vwprintf function returns the number of wide characters 821 transmitted, or a negative value if an output or encoding error 822 occurred. 823 **/ 824 int vwprintf(const wchar_t * __restrict Format, va_list Args); 825 826 /** Formatted input, from stdin, to an argument list. 827 828 The vwscanf function is equivalent to wscanf, with the variable argument 829 list replaced by arg, which shall have been initialized by the va_start 830 macro. The vwscanf function does not invoke the va_end macro. 831 832 @param[in] Format A wide character sequence containing characters 833 to be matched against, and conversion specifiers 834 which convert their associated arguments. 835 @param[out] Args A list of arguments, initialized by the va_start macro 836 and accessed using the va_arg macro, used to satisfy 837 the directives in the Format string. 838 839 @return The vwscanf function returns the value of the macro EOF if an 840 input failure occurs before any conversion. Otherwise, the 841 vwscanf function returns the number of input items assigned, 842 which can be fewer than provided for, or even zero, in the event 843 of an early matching failure. 844 **/ 845 int vwscanf(const wchar_t * __restrict Format, va_list Args); 846 847 /** Formatted print to stdout. 848 849 The wprintf function is equivalent to fwprintf with the argument stdout 850 specifying the output stream. 851 852 @param[in] format A wide character sequence containing characters 853 to be copied unchanged, and conversion specifiers 854 which convert their associated arguments. 855 @param ... Variable number of parameters as required by format. 856 857 @return The wprintf function returns the number of wide characters 858 transmitted, or a negative value if an output or encoding error 859 occurred. 860 **/ 861 int wprintf(const wchar_t * __restrict Format, ...); 862 863 /** Formatted input from stdin. 864 865 The wscanf function is equivalent to fwscanf with the argument stdin 866 specifying the input stream. 867 868 @param[in] format A wide character sequence containing characters 869 to be matched against, and conversion specifiers 870 which convert their associated arguments. Converted 871 items are stored according to their associated arguments. 872 @param ... Variable number of parameters, as required by format, 873 specifying the objects to receive the converted input. 874 875 @return The wscanf function returns the value of the macro EOF if an 876 input failure occurs before any conversion. Otherwise, the 877 wscanf function returns the number of input items assigned, 878 which can be fewer than provided for, or even zero, in the event 879 of an early matching failure. 880 **/ 881 int wscanf(const wchar_t * __restrict format, ...); 882 883 /* ################### Input/Output Functions ########################### */ 884 885 886 /** Get a character from an input Stream. 887 888 If the end-of-file indicator for the input stream pointed to by stream is not set and a 889 next wide character is present, the fgetwc function obtains that wide character as a 890 wchar_t converted to a wint_t and advances the associated file position indicator for 891 the stream (if defined). 892 893 @param[in] Stream An input stream from which to obtain a character. 894 895 @return If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof- 896 file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise, 897 the fgetwc function returns the next wide character from the input stream pointed to by 898 stream. If a read error occurs, the error indicator for the stream is set and the fgetwc 899 function returns WEOF. If an encoding error occurs (including too few bytes), the value of 900 the macro EILSEQ is stored in errno and the fgetwc function returns WEOF. 901 **/ 902 wint_t fgetwc(FILE *Stream); 903 904 /** Read a string from an input stream into a buffer. 905 906 The fgetws function reads at most one less than the number of 907 wide characters specified by n from the stream pointed to by 908 stream into the array pointed to by s. No additional wide 909 characters are read after a new-line wide character (which is 910 retained) or after end-of-file. A null wide character is written 911 immediately after the last wide character read into the array. 912 913 @param[out] S A pointer to the array to receive the input string. 914 @param[in] Limit The maximum number of characters to put into Buff, 915 including the terminating null character. 916 @param[in] Stream An input stream from which to obtain the string. 917 918 @return The fgetws function returns S if successful. If end-of-file is 919 encountered and no characters have been read into the array, the 920 contents of the array remain unchanged and a null pointer is 921 returned. If a read or encoding error occurs during the 922 operation, the array contents are indeterminate and a 923 null pointer is returned. 924 **/ 925 wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream); 926 927 /** Write a character to an output stream. 928 929 The fputwc function writes the wide character specified by c to the output stream 930 pointed to by stream, at the position indicated by the associated file position indicator 931 for the stream (if defined), and advances the indicator appropriately. If the file cannot 932 support positioning requests, or if the stream was opened with append mode, the 933 character is appended to the output stream. 934 935 @param[in] C The character to be written to Stream. 936 @param[in] Stream The output stream that C is to be written to. 937 938 @return The fputwc function returns the wide character written. If a write error occurs, the 939 error indicator for the stream is set and fputwc returns WEOF. If an encoding error 940 occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF. 941 **/ 942 wint_t fputwc(wchar_t C, FILE *Stream); 943 944 /** Write a string to an output stream. 945 946 The fputws function writes the wide string pointed to by S to the stream pointed to by 947 Stream. The terminating null wide character is not written. 948 949 @param[in] String The character string to be written to Stream. 950 @param[in] Stream The output stream that String is to be written to. 951 952 @return The fputws function returns EOF if a write or encoding error occurs; otherwise, it 953 returns a nonnegative value. 954 **/ 955 int fputws(const wchar_t * __restrict S, FILE * __restrict Stream); 956 957 /** Query or set a stream's orientation. 958 959 The fwide function determines the orientation of the stream pointed to by stream. If 960 Mode is greater than zero, the function first attempts to make the stream wide oriented. If 961 Mode is less than zero, the function first attempts to make the stream byte oriented. 962 Otherwise, Mode is zero and the function does not alter the orientation of the stream. 963 964 @param[in] Stream The stream to be queried. 965 @param[in] Mode Control value selecting between quering or setting 966 the Stream's orientation. 967 @return The fwide function returns a value greater than zero if, after the call, the stream has 968 wide orientation, a value less than zero if the stream has byte orientation, or zero if the 969 stream has no orientation. 970 **/ 971 int fwide(FILE *Stream, int Mode); 972 973 /** Get a character from an input stream. 974 975 The getwc function is equivalent to fgetwc, except that if it is implemented as a 976 macro, it may evaluate Stream more than once, so the argument should never be an 977 expression with side effects. 978 979 @param[in] Stream The stream to be read. 980 981 @return The getwc function returns the next wide character from the input stream pointed to by 982 stream, or WEOF. 983 **/ 984 wint_t getwc(FILE *Stream); 985 986 /** Get a character from stdin. 987 988 The getwchar function is equivalent to getwc with the argument stdin. 989 990 @return The getwchar function returns the next wide character from the 991 input stream pointed to by stdin, or WEOF. 992 **/ 993 wint_t getwchar(void); 994 995 /** Write a character to an output stream. 996 997 The putwc function is equivalent to fputwc, except that if it is implemented as a 998 macro, it may evaluate Stream more than once, so the Stream argument should never be an 999 expression with side effects. 1000 1001 @param[in] C The wide character to be written to Stream. 1002 @param[in] Stream The output stream that C is to be written to. 1003 1004 @return The putwc function returns the wide character written, or WEOF. 1005 **/ 1006 wint_t putwc(wchar_t C, FILE *Stream); 1007 1008 /** Write a character to stdout. 1009 1010 The putwchar function is equivalent to putwc with the second argument stdout. 1011 1012 @param[in] C The wide character to be written to stdout. 1013 1014 @return The putwchar function returns the character written, or WEOF. 1015 **/ 1016 wint_t putwchar(wchar_t C); 1017 1018 /** Return a character to the input Stream as if it had not been read. 1019 1020 The ungetwc function pushes the wide character specified by C back onto the input 1021 stream pointed to by Stream. Pushed-back wide characters will be returned by 1022 subsequent reads on that stream in the reverse order of their pushing. A successful 1023 intervening call (with the stream pointed to by Stream) to a file positioning function 1024 (fseek, fsetpos, or rewind) discards any pushed-back wide characters for the 1025 stream. The external storage corresponding to the stream is unchanged. 1026 1027 One wide character of pushback is guaranteed, even if the call to the ungetwc function 1028 follows just after a call to a formatted wide character input function fwscanf, 1029 vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times 1030 on the same stream without an intervening read or file positioning operation on that 1031 stream, the operation may fail. 1032 1033 If the value of C equals that of the macro WEOF, the operation fails and the input stream is 1034 unchanged. 1035 1036 A successful call to the ungetwc function clears the end-of-file indicator for the stream. 1037 The value of the file position indicator for the stream after reading or discarding all 1038 pushed-back wide characters is the same as it was before the wide characters were pushed 1039 back. For a text or binary stream, the value of its file position indicator after a successful 1040 call to the ungetwc function is unspecified until all pushed-back wide characters are 1041 read or discarded. 1042 1043 @param[in] C The wide character to push back onto the Stream. 1044 @param[in] Stream The output stream that C is to be pushed back onto. 1045 1046 @return The ungetwc function returns the character pushed back, 1047 or WEOF if the operation fails. 1048 **/ 1049 wint_t ungetwc(wint_t C, FILE *Stream); 1050 1051 /* ################### Numeric Conversions ########################### */ 1052 1053 /** @{ 1054 The wcstod, wcstof, and wcstold functions convert the initial portion of the wide 1055 string pointed to by nptr to double, float, and long double representation, 1056 respectively. First, they decompose the input string into three parts: an initial, possibly 1057 empty, sequence of white-space wide characters (as specified by the iswspace 1058 function), a subject sequence resembling a floating-point constant or representing an 1059 infinity or NaN; and a final wide string of one or more unrecognized wide characters, 1060 including the terminating null wide character of the input wide string. Then, they attempt 1061 to convert the subject sequence to a floating-point number, and return the result. 1062 1063 @param[in] Nptr Pointer to the string to convert to a floating-point value. 1064 @param[in] EndPtr Optional pointer to an object in which to store a pointer 1065 to the final wide string. 1066 1067 The functions return the converted value, if any. If no conversion could be performed, 1068 zero is returned. If the correct value is outside the range of representable values, plus or 1069 minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return 1070 type and sign of the value), and the value of the macro ERANGE is stored in errno. If 1071 the result underflows (7.12.1), the functions return a value whose magnitude is no greater 1072 than the smallest normalized positive number in the return type. A pointer to the 1073 final wide string is stored in the object pointed to by endptr, provided that endptr is 1074 not a null pointer. 1075 **/ 1076 double wcstod (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr); 1077 float wcstof (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr); 1078 long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr); 1079 /*@}*/ 1080 1081 /** @{ 1082 The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial 1083 portion of the wide string pointed to by nptr to long int, long long int, 1084 unsigned long int, and unsigned long long int representation, 1085 respectively. First, they decompose the input string into three parts: an initial, possibly 1086 empty, sequence of white-space wide characters (as specified by the iswspace 1087 function), a subject sequence resembling an integer represented in some radix determined 1088 by the value of base, and a final wide string of one or more unrecognized wide 1089 characters, including the terminating null wide character of the input wide string. Then, 1090 they attempt to convert the subject sequence to an integer, and return the result. 1091 1092 @param[in] Nptr Pointer to the string to convert. 1093 @param[in] EndPtr Optional pointer to an object in which to store a pointer 1094 to the final wide string. 1095 @param[in] Base Base, 0 to 36, of the value represented by the string 1096 pointed to by Nptr. 1097 1098 @return The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted 1099 value, if any. If no conversion could be performed, zero is returned. If the correct value 1100 is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN, 1101 LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type 1102 sign of the value, if any), and the value of the macro ERANGE is stored in errno. 1103 **/ 1104 long int wcstol ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base); 1105 long long int wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base); 1106 unsigned long int wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base); 1107 unsigned long long int wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base); 1108 /*@}*/ 1109 1110 /* ####################### String Copying ############################### */ 1111 1112 /** The wcscpy function copies the wide string pointed to by Src (including the 1113 terminating null wide character) into the array pointed to by Dest. 1114 1115 @return The wcscpy function returns the value of Dest. 1116 **/ 1117 wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src); 1118 1119 /** The wcsncpy function copies not more than n wide characters (those that 1120 follow a null wide character are not copied) from the array pointed to by 1121 Src to the array pointed to by Dest. 1122 1123 If the array pointed to by Src is a wide string that is shorter than n wide 1124 characters, null wide characters are appended to the copy in the array 1125 pointed to by Dest, until n wide characters in all have been written. 1126 1127 @return The wcsncpy function returns the value of Dest. 1128 **/ 1129 wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n); 1130 1131 /** The wmemcpy function copies n wide characters from the object pointed to by 1132 Src to the object pointed to by Dest. 1133 1134 Use this function if you know that Dest and Src DO NOT Overlap. Otherwise, 1135 use wmemmove. 1136 1137 @return The wmemcpy function returns the value of Dest. 1138 **/ 1139 wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n); 1140 1141 /** The wmemmove function copies n wide characters from the object pointed to by 1142 Src to the object pointed to by Dest. The objects pointed to by Dest and Src are 1143 allowed to overlap. 1144 1145 Because the UEFI BaseMemoryLib function CopyMem explicitly handles 1146 overlapping source and destination objects, this function and wmemcpy are 1147 implemented identically. 1148 1149 For programming clarity, it is recommended that you use wmemcpy if you know 1150 that Dest and Src DO NOT Overlap. If Dest and Src might possibly overlap, then 1151 use wmemmove. 1152 1153 @return The wmemmove function returns the value of Dest. 1154 **/ 1155 wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n); 1156 1157 /* ################### String Concatenation ########################## */ 1158 1159 /** The wcscat function appends a copy of the wide string pointed to by Src 1160 (including the terminating null wide character) to the end of the wide 1161 string pointed to by Dest. The initial wide character of Src overwrites the 1162 null wide character at the end of Dest. 1163 1164 @return The wcscat function returns the value of Dest. 1165 **/ 1166 wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src); 1167 1168 /** The wcsncat function appends not more than n wide characters (a null wide 1169 character and those that follow it are not appended) from the array pointed 1170 to by Src to the end of the wide string pointed to by Dest. The initial wide 1171 character of Src overwrites the null wide character at the end of Dest. 1172 A terminating null wide character is always appended to the result. 1173 1174 @return The wcsncat function returns the value of Dest. 1175 **/ 1176 wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n); 1177 1178 /* ##################### String Comparison ############################# */ 1179 1180 /** The wcscmp function compares the wide string pointed to by s1 to the wide 1181 string pointed to by s2. 1182 1183 @return The wcscmp function returns an integer greater than, equal to, or 1184 less than zero, accordingly as the wide string pointed to by s1 1185 is greater than, equal to, or less than the wide string 1186 pointed to by s2. 1187 **/ 1188 int wcscmp(const wchar_t *s1, const wchar_t *s2); 1189 1190 /** The wcscoll function compares the wide string pointed to by s1 to the wide 1191 string pointed to by s2, both interpreted as appropriate to the LC_COLLATE 1192 category of the current locale. 1193 1194 @return The wcscoll function returns an integer greater than, equal to, 1195 or less than zero, accordingly as the wide string pointed to by 1196 s1 is greater than, equal to, or less than the wide string 1197 pointed to by s2 when both are interpreted as appropriate to 1198 the current locale. 1199 **/ 1200 int wcscoll(const wchar_t *s1, const wchar_t *s2); 1201 1202 /** The wcsncmp function compares not more than n wide characters (those that 1203 follow a null wide character are not compared) from the array pointed to by 1204 s1 to the array pointed to by s2. 1205 1206 @return The wcsncmp function returns an integer greater than, equal to, 1207 or less than zero, accordingly as the possibly null-terminated 1208 array pointed to by s1 is greater than, equal to, or less than 1209 the possibly null-terminated array pointed to by s2. 1210 **/ 1211 int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n); 1212 1213 /** The wcsxfrm function transforms the wide string pointed to by s2 and places 1214 the resulting wide string into the array pointed to by s1. The 1215 transformation is such that if the wcscmp function is applied to two 1216 transformed wide strings, it returns a value greater than, equal to, or 1217 less than zero, corresponding to the result of the wcscoll function applied 1218 to the same two original wide strings. No more than n wide characters are 1219 placed into the resulting array pointed to by s1, including the terminating 1220 null wide character. If n is zero, s1 is permitted to be a null pointer. 1221 1222 @return The wcsxfrm function returns the length of the transformed wide 1223 string (not including the terminating null wide character). If 1224 the value returned is n or greater, the contents of the array 1225 pointed to by s1 are indeterminate. 1226 **/ 1227 size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n); 1228 1229 /** The wmemcmp function compares the first n wide characters of the object 1230 pointed to by s1 to the first n wide characters of the object pointed to 1231 by s2. 1232 1233 @return The wmemcmp function returns an integer greater than, equal to, 1234 or less than zero, accordingly as the object pointed to by s1 is 1235 greater than, equal to, or less than the object pointed to by s2. 1236 **/ 1237 int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n); 1238 1239 /* ##################### String Searching ############################## */ 1240 1241 /** The wcschr function locates the first occurrence of C in the wide string 1242 pointed to by S. The terminating null wide character is considered to be 1243 part of the wide string. 1244 1245 @return The wcschr function returns a pointer to the located wide 1246 character, or a null pointer if the wide character does not occur 1247 in the wide string. 1248 **/ 1249 wchar_t *wcschr(const wchar_t *S, wchar_t C); 1250 1251 /** The wcscspn function computes the length of the maximum initial segment of 1252 the wide string pointed to by s1 which consists entirely of wide characters 1253 not from the wide string pointed to by s2. 1254 1255 @return The wcscspn function returns the length of the segment. 1256 **/ 1257 size_t wcscspn(const wchar_t *s1, const wchar_t *s2); 1258 1259 /** The wcspbrk function locates the first occurrence in the wide string 1260 pointed to by s1 of any wide character from the wide string 1261 pointed to by s2. 1262 1263 @return The wcspbrk function returns a pointer to the wide character 1264 in s1, or a null pointer if no wide character from s2 occurs 1265 in s1. 1266 **/ 1267 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); 1268 1269 /** The wcsrchr function locates the last occurrence of C in the wide string 1270 pointed to by S. The terminating null wide character is considered to be 1271 part of the wide string. 1272 1273 @return The wcsrchr function returns a pointer to the wide character, 1274 or a null pointer if C does not occur in the wide string. 1275 **/ 1276 wchar_t *wcsrchr(const wchar_t *S, wchar_t C); 1277 1278 /** The wcsspn function computes the length of the maximum initial segment of 1279 the wide string pointed to by s1 which consists entirely of wide characters 1280 from the wide string pointed to by s2. 1281 1282 @return The wcsspn function returns the length of the segment. 1283 **/ 1284 size_t wcsspn(const wchar_t *s1, const wchar_t *s2); 1285 1286 /** The wcsstr function locates the first occurrence in the wide string pointed 1287 to by s1 of the sequence of wide characters (excluding the terminating null 1288 wide character) in the wide string pointed to by s2. 1289 1290 @return The wcsstr function returns a pointer to the located wide string, 1291 or a null pointer if the wide string is not found. If s2 points 1292 to a wide string with zero length, the function returns s1. 1293 **/ 1294 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); 1295 1296 /** A sequence of calls to the wcstok function breaks the wide string pointed 1297 to by s1 into a sequence of tokens, each of which is delimited by a wide 1298 character from the wide string pointed to by s2. The third argument points 1299 to a caller-provided wchar_t pointer into which the wcstok function stores 1300 information necessary for it to continue scanning the same wide string. 1301 1302 The first call in a sequence has a non-null first argument and stores an 1303 initial value in the object pointed to by ptr. Subsequent calls in the 1304 sequence have a null first argument and the object pointed to by ptr is 1305 required to have the value stored by the previous call in the sequence, 1306 which is then updated. The separator wide string pointed to by s2 may be 1307 different from call to call. 1308 1309 The first call in the sequence searches the wide string pointed to by s1 1310 for the first wide character that is not contained in the current separator 1311 wide string pointed to by s2. If no such wide character is found, then 1312 there are no tokens in the wide string pointed to by s1 and the wcstok 1313 function returns a null pointer. If such a wide character is found, it is 1314 the start of the first token. 1315 1316 The wcstok function then searches from there for a wide character that is 1317 contained in the current separator wide string. If no such wide character 1318 is found, the current token extends to the end of the wide string pointed 1319 to by s1, and subsequent searches in the same wide string for a token 1320 return a null pointer. If such a wide character is found, it is overwritten 1321 by a null wide character, which terminates the current token. 1322 1323 In all cases, the wcstok function stores sufficient information in the 1324 pointer pointed to by ptr so that subsequent calls, with a null pointer for 1325 s1 and the unmodified pointer value for ptr, shall start searching just 1326 past the element overwritten by a null wide character (if any). 1327 1328 @return The wcstok function returns a pointer to the first wide character 1329 of a token, or a null pointer if there is no token. 1330 **/ 1331 wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr); 1332 1333 /** The wmemchr function locates the first occurrence of C in the initial n 1334 wide characters of the object pointed to by S. 1335 1336 @return The wmemchr function returns a pointer to the located wide 1337 character, or a null pointer if the wide character does not occur 1338 in the object. 1339 **/ 1340 wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n); 1341 1342 /* ################### String Manipulation ############################# */ 1343 1344 /** The wcslen function computes the length of the wide string pointed to by S. 1345 1346 @return The wcslen function returns the number of wide characters that 1347 precede the terminating null wide character. 1348 **/ 1349 size_t wcslen(const wchar_t *S); 1350 1351 /** The wmemset function copies the value of C into each of the first n wide 1352 characters of the object pointed to by S. 1353 1354 @return The wmemset function returns the value of S. 1355 **/ 1356 wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n); 1357 1358 /* ################# Date and Time Conversion ########################### */ 1359 1360 /** 1361 The wcsftime function is equivalent to the strftime function, except that: 1362 - The argument s points to the initial element of an array of wide characters into which 1363 the generated output is to be placed. 1364 - The argument maxsize indicates the limiting number of wide characters. 1365 - The argument format is a wide string and the conversion specifiers are replaced by 1366 corresponding sequences of wide characters. 1367 - The return value indicates the number of wide characters. 1368 1369 If the total number of resulting wide characters including the terminating null wide 1370 character is not more than maxsize, the wcsftime function returns the number of 1371 wide characters placed into the array pointed to by s not including the terminating null 1372 wide character. Otherwise, zero is returned and the contents of the array are 1373 indeterminate. 1374 **/ 1375 size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr); 1376 1377 /* ############# Multibyte <--> Wide Character Conversion ############### */ 1378 1379 /** The btowc function determines whether C constitutes a valid single-byte 1380 character in the initial shift state. 1381 1382 @return The btowc function returns WEOF if c has the value EOF or if 1383 (unsigned char)C does not constitute a valid single-byte 1384 character in the initial shift state. Otherwise, it returns the 1385 wide character representation of that character. 1386 **/ 1387 wint_t btowc(int C); 1388 1389 /** The wctob function determines whether C corresponds to a member of the extended 1390 character set whose multibyte character representation is a single byte when in the initial 1391 shift state. 1392 1393 @return The wctob function returns EOF if C does not correspond to a multibyte 1394 character with length one in the initial shift state. Otherwise, it 1395 returns the single-byte representation of that character as an 1396 unsigned char converted to an int. 1397 **/ 1398 int wctob(wint_t C); 1399 1400 /** If ps is not a null pointer, the mbsinit function determines whether the 1401 pointed-to mbstate_t object describes an initial conversion state. 1402 1403 @return The mbsinit function returns nonzero if ps is a null pointer 1404 or if the pointed-to object describes an initial conversion 1405 state; otherwise, it returns zero. 1406 **/ 1407 int mbsinit(const mbstate_t *ps); 1408 1409 /* ####### Restartable Multibyte <--> Wide Character Conversion ######### */ 1410 1411 /** The mbrlen function is equivalent to the call:<BR> 1412 @verbatim 1413 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal) 1414 @endverbatim 1415 where internal is the mbstate_t object for the mbrlen function, except that 1416 the expression designated by ps is evaluated only once. 1417 1418 @param[in] s Pointer to a multibyte character sequence. 1419 @param[in] n Maximum number of bytes to examine. 1420 @param[in] pS Pointer to the conversion state object. 1421 1422 @retval 0 The next n or fewer characters complete a NUL. 1423 @retval 1..n The number of bytes that complete the multibyte character. 1424 @retval -2 The next n bytes contribute to an incomplete (but potentially valid) multibyte character. 1425 @retval -1 An encoding error occurred. 1426 **/ 1427 size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict pS); 1428 1429 /** Restartable Multibyte to Wide character conversion. 1430 If S is a null pointer, the mbrtowc function is equivalent to the call:<BR> 1431 @verbatim 1432 mbrtowc(NULL, "", 1, ps) 1433 @endverbatim 1434 1435 In this case, the values of the parameters pwc and n are ignored. 1436 1437 If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with 1438 the byte pointed to by S to determine the number of bytes needed to complete the next 1439 multibyte character (including any shift sequences). If the function determines that the 1440 next multibyte character is complete and valid, it determines the value of the 1441 corresponding wide character and then, if pwc is not a null pointer, stores that value in 1442 the object pointed to by pwc. If the corresponding wide character is the null wide 1443 character, the resulting state described is the initial conversion state. 1444 1445 @retval 0 if the next n or fewer bytes complete the multibyte 1446 character that corresponds to the null wide 1447 character (which is the value stored). 1448 @retval between_1_and_n_inclusive if the next n or fewer bytes complete 1449 a valid multibyte character (which is the value 1450 stored); the value returned is the number of bytes 1451 that complete the multibyte character. 1452 @retval (size_t)(-2) if the next n bytes contribute to an incomplete 1453 (but potentially valid) multibyte character, and 1454 all n bytes have been processed (no value is stored). 1455 @retval (size_t)(-1) if an encoding error occurs, in which case the next 1456 n or fewer bytes do not contribute to a complete and 1457 valid multibyte character (no value is stored); the 1458 value of the macro EILSEQ is stored in errno, and 1459 the conversion state is unspecified. 1460 **/ 1461 size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps); 1462 1463 /** 1464 If S is a null pointer, the wcrtomb function is equivalent to the call:<BR> 1465 @verbatim 1466 wcrtomb(buf, L'\0', ps) 1467 @endverbatim 1468 where buf is an internal buffer. 1469 1470 If S is not a null pointer, the wcrtomb function determines the number of bytes needed 1471 to represent the multibyte character that corresponds to the wide character given by wc 1472 (including any shift sequences), and stores the multibyte character representation in the 1473 array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If 1474 wc is a null wide character, a null byte is stored, preceded by any shift sequence needed 1475 to restore the initial shift state; the resulting state described is the initial conversion state. 1476 1477 @return The wcrtomb function returns the number of bytes stored in the 1478 array object (including any shift sequences). When wc is not a 1479 valid wide character, an encoding error occurs: the function 1480 stores the value of the macro EILSEQ in errno and 1481 returns (size_t)(-1); the conversion state is unspecified. 1482 **/ 1483 size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps); 1484 1485 /** Convert a sequence of multibyte characters into a sequence of wide characters. 1486 The mbsrtowcs function converts a sequence of multibyte characters that begins in the 1487 conversion state described by the object pointed to by ps, from the array indirectly 1488 pointed to by src into a sequence of corresponding wide characters. If dst is not a null 1489 pointer, the converted characters are stored into the array pointed to by dst. Conversion 1490 continues up to and including a terminating null character, which is also stored. 1491 Conversion stops earlier in two cases: when a sequence of bytes is encountered that does 1492 not form a valid multibyte character, or (if dst is not a null pointer) when len wide 1493 characters have been stored into the array pointed to by dst. Each conversion takes 1494 place as if by a call to the mbrtowc function. 1495 1496 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null 1497 pointer (if conversion stopped due to reaching a terminating null character) or the address 1498 just past the last multibyte character converted (if any). If conversion stopped due to 1499 reaching a terminating null character and if dst is not a null pointer, the resulting state 1500 described is the initial conversion state. 1501 1502 @param[in] dst Destination for the Wide character sequence. 1503 @param[in] src Pointer to Pointer to MBCS char. sequence to convert. 1504 @param[in] len Length of dest, in WIDE characters. 1505 @param[in] ps Pointer to the conversion state object to be used for this conversion. 1506 1507 @return If the input conversion encounters a sequence of bytes that do 1508 not form a valid multibyte character, an encoding error occurs: 1509 the mbsrtowcs function stores the value of the macro EILSEQ in 1510 errno and returns (size_t)(-1); the conversion state is 1511 unspecified. Otherwise, it returns the number of multibyte 1512 characters successfully converted, not including the terminating 1513 null character (if any). 1514 **/ 1515 size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps); 1516 1517 /** The wcsrtombs function converts a sequence of wide characters from the array 1518 indirectly pointed to by src into a sequence of corresponding multibyte 1519 characters that begins in the conversion state described by the object 1520 pointed to by ps. If dst is not a null pointer, the converted characters 1521 are then stored into the array pointed to by dst. Conversion continues 1522 up to and including a terminating null wide character, which is also 1523 stored. Conversion stops earlier in two cases: when a wide character is 1524 reached that does not correspond to a valid multibyte character, or 1525 (if dst is not a null pointer) when the next multibyte character would 1526 exceed the limit of len total bytes to be stored into the array pointed 1527 to by dst. Each conversion takes place as if by a call to the wcrtomb 1528 function.) 1529 1530 If dst is not a null pointer, the pointer object pointed to by src is 1531 assigned either a null pointer (if conversion stopped due to reaching 1532 a terminating null wide character) or the address just past the last wide 1533 character converted (if any). If conversion stopped due to reaching a 1534 terminating null wide character, the resulting state described is the 1535 initial conversion state. 1536 1537 @param[in] dst Destination for the MBCS sequence. 1538 @param[in] src Pointer to Pointer to wide char. sequence to convert. 1539 @param[in] len Length of dest, in bytes. 1540 @param[in] ps Pointer to the conversion state object to be used for this conversion. 1541 1542 @return If conversion stops because a wide character is reached that 1543 does not correspond to a valid multibyte character, an 1544 encoding error occurs: the wcsrtombs function stores the 1545 value of the macro EILSEQ in errno and returns (size_t)(-1); 1546 the conversion state is unspecified. Otherwise, it returns 1547 the number of bytes in the resulting multibyte character 1548 sequence, not including the terminating null character (if any). 1549 **/ 1550 size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps); 1551 1552 #endif /* _WCHAR_H */ 1553
