summaryrefslogtreecommitdiff
path: root/StdLib/Include/wchar.h
blob: 2c9ec6e5e784417174c862b107e003747a78abdb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
/** @file
    Extended multibyte and wide character utilities.

    Within this implementation, multibyte characters are represented using the
    Unicode UTF-8 encoding and wide characters are represented using the
    16-bit UCS-2 encoding.

    Unless explicitly stated otherwise, if the execution of a function declared
    in this file causes copying to take place between objects that overlap, the
    behavior is undefined.

    The following macros are defined in this file:<BR>
    @verbatim
      NULL        Actually defined in <sys/EfiCdefs.h>
      WCHAR_MIN   Minimum value of a wide char.
      WCHAR_MAX   Maximum value of a wide char.
      WEOF        Wide char version of end-of-file.
    @endverbatim

    The following types are defined in this file:<BR>
    @verbatim
      size_t      Unsigned integer type of the result of the sizeof operator.
      wchar_t     Type of wide characters.
      wint_t      Type capable of holding all wchar_t values and WEOF.
      mbstate_t   Type of object holding multibyte conversion state.
      struct tm   Incomplete declaration of the broken-down time structure.
    @endverbatim

    The following functions are declared in this file:<BR>
@verbatim
      ###############  Formatted Input/Output Functions
      int       fwprintf  (FILE * __restrict stream,
                           const wchar_t * __restrict format, ...);
      int       fwscanf   (FILE * __restrict stream,
                           const wchar_t * __restrict format, ...);
      int       swprintf  (wchar_t * __restrict s,  size_t n,
                           const wchar_t * __restrict format, ...);
      int       swscanf   (const wchar_t * __restrict s,
                           const wchar_t * __restrict format, ...);
      int       vfwprintf (FILE * __restrict stream,
                           const wchar_t * __restrict format,   va_list arg);
      int       vfwscanf  (FILE * __restrict stream,
                           const wchar_t * __restrict format,   va_list arg);
      int       vswprintf (wchar_t * __restrict s,  size_t n,
                           const wchar_t * __restrict format,   va_list arg);
      int       vswscanf  (const wchar_t * __restrict s,
                           const wchar_t * __restrict format,   va_list arg);
      int       vwprintf  (const wchar_t * __restrict format,   va_list arg);
      int       vwscanf   (const wchar_t * __restrict format,   va_list arg);
      int       wprintf   (const wchar_t * __restrict format, ...);
      int       wscanf    (const wchar_t * __restrict format, ...);

      ###################  Input/Output Functions
      wint_t    fgetwc    (FILE *stream);
      wchar_t  *fgetws    (wchar_t * __restrict S,  int n,
                           FILE * __restrict stream);
      wint_t    fputwc    (wchar_t c, FILE *stream);
      int       fputws    (const wchar_t * __restrict S,
                           FILE * __restrict stream);
      int       fwide     (FILE *stream, int mode);
      wint_t    getwc     (FILE *stream);
      wint_t    getwchar  (void);
      wint_t    putwc     (wchar_t c, FILE *stream);
      wint_t    putwchar  (wchar_t c);
      wint_t    ungetwc   (wint_t c, FILE *stream);

      ###################  Numeric Conversions
      double                  wcstod    (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr);
      float                   wcstof    (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr);
      long double             wcstold   (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr);
      long int                wcstol    (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr, int base);
      long long int           wcstoll   (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr, int base);
      unsigned long int       wcstoul   (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr, int base);
      unsigned long long int  wcstoull  (const wchar_t * __restrict nptr,
                                         wchar_t ** __restrict endptr, int base);

      #######################  String Copying
      wchar_t  *wcscpy    (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2);
      wchar_t  *wcsncpy   (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2,   size_t n);
      wchar_t  *wmemcpy   (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2,   size_t n);
      wchar_t  *wmemmove  (wchar_t *s1, const wchar_t *s2,  size_t n);

      ###################  String Concatenation
      wchar_t  *wcscat    (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2);
      wchar_t  *wcsncat   (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2,   size_t n);

      #####################  String Comparison
      int       wcscmp    (const wchar_t *s1, const wchar_t *s2);
      int       wcscoll   (const wchar_t *s1, const wchar_t *s2);
      int       wcsncmp   (const wchar_t *s1, const wchar_t *s2,  size_t n);
      size_t    wcsxfrm   (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2,   size_t n);
      int       wmemcmp   (const wchar_t *s1,  const wchar_t *s2,  size_t n);

      #####################  String Searching
      wchar_t  *wcschr    (const wchar_t *S, wchar_t c);
      size_t    wcscspn   (const wchar_t *s1, const wchar_t *s2);
      wchar_t  *wcspbrk   (const wchar_t *s1, const wchar_t *s2);
      wchar_t  *wcsrchr   (const wchar_t *S, wchar_t c);
      size_t    wcsspn    (const wchar_t *s1, const wchar_t *s2);
      wchar_t  *wcsstr    (const wchar_t *s1, const wchar_t *s2);
      wchar_t  *wcstok    (wchar_t * __restrict s1,
                           const wchar_t * __restrict s2,
                           wchar_t ** __restrict ptr);
      wchar_t  *wmemchr   (const wchar_t *S,  wchar_t c,  size_t n);

      ###################  String Manipulation
      size_t    wcslen    (const wchar_t *S);
      wchar_t  *wmemset   (wchar_t *S,  wchar_t c,  size_t n);

      #################  Date and Time Conversion
      size_t    wcsftime  (wchar_t * __restrict S,  size_t maxsize,
                           const wchar_t * __restrict format,
                           const struct tm * __restrict timeptr);

      #############  Multibyte <--> Wide Character Conversion
      wint_t    btowc     (int c);
      int       wctob     (wint_t c);
      int       mbsinit   (const mbstate_t *ps);

      #######  Restartable Multibyte <--> Wide Character Conversion
      size_t    mbrlen    (const char * __restrict S,   size_t n,
                           mbstate_t * __restrict ps);
      size_t    mbrtowc   (wchar_t * __restrict pwc,  const char * __restrict S,
                           size_t n, mbstate_t * __restrict ps);
      size_t    wcrtomb   (char * __restrict S,   wchar_t wc,
                           mbstate_t * __restrict ps);
      size_t    mbsrtowcs (wchar_t * __restrict dst,
                           const char ** __restrict src,  size_t len,
                           mbstate_t * __restrict ps);
      size_t    wcsrtombs (char * __restrict dst,
                           const wchar_t ** __restrict src,
                           size_t len,  mbstate_t * __restrict ps);
@endverbatim

    @note   Properly constructed programs will take the following into consideration:
              - wchar_t and wint_t may be the same integer type.
              - WEOF might be a different value than that of EOF.
              - WEOF might not be negative.
              - mbstate_t objects are not intended to be inspected by programs.

    Copyright (c) 2010 - 2012, Intel Corporation. All rights reserved.<BR>
    This program and the accompanying materials are licensed and made available under
    the terms and conditions of the BSD License that accompanies this distribution.
    The full text of the license may be found at
    http://opensource.org/licenses/bsd-license.

    THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
    WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _WCHAR_H
#define _WCHAR_H
#include  <sys/EfiCdefs.h>
#include  <machine/ansi.h>
#include  <machine/limits.h>
#include  <stdarg.h>
#include  <stdio.h>

#if defined(_MSC_VER)
  #pragma warning ( disable : 4142 )
#endif

#ifdef _EFI_SIZE_T_
  typedef _EFI_SIZE_T_    size_t;   /**< Unsigned integer type of the result of the sizeof operator. */
  #undef _BSD_SIZE_T_
  #undef _EFI_SIZE_T_
#endif

#ifndef __cplusplus
  #ifdef _EFI_WCHAR_T
    /** An integer type capable of representing all distinct codes in the
        UCS-2 encoding supported by UEFI.
    **/
    typedef _EFI_WCHAR_T  wchar_t;
    #undef _BSD_WCHAR_T_
    #undef  _EFI_WCHAR_T
  #endif
#endif

#ifdef _BSD_MBSTATE_T_
  /** mbstate_t is an opaque object, that is not an array type, used to keep
      conversion state during multibyte stream conversions.
   */
  typedef _BSD_MBSTATE_T_ mbstate_t;
  #undef _BSD_MBSTATE_T_
#endif

#ifdef _EFI_WINT_T
  /** wint_t is an integer type unchanged by default argument promotions that can
      hold any value corresponding to members of the extended character set, as
      well as at least one value that does not correspond to any member of the
      extended character set: WEOF.
  */
  typedef _EFI_WINT_T     wint_t;
  #undef _BSD_WINT_T_
  #undef _EFI_WINT_T
#endif

#ifndef WCHAR_MIN
  /** @{
      Since wchar_t is an unsigned 16-bit value, it has a minimum value of 0, and
      a maximum value defined by __USHRT_MAX (65535 on IA processors).
  */
  #define WCHAR_MIN       0
  #define WCHAR_MAX       __USHRT_MAX
  /*@}*/
#endif

#ifndef WEOF
  /** WEOF expands to a constant expression of type wint_t whose value does not
      correspond to any member of the extended character set. It is accepted
      (and returned) by several functions, declared in this file, to indicate
      end-of-file, that is, no more input from a stream. It is also used as a
      wide character value that does not correspond to any member of the
      extended character set.
  */
  #define WEOF  ((wint_t)-1)
#endif

/* limits of wint_t -- These are NOT specified by ISO/IEC 9899 */
#ifndef WINT_MIN
  #define WINT_MIN        _EFI_WINT_MIN       /* wint_t   */
  #define WINT_MAX        _EFI_WINT_MAX       /* wint_t   */
#endif

/** Type struct tm is declared here as an incomplete structure type for use as an argument
    type by the wcsftime function.  The full structure declaration is in <time.h>.
*/
struct  tm;

/* ###############  Formatted Input/Output Functions  ##################### */

/** The fwprintf function writes output to the stream pointed to by stream,
    under control of the wide string pointed to by format that specifies how
    subsequent arguments are converted for output. If there are insufficient
    arguments for the format, the behavior is undefined. If the format is
    exhausted while arguments remain, the excess arguments are evaluated
    (as always) but are otherwise ignored. The fwprintf function returns
    when the end of the format string is encountered.

    The format is composed of zero or more directives: ordinary wide characters
    (not %), which are copied unchanged to the output stream; and conversion
    specifications, each of which results in fetching zero or more subsequent
    arguments, converting them, if applicable, according to the corresponding
    conversion specifier, and then writing the result to the output stream.

    Each conversion specification is introduced by the wide character %. After
    the %, the following appear in sequence:
      * Zero or more flags (in any order) that modify the meaning of the
        conversion specification.
      * An optional minimum field width. If the converted value has fewer wide
        characters than the field width, it is padded with spaces (by default)
        on the left (or right, if the left adjustment flag, described later,
        has been given) to the field width. The field width takes the form of
        an asterisk * (described later) or a nonnegative decimal integer.
      * An optional precision that gives the minimum number of digits to appear
        for the d, i, o, u, x, and X conversions, the number of digits to
        appear after the decimal-point wide character for e, E, f, and F
        conversions, the maximum number of significant digits for the g and G
        conversions, or the maximum number of wide characters to be written
        for s conversions. The precision takes the form of a period (.)
        followed either by an asterisk * (described later) or by an optional
        decimal integer; if only the period is specified, the precision is
        taken as zero. If a precision appears with any other conversion
        specifier, the behavior is undefined.
      * An optional length modifier that specifies the size of the argument.
      * A conversion specifier wide character that specifies the type of
        conversion to be applied.

    As noted above, a field width, or precision, or both, may be indicated by
    an asterisk. In this case, an int argument supplies the field width or
    precision. The arguments specifying field width, or precision, or both,
    must appear (in that order) before the argument (if any) to be converted.
    A negative field width argument is taken as a - flag followed by a positive
    field width. A negative precision argument is taken as if the precision
    were omitted.

    The flag wide characters and their meanings are:<BR>
    -     The result of the conversion is left-justified within the field.
          (It is right-justified if this flag is not specified.)
    +     The result of a signed conversion always begins with a plus or minus
          sign. (It begins with a sign only when a negative value is converted
          if this flag is not specified.)
    space If the first wide character of a signed conversion is not a sign, or
          if a signed conversion results in no wide characters, a space is
          prefixed to the result. If the space and + flags both appear, the
          space flag is ignored.
    #     The result is converted to an "alternative form". For o conversion,
          it increases the precision, if and only if necessary, to force the
          first digit of the result to be a zero (if the value and precision
          are both 0, a single 0 is printed). For x (or X) conversion, a
          nonzero result has 0x (or 0X) prefixed to it. For e, E, f, F, g,
          and G conversions, the result of converting a floating-point number
          always contains a decimal-point wide character, even if no digits
          follow it. (Normally, a decimal-point wide character appears in the
          result of these conversions only if a digit follows it.) For g and G
          conversions, trailing zeros are not removed from the result. For
          other conversions, the behavior is undefined.
    0     For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros
          (following any indication of sign or base) are used to pad to the
          field width rather than performing space padding, except when
          converting an infinity or NaN. If the 0 and - flags both appear,
          the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a
          precision is specified, the 0 flag is ignored. For other conversions,
          the behavior is undefined.

    The length modifiers and their meanings are:<BR>
    hh    Specifies that a following d, i, o, u, x, or X conversion specifier
          applies to a signed char or unsigned char argument (the argument
          will have been promoted according to the integer promotions, but its
          value shall be converted to signed char or unsigned char before
          printing); or that a following n conversion specifier applies to a
          pointer to a signed char argument.
    h     Specifies that a following d, i, o, u, x, or X conversion specifier
          applies to a short int or unsigned short int argument (the argument
          will have been promoted according to the integer promotions, but its
          value shall be converted to short int or unsigned short int before
          printing); or that a following n conversion specifier applies to a
          pointer to a short int argument.
    l (ell)   Specifies that a following d, i, o, u, x, or X conversion
              specifier applies to a long int or unsigned long int argument;
              that a following n conversion specifier applies to a pointer to a
              long int argument; that a following c conversion specifier
              applies to a wint_t argument; that a following s conversion
              specifier applies to a pointer to a wchar_t argument; or has no
              effect on a following e, E, f, F, g, or G conversion specifier.
    ll (ell-ell)  Specifies that a following d, i, o, u, x, or X conversion
                  specifier applies to a long long int or unsigned long long int
                  argument; or that a following n conversion specifier applies
                  to a pointer to a long long int argument.
    j     Specifies that a following d, i, o, u, x, or X conversion specifier
          applies to an intmax_t or uintmax_t argument; or that a following
          n conversion specifier applies to a pointer to an intmax_t argument.
    z     Specifies that a following d, i, o, u, x, or X conversion specifier
          applies to a size_t or the corresponding signed integer type
          argument; or that a following n conversion specifier applies to a
          pointer to a signed integer type corresponding to size_t argument.
    t     Specifies that a following d, i, o, u, x, or X conversion specifier
          applies to a ptrdiff_t or the corresponding unsigned integer type
          argument; or that a following n conversion specifier applies to a
          pointer to a ptrdiff_t argument.
    L     Specifies that a following a, A, e, E, f, F, g, or G conversion
          specifier applies to a long double argument.

    If a length modifier appears with any conversion specifier other than as
    specified above, the behavior is undefined.

    The conversion specifiers and their meanings are:<BR>
    d,i     The int argument is converted to signed decimal in the
            style [-]dddd. The precision specifies the minimum number of digits
            to appear; if the value being converted can be represented in fewer
            digits, it is expanded with leading zeros. The default precision
            is 1. The result of converting a zero value with a precision of
            zero is no wide characters.
    o,u,x,X The unsigned int argument is converted to unsigned octal (o),
            unsigned decimal (u), or unsigned hexadecimal notation (x or X) in
            the style dddd; the letters abcdef are used for x conversion and
            the letters ABCDEF for X conversion. The precision specifies the
            minimum number of digits to appear; if the value being converted
            can be represented in fewer digits, it is expanded with leading
            zeros. The default precision is 1. The result of converting a zero
            value with a precision of zero is no wide characters.
    f,F     A double argument representing a floating-point number is converted
            to decimal notation in the style [-]ddd.ddd, where the number of
            digits after the decimal-point wide character is equal to the
            precision specification. If the precision is missing, it is taken
            as 6; if the precision is zero and the # flag is not specified, no
            decimal-point wide character appears. If a decimal-point wide
            character appears, at least one digit appears before it. The value
            is rounded to the appropriate number of digits.<BR>
            A double argument representing an infinity is converted to [-]inf.
            A double argument representing a NaN is converted to [-]nan.
            The F conversion specifier produces INF or NAN instead
            of inf or nan, respectively.
    e,E     A double argument representing a floating-point number is converted
            in the style [-]d.ddd e +/- dd, where there is one digit (which is
            nonzero if the argument is nonzero) before the decimal-point wide
            character and the number of digits after it is equal to the
            precision; if the precision is missing, it is taken as 6; if the
            precision is zero and the # flag is not specified, no decimal-point
            wide character appears. The value is rounded to the appropriate
            number of digits. The E conversion specifier produces a number with
            E instead of e introducing the exponent. The exponent always
            contains at least two digits, and only as many more digits as
            necessary to represent the exponent. If the value is zero, the
            exponent is zero. A double argument representing an infinity or NaN
            is converted in the style of an f or F conversion specifier.
    g,G     A double argument representing a floating-point number is converted
            in style f or e (or in style F or E in the case of a G conversion
            specifier), depending on the value converted and the precision.
            Let P equal the precision if nonzero, 6 if the precision is
            omitted, or 1 if the precision is zero. Then, if a conversion with
            style E would have an exponent of X:
              - if P > X = -4, the conversion is with style f (or F) and
                precision P - (X + 1).
              - otherwise, the conversion is with style e (or E) and
                precision P - 1.
            Finally, unless the # flag is used, any trailing zeros are removed
            from the fractional portion of the result and the decimal-point
            wide character is removed if there is no fractional portion
            remaining.  A double argument representing an infinity or NaN is
            converted in the style of an f or F conversion specifier.
    c       If no l length modifier is present, the int argument is converted
            to a wide character as if by calling btowc and the resulting wide
            character is written.  If an l length modifier is present, the
            wint_t argument is converted to wchar_t and written.
    s       If no l length modifier is present, the argument shall be a pointer
            to the initial element of a character array containing a multibyte
            character sequence beginning in the initial shift state. Characters
            from the array are converted as if by repeated calls to the mbrtowc
            function, with the conversion state described by an mbstate_t
            object initialized to zero before the first multibyte character is
            converted, and written up to (but not including) the terminating
            null wide character. If the precision is specified, no more than
            that many wide characters are written. If the precision is not
            specified or is greater than the size of the converted array, the
            converted array shall contain a null wide character.<BR>
            If an l length modifier is present, the argument shall be a pointer
            to the initial element of an array of wchar_t type. Wide characters
            from the array are written up to (but not including) a terminating
            null wide character. If the precision is specified, no more than
            that many wide characters are written. If the precision is not
            specified or is greater than the size of the array, the array
            shall contain a null wide character.
    p       The argument shall be a pointer to void. The value of the pointer
            is converted to a sequence of printing wide characters, in an
            implementation-defined manner.
    n       The argument shall be a pointer to signed integer into which is
            written the number of wide characters written to the output stream
            so far by this call to fwprintf. No argument is converted, but one
            is consumed. If the conversion specification includes any flags, a
            field width, or a precision, the behavior is undefined.
    %       A % wide character is written. No argument is converted. The
            complete conversion specification is %%.


    @param[in]  stream    An open File specifier to which the output is sent.
    @param[in]  format    A wide character sequence containing characters
                          to be copied unchanged, and conversion specifiers
                          which convert their associated arguments.
    @param      ...       Variable number of parameters as required by format.

    @return   The fwprintf function returns the number of wide characters
              transmitted, or a negative value if an output or encoding error
              occurred.
**/
int fwprintf(FILE * __restrict stream, const wchar_t * __restrict format, ...);

/** The fwscanf function reads input from the stream pointed to by stream,
    under control of the wide string pointed to by format that specifies
    the admissible input sequences and how they are to be converted for
    assignment, using subsequent arguments as pointers to the objects to
    receive the converted input. If there are insufficient arguments for
    the format, the behavior is undefined. If the format is exhausted while
    arguments remain, the excess arguments are evaluated (as always) but are
    otherwise ignored.

    The format is composed of zero or more directives: one or more white-space
    wide characters, an ordinary wide character (neither % nor a white-space
    wide character), or a conversion specification. Each conversion
    specification is introduced by the wide character %. After the %, the
    following appear in sequence:
      - An optional assignment-suppressing wide character *.
      - An optional decimal integer greater than zero that specifies the
        maximum field width (in wide characters).
      - An optional length modifier that specifies the size of the receiving object.
      - A conversion specifier wide character that specifies the type of
        conversion to be applied.

    The fwscanf function executes each directive of the format in turn. If a
    directive fails, as detailed below, the function returns. Failures are
    described as input failures (due to the occurrence of an encoding error
    or the unavailability of input characters), or matching failures
    (due to inappropriate input).

    A directive composed of white-space wide character(s) is executed by
    reading input up to the first non-white-space wide character (which remains
    unread), or until no more wide characters can be read.

    A directive that is an ordinary wide character is executed by reading the
    next wide character of the stream. If that wide character differs from the
    directive, the directive fails and the differing and subsequent wide
    characters remain unread. Similarly, if end-of-file, an encoding error, or
    a read error prevents a wide character from being read, the directive fails.

    A directive that is a conversion specification defines a set of matching
    input sequences, as described below for each specifier. A conversion
    specification is executed in the following steps:
      - Input white-space wide characters (as specified by the iswspace
        function) are skipped, unless the specification includes
        a [, c, or n specifier.
      - An input item is read from the stream, unless the specification
        includes an n specifier. An input item is defined as the longest
        sequence of input wide characters which does not exceed any specified
        field width and which is, or is a prefix of, a matching input sequence.
        The first wide character, if any, after the input item remains unread.
        If the length of the input item is zero, the execution of the directive
        fails; this condition is a matching failure unless end-of-file, an
        encoding error, or a read error prevented input from the stream, in
        which case it is an input failure.
      - Except in the case of a % specifier, the input item (or, in the case of
        a %n directive, the count of input wide characters) is converted to a
        type appropriate to the conversion specifier. If the input item is not
        a matching sequence, the execution of the directive fails: this
        condition is a matching failure. Unless assignment suppression was
        indicated by a *, the result of the conversion is placed in the object
        pointed to by the first argument following the format argument that has
        not already received a conversion result. If this object does not have
        an appropriate type, or if the result of the conversion cannot be
        represented in the object, the behavior is undefined.

    The length modifiers and their meanings are:<BR>
    hh      Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to signed char
            or unsigned char.
    h       Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to short int
            or unsigned short int.
    l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to long int or
            unsigned long int; that a following e, E, f, F, g, or G conversion
            specifier applies to an argument with type pointer to double; or
            that a following c, s, or [ conversion specifier applies to an
            argument with type pointer to wchar_t.
    ll (ell-ell)  Specifies that a following d, i, o, u, x, X, or n conversion
                  specifier applies to an argument with type
                  pointer to long long int or unsigned long long int.
    j       Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to intmax_t
            or uintmax_t.
    z       Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to size_t or the
            corresponding signed integer type.
    t       Specifies that a following d, i, o, u, x, X, or n conversion
            specifier applies to an argument with type pointer to ptrdiff_t or
            the corresponding unsigned integer type.
    L       Specifies that a following e, E, f, F, g, or G conversion specifier
            applies to an argument with type pointer to long double.

    If a length modifier appears with any conversion specifier other than as
    specified above, the behavior is undefined.

    The conversion specifiers and their meanings are:<BR>
    d       Matches an optionally signed decimal integer, whose format is the
            same as expected for the subject sequence of the wcstol function
            with the value 10 for the base argument. The corresponding argument
            shall be a pointer to signed integer.
    i       Matches an optionally signed integer, whose format is the same as
            expected for the subject sequence of the wcstol function with the
            value 0 for the base argument. The corresponding argument shall be
            a pointer to signed integer.
    o       Matches an optionally signed octal integer, whose format is the
            same as expected for the subject sequence of the wcstoul function
            with the value 8 for the base argument. The corresponding argument
            shall be a pointer to unsigned integer.
    u       Matches an optionally signed decimal integer, whose format is the
            same as expected for the subject sequence of the wcstoul function
            with the value 10 for the base argument. The corresponding argument
            shall be a pointer to unsigned integer.
    x       Matches an optionally signed hexadecimal integer, whose format is
            the same as expected for the subject sequence of the wcstoul
            function with the value 16 for the base argument. The corresponding
            argument shall be a pointer to unsigned integer.
    e,f,g   Matches an optionally signed floating-point number, infinity, or
            NaN, whose format is the same as expected for the subject sequence
            of the wcstod function. The corresponding argument shall be a
            pointer to float.
    c       Matches a sequence of wide characters of exactly the number
            specified by the field width (1 if no field width is present in the
            directive).<BR>
            If no l length modifier is present, characters from the input field
            are converted as if by repeated calls to the wcrtomb function, with
            the conversion state described by an mbstate_t object initialized
            to zero before the first wide character is converted. The
            corresponding argument shall be a pointer to the initial element of
            a character array large enough to accept the sequence. No null
            character is added.<BR>
            If an l length modifier is present, the corresponding argument
            shall be a pointer to the initial element of an array of
            wchar_t large enough to accept the sequence.
            No null wide character is added.
    s       Matches a sequence of non-white-space wide characters.
            If no l length modifier is present, characters from the input field
            are converted as if by repeated calls to the wcrtomb function, with
            the conversion state described by an mbstate_t object initialized
            to zero before the first wide character is converted. The
            corresponding argument shall be a pointer to the initial element of
            a character array large enough to accept the sequence and a
            terminating null character, which will be added automatically.<BR>
            If an l length modifier is present, the corresponding argument
            shall be a pointer to the initial element of an array of wchar_t
            large enough to accept the sequence and the terminating null wide
            character, which will be added automatically.
    [       Matches a nonempty sequence of wide characters from a set of
            expected characters (the scanset).<BR>
            If no l length modifier is present, characters from the input field
            are converted as if by repeated calls to the wcrtomb function, with
            the conversion state described by an mbstate_t object initialized
            to zero before the first wide character is converted. The
            corresponding argument shall be a pointer to the initial element of
            a character array large enough to accept the sequence and a
            terminating null character, which will be added automatically.<BR>
            If an l length modifier is present, the corresponding argument
            shall be a pointer to the initial element of an array of wchar_t
            large enough to accept the sequence and the terminating null wide
            character, which will be added automatically.<BR>
            The conversion specifier includes all subsequent wide characters
            in the format string, up to and including the matching right
            bracket (]). The wide characters between the brackets
            (the scanlist) compose the scanset, unless the wide character after
            the left bracket is a circumflex (^), in which case the scanset
            contains all wide characters that do not appear in the scanlist
            between the circumflex and the right bracket. If the conversion
            specifier begins with [] or [^], the right bracket wide character
            is in the scanlist and the next following right bracket wide
            character is the matching right bracket that ends the specification;
            otherwise the first following right bracket wide character is the
            one that ends the specification. If a - wide character is in the
            scanlist and is not the first, nor the second where the first wide
            character is a ^, nor the last character,
            the - is added to the scanset.
    p       Matches the set of sequences produced by the %p conversion of the
            fwprintf function. The corresponding argument is a pointer to a
            pointer to void. The input item is converted to a pointer value. If
            the input item is a value converted earlier during the same program
            execution, the pointer that results will compare equal to that
            value.
    n       No input is consumed. The corresponding argument is a pointer to
            signed integer into which is to be written the number of wide
            characters read from the input stream so far by this call to the
            fwscanf function. Execution of a %n directive does not increment
            the assignment count returned at the completion of execution of the
            fwscanf function. No argument is converted, but one is consumed.
    %       Matches a single % wide character; no conversion or assignment
            occurs. The complete conversion specification shall be %%.

    The conversion specifiers E, F, G, and X are also valid and behave the same
    as, respectively, e, f, g, and x.

    Trailing white space (including new-line wide characters) is left unread
    unless matched by a directive. The success of literal matches and
    suppressed assignments is not directly determinable other than via
    the %n directive.

    @param[in]  stream    An open File specifier from which the input is read.
    @param[in]  format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.  Converted
                          items are stored according to their associated arguments.
    @param      ...       Variable number of parameters, as required by format,
                          specifying the objects to receive the converted input.

    @return   The fwscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              function returns the number of input items assigned, which can be
              fewer than provided for, or even zero, in the event of an early
              matching failure.
**/
int fwscanf(FILE * __restrict stream, const wchar_t * __restrict format, ...);

/** Formatted wide-character output to a buffer.

    The swprintf function is equivalent to fwprintf, except that the argument s
    specifies an array of wide characters into which the generated output is to
    be written, rather than written to a stream. No more than n wide characters
    are written, including a terminating null wide character, which is always
    added (unless n is zero).

    @param[out]   s         A pointer to the array to receive the formatted output.
    @param[in]    n         Maximum number of characters to write into buffer s.
    @param[in]    format    A wide character sequence containing characters
                            to be copied unchanged, and conversion specifiers
                            which convert their associated arguments.  Copied and
                            converted characters are written to the array pointed
                            to by s.
    @param        ...       Variable number of parameters as required by format.

    @return   The swprintf function returns the number of wide characters
              written in the array, not counting the terminating null wide
              character, or a negative value if an encoding error occurred or
              if n or more wide characters were requested to be written.
**/
int swprintf(wchar_t * __restrict s, size_t n, const wchar_t * __restrict format, ...);

/** Formatted wide input from a string.

    The swscanf function is equivalent to fwscanf, except that the argument
    Buff specifies a wide string from which the input is to be obtained, rather
    than from a stream. Reaching the end of the wide string is equivalent to
    encountering end-of-file for the fwscanf function.

    @param[in]  Buff      Pointer to the string from which to obtain input.
    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[out] ...       Variable number of parameters, as required by format,
                          specifying the objects to receive the converted input.

    @return   The swscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              swscanf function returns the number of input items assigned,
              which can be fewer than provided for, or even zero, in the event
              of an early matching failure.
**/
int swscanf(const wchar_t * __restrict Buff, const wchar_t * __restrict Format, ...);

/** Print formatted values from an argument list.

The vfwprintf function is equivalent to fwprintf, with the variable argument list
replaced by Args, which shall have been initialized by the va_start macro (and
possibly subsequent va_arg calls). The vfwprintf function does not invoke the
va_end macro.

    @param[in]  Stream    The output stream to receive the formatted output.
    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[in]  Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vfwprintf function returns the number of wide characters
              transmitted, or a negative value if an output or encoding
              error occurred.
**/
int vfwprintf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);

/** Formatted input from a stream.

    The vfwscanf function is equivalent to fwscanf, with the variable argument
    list replaced by Args, which must have been initialized by the va_start
    macro (and possibly subsequent va_arg calls). The vfwscanf function does
    not invoke the va_end macro.

    @param[in]  Stream    The input stream.
    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[in]  Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vfwscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              vfwscanf function returns the number of input items assigned,
              which can be fewer than provided for, or even zero, in the event
              of an early matching failure.
**/
int vfwscanf(FILE * __restrict Stream, const wchar_t * __restrict Format, va_list Args);

/** Formatted print, to a buffer, from an argument list.

    The vswprintf function is equivalent to swprintf, with the variable
    argument list replaced by Args, which must have been initialized by the
    va_start macro (and possibly subsequent va_arg calls). The vswprintf
    function does not invoke the va_end macro.

    @param[in]  S         A pointer to the array to receive the formatted output.
    @param[in]  N         Maximum number of characters to write into array S.
    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[in]  Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vswprintf function returns the number of wide characters
              written in the array, not counting the terminating null wide
              character, or a neg ative value if an encoding error occurred or
              if n or more wide characters were requested to be generated.
**/
int vswprintf(wchar_t * __restrict S, size_t N, const wchar_t * __restrict Format, va_list Args);

/** Formatted input from a string, using an argument list.

    The vswscanf function is equivalent to swscanf, with the variable argument
    list replaced by Args, which must have been initialized by the va_start
    macro. The vswscanf function does not invoke the va_end macro.

    @param[in]  S         Pointer to the string from which to obtain input.
    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[out] Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vswscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              vswscanf function returns the number of input items assigned,
              which can be fewer than provided for, or even zero, in the event
              of an early matching failure.
**/
int vswscanf(const wchar_t * __restrict S, const wchar_t * __restrict Format, va_list Args);

/** Formatted print, to stdout, from an argument list.

    The vwprintf function is equivalent to wprintf, with the variable argument
    list replaced by Args, which must have been initialized by the va_start
    macro. The vwprintf function does not invoke the va_end macro.

    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[out] Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vwprintf function returns the number of wide characters
              transmitted, or a negative value if an output or encoding error
              occurred.
**/
int vwprintf(const wchar_t * __restrict Format, va_list Args);

/** Formatted input, from stdin, to an argument list.

    The vwscanf function is equivalent to wscanf, with the variable argument
    list replaced by arg, which shall have been initialized by the va_start
    macro. The vwscanf function does not invoke the va_end macro.

    @param[in]  Format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.
    @param[out] Args      A list of arguments, initialized by the va_start macro
                          and accessed using the va_arg macro, used to satisfy
                          the directives in the Format string.

    @return   The vwscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              vwscanf function returns the number of input items assigned,
              which can be fewer than provided for, or even zero, in the event
              of an early matching failure.
**/
int vwscanf(const wchar_t * __restrict Format, va_list Args);

/** Formatted print to stdout.

    The wprintf function is equivalent to fwprintf with the argument stdout
    specifying the output stream.

    @param[in]  format    A wide character sequence containing characters
                          to be copied unchanged, and conversion specifiers
                          which convert their associated arguments.
    @param      ...       Variable number of parameters as required by format.

    @return   The wprintf function returns the number of wide characters
              transmitted, or a negative value if an output or encoding error
              occurred.
**/
int wprintf(const wchar_t * __restrict Format, ...);

/** Formatted input from stdin.

    The wscanf function is equivalent to fwscanf with the argument stdin
    specifying the input stream.

    @param[in]  format    A wide character sequence containing characters
                          to be matched against, and conversion specifiers
                          which convert their associated arguments.  Converted
                          items are stored according to their associated arguments.
    @param      ...       Variable number of parameters, as required by format,
                          specifying the objects to receive the converted input.

    @return   The wscanf function returns the value of the macro EOF if an
              input failure occurs before any conversion. Otherwise, the
              wscanf function returns the number of input items assigned,
              which can be fewer than provided for, or even zero, in the event
              of an early matching failure.
**/
int wscanf(const wchar_t * __restrict format, ...);

/* ###################  Input/Output Functions  ########################### */


/** Get a character from an input Stream.

If the end-of-file indicator for the input stream pointed to by stream is not set and a
next wide character is present, the fgetwc function obtains that wide character as a
wchar_t converted to a wint_t and advances the associated file position indicator for
the stream (if defined).

    @param[in]  Stream    An input stream from which to obtain a character.

    @return   If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the endof-
file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
the fgetwc function returns the next wide character from the input stream pointed to by
stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
function returns WEOF. If an encoding error occurs (including too few bytes), the value of
the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.
**/
wint_t fgetwc(FILE *Stream);

/** Read a string from an input stream into a buffer.

    The fgetws function reads at most one less than the number of
    wide characters specified by n from the stream pointed to by
    stream into the array pointed to by s. No additional wide
    characters are read after a new-line wide character (which is
    retained) or after end-of-file. A null wide character is written
    immediately after the last wide character read into the array.

    @param[out] S         A pointer to the array to receive the input string.
    @param[in]  Limit     The maximum number of characters to put into Buff,
                          including the terminating null character.
    @param[in]  Stream    An input stream from which to obtain the string.

    @return   The fgetws function returns S if successful. If end-of-file is
              encountered and no characters have been read into the array, the
              contents of the array remain unchanged and a null pointer is
              returned. If a read or encoding error occurs during the
              operation, the array contents are indeterminate and a
              null pointer is returned.
**/
wchar_t *fgetws(wchar_t * __restrict S, int Limit, FILE * __restrict Stream);

/** Write a character to an output stream.

The fputwc function writes the wide character specified by c to the output stream
pointed to by stream, at the position indicated by the associated file position indicator
for the stream (if defined), and advances the indicator appropriately. If the file cannot
support positioning requests, or if the stream was opened with append mode, the
character is appended to the output stream.

    @param[in]  C       The character to be written to Stream.
    @param[in]  Stream  The output stream that C is to be written to.

    @return   The fputwc function returns the wide character written. If a write error occurs, the
error indicator for the stream is set and fputwc returns WEOF. If an encoding error
occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
**/
wint_t fputwc(wchar_t C, FILE *Stream);

/** Write a string to an output stream.

The fputws function writes the wide string pointed to by S to the stream pointed to by
Stream. The terminating null wide character is not written.

    @param[in]  String  The character string to be written to Stream.
    @param[in]  Stream  The output stream that String is to be written to.

    @return   The fputws function returns EOF if a write or encoding error occurs; otherwise, it
returns a nonnegative value.
**/
int fputws(const wchar_t * __restrict S, FILE * __restrict Stream);

/** Query or set a stream's orientation.

The fwide function determines the orientation of the stream pointed to by stream. If
Mode is greater than zero, the function first attempts to make the stream wide oriented. If
Mode is less than zero, the function first attempts to make the stream byte oriented.
Otherwise, Mode is zero and the function does not alter the orientation of the stream.

    @param[in]  Stream    The stream to be queried.
    @param[in]  Mode      Control value selecting between quering or setting
                          the Stream's orientation.
    @return   The fwide function returns a value greater than zero if, after the call, the stream has
wide orientation, a value less than zero if the stream has byte orientation, or zero if the
stream has no orientation.
**/
int fwide(FILE *Stream, int Mode);

/** Get a character from an input stream.

The getwc function is equivalent to fgetwc, except that if it is implemented as a
macro, it may evaluate Stream more than once, so the argument should never be an
expression with side effects.

    @param[in]  Stream    The stream to be read.

    @return   The getwc function returns the next wide character from the input stream pointed to by
stream, or WEOF.
**/
wint_t getwc(FILE *Stream);

/** Get a character from stdin.

    The getwchar function is equivalent to getwc with the argument stdin.

    @return   The getwchar function returns the next wide character from the
              input stream pointed to by stdin, or WEOF.
**/
wint_t getwchar(void);

/** Write a character to an output stream.

The putwc function is equivalent to fputwc, except that if it is implemented as a
macro, it may evaluate Stream more than once, so the Stream argument should never be an
expression with side effects.

    @param[in]  C       The wide character to be written to Stream.
    @param[in]  Stream  The output stream that C is to be written to.

    @return   The putwc function returns the wide character written, or WEOF.
**/
wint_t putwc(wchar_t C, FILE *Stream);

/** Write a character to stdout.

The putwchar function is equivalent to putwc with the second argument stdout.

    @param[in]  C       The wide character to be written to stdout.

    @return   The putwchar function returns the character written, or WEOF.
**/
wint_t putwchar(wchar_t C);

/** Return a character to the input Stream as if it had not been read.

The ungetwc function pushes the wide character specified by C back onto the input
stream pointed to by Stream. Pushed-back wide characters will be returned by
subsequent reads on that stream in the reverse order of their pushing. A successful
intervening call (with the stream pointed to by Stream) to a file positioning function
(fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
stream. The external storage corresponding to the stream is unchanged.

One wide character of pushback is guaranteed, even if the call to the ungetwc function
follows just after a call to a formatted wide character input function fwscanf,
vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
on the same stream without an intervening read or file positioning operation on that
stream, the operation may fail.

If the value of C equals that of the macro WEOF, the operation fails and the input stream is
unchanged.

A successful call to the ungetwc function clears the end-of-file indicator for the stream.
The value of the file position indicator for the stream after reading or discarding all
pushed-back wide characters is the same as it was before the wide characters were pushed
back. For a text or binary stream, the value of its file position indicator after a successful
call to the ungetwc function is unspecified until all pushed-back wide characters are
read or discarded.

    @param[in]  C       The wide character to push back onto the Stream.
    @param[in]  Stream  The output stream that C is to be pushed back onto.

    @return   The ungetwc function returns the character pushed back,
              or WEOF if the operation fails.
**/
wint_t ungetwc(wint_t C, FILE *Stream);

/* ###################  Numeric Conversions     ########################### */

/** @{
The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
string pointed to by nptr to double, float, and long double representation,
respectively. First, they decompose the input string into three parts: an initial, possibly
empty, sequence of white-space wide characters (as specified by the iswspace
function), a subject sequence resembling a floating-point constant or representing an
infinity or NaN; and a final wide string of one or more unrecognized wide characters,
including the terminating null wide character of the input wide string. Then, they attempt
to convert the subject sequence to a floating-point number, and return the result.

    @param[in]  Nptr    Pointer to the string to convert to a floating-point value.
    @param[in]  EndPtr  Optional pointer to an object in which to store a pointer
                        to the final wide string.

The functions return the converted value, if any. If no conversion could be performed,
zero is returned. If the correct value is outside the range of representable values, plus or
minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the return
type and sign of the value), and the value of the macro ERANGE is stored in errno. If
the result underflows (7.12.1), the functions return a value whose magnitude is no greater
than the smallest normalized positive number in the return type. A pointer to the
final wide string is stored in the object pointed to by endptr, provided that endptr is
not a null pointer.
**/
double      wcstod  (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
float       wcstof  (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
long double wcstold (const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr);
/*@}*/

/** @{
The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
portion of the wide string pointed to by nptr to long int, long long int,
unsigned long int, and unsigned long long int representation,
respectively. First, they decompose the input string into three parts: an initial, possibly
empty, sequence of white-space wide characters (as specified by the iswspace
function), a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final wide string of one or more unrecognized wide
characters, including the terminating null wide character of the input wide string. Then,
they attempt to convert the subject sequence to an integer, and return the result.

    @param[in]  Nptr    Pointer to the string to convert to a floating-point value.
    @param[in]  EndPtr  Optional pointer to an object in which to store a pointer
                        to the final wide string.
    @param[in]  Base    Base, 0 to 36, of the value represented by the string
                        pointed to by Nptr.

    @return   The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
value, if any. If no conversion could be performed, zero is returned. If the correct value
is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
sign of the value, if any), and the value of the macro ERANGE is stored in errno.
**/
long int                wcstol  ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
long long int           wcstoll ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
unsigned long int       wcstoul ( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
unsigned long long int  wcstoull( const wchar_t * __restrict Nptr, wchar_t ** __restrict EndPtr, int Base);
/*@}*/

/* #######################  String Copying  ############################### */

/** The wcscpy function copies the wide string pointed to by Src (including the
    terminating null wide character) into the array pointed to by Dest.

    @return   The wcscpy function returns the value of Dest.
**/
wchar_t *wcscpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src);

/** The wcsncpy function copies not more than n wide characters (those that
    follow a null wide character are not copied) from the array pointed to by
    Src to the array pointed to by Dest.

    If the array pointed to by Src is a wide string that is shorter than n wide
    characters, null wide characters are appended to the copy in the array
    pointed to by Dest, until n wide characters in all have been written.

    @return   The wcsncpy function returns the value of Dest.
**/
wchar_t *wcsncpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);

/** The wmemcpy function copies n wide characters from the object pointed to by
    Src to the object pointed to by Dest.

    Use this function if you know that Dest and Src DO NOT Overlap.  Otherwise,
    use wmemmove.

    @return   The wmemcpy function returns the value of Dest.
**/
wchar_t *wmemcpy(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);

/** The wmemmove function copies n wide characters from the object pointed to by
    Src to the object pointed to by Dest. The objects pointed to by Dest and Src are
    allowed to overlap.

    Because the UEFI BaseMemoryLib function CopyMem explicitly handles
    overlapping source and destination objects, this function and wmemcpy are
    implemented identically.

    For programming clarity, it is recommended that you use wmemcpy if you know
    that Dest and Src DO NOT Overlap.  If Dest and Src might possibly overlap, then
    use wmemmove.

    @return   The wmemmove function returns the value of Dest.
**/
wchar_t *wmemmove(wchar_t *Dest, const wchar_t *Src, size_t n);

/* ###################  String Concatenation     ########################## */

/** The wcscat function appends a copy of the wide string pointed to by Src
    (including the terminating null wide character) to the end of the wide
    string pointed to by Dest. The initial wide character of Src overwrites the
    null wide character at the end of Dest.

    @return   The wcscat function returns the value of Dest.
**/
wchar_t *wcscat(wchar_t * __restrict Dest, const wchar_t * __restrict Src);

/** The wcsncat function appends not more than n wide characters (a null wide
    character and those that follow it are not appended) from the array pointed
    to by Src to the end of the wide string pointed to by Dest. The initial wide
    character of Src overwrites the null wide character at the end of Dest.
    A terminating null wide character is always appended to the result.

    @return   The wcsncat function returns the value of Dest.
**/
wchar_t *wcsncat(wchar_t * __restrict Dest, const wchar_t * __restrict Src, size_t n);

/* #####################  String Comparison   ############################# */

/** The wcscmp function compares the wide string pointed to by s1 to the wide
    string pointed to by s2.

    @return   The wcscmp function returns an integer greater than, equal to, or
              less than zero, accordingly as the wide string pointed to by s1
              is greater than, equal to, or less than the wide string
              pointed to by s2.
**/
int wcscmp(const wchar_t *s1, const wchar_t *s2);

/** The wcscoll function compares the wide string pointed to by s1 to the wide
    string pointed to by s2, both interpreted as appropriate to the LC_COLLATE
    category of the current locale.

    @return   The wcscoll function returns an integer greater than, equal to,
              or less than zero, accordingly as the wide string pointed to by
              s1 is greater than, equal to, or less than the wide string
              pointed to by s2 when both are interpreted as appropriate to
              the current locale.
**/
int wcscoll(const wchar_t *s1, const wchar_t *s2);

/** The wcsncmp function compares not more than n wide characters (those that
    follow a null wide character are not compared) from the array pointed to by
    s1 to the array pointed to by s2.

    @return   The wcsncmp function returns an integer greater than, equal to,
              or less than zero, accordingly as the possibly null-terminated
              array pointed to by s1 is greater than, equal to, or less than
              the possibly null-terminated array pointed to by s2.
**/
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);

/** The wcsxfrm function transforms the wide string pointed to by s2 and places
    the resulting wide string into the array pointed to by s1. The
    transformation is such that if the wcscmp function is applied to two
    transformed wide strings, it returns a value greater than, equal to, or
    less than zero, corresponding to the result of the wcscoll function applied
    to the same two original wide strings. No more than n wide characters are
    placed into the resulting array pointed to by s1, including the terminating
    null wide character. If n is zero, s1 is permitted to be a null pointer.

    @return   The wcsxfrm function returns the length of the transformed wide
              string (not including the terminating null wide character). If
              the value returned is n or greater, the contents of the array
              pointed to by s1 are indeterminate.
**/
size_t wcsxfrm(wchar_t * __restrict s1, const wchar_t * __restrict s2, size_t n);

/** The wmemcmp function compares the first n wide characters of the object
    pointed to by s1 to the first n wide characters of the object pointed to
    by s2.

    @return   The wmemcmp function returns an integer greater than, equal to,
              or less than zero, accordingly as the object pointed to by s1 is
              greater than, equal to, or less than the object pointed to by s2.
**/
int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);

/* #####################  String Searching   ############################## */

/** The wcschr function locates the first occurrence of C in the wide string
    pointed to by S.  The terminating null wide character is considered to be
    part of the wide string.

    @return   The wcschr function returns a pointer to the located wide
              character, or a null pointer if the wide character does not occur
              in the wide string.
**/
wchar_t *wcschr(const wchar_t *S, wchar_t C);

/** The wcscspn function computes the length of the maximum initial segment of
    the wide string pointed to by s1 which consists entirely of wide characters
    not from the wide string pointed to by s2.

    @return   The wcscspn function returns the length of the segment.
**/
size_t wcscspn(const wchar_t *s1, const wchar_t *s2);

/** The wcspbrk function locates the first occurrence in the wide string
    pointed to by s1 of any wide character from the wide string
    pointed to by s2.

    @return   The wcspbrk function returns a pointer to the wide character
              in s1, or a null pointer if no wide character from s2 occurs
              in s1.
**/
wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);

/** The wcsrchr function locates the last occurrence of C in the wide string
    pointed to by S. The terminating null wide character is considered to be
    part of the wide string.

    @return   The wcsrchr function returns a pointer to the wide character,
              or a null pointer if C does not occur in the wide string.
**/
wchar_t *wcsrchr(const wchar_t *S, wchar_t C);

/** The wcsspn function computes the length of the maximum initial segment of
    the wide string pointed to by s1 which consists entirely of wide characters
    from the wide string pointed to by s2.

    @return   The wcsspn function returns the length of the segment.
**/
size_t wcsspn(const wchar_t *s1, const wchar_t *s2);

/** The wcsstr function locates the first occurrence in the wide string pointed
    to by s1 of the sequence of wide characters (excluding the terminating null
    wide character) in the wide string pointed to by s2.

    @return   The wcsstr function returns a pointer to the located wide string,
              or a null pointer if the wide string is not found. If s2 points
              to a wide string with zero length, the function returns s1.
**/
wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);

/** A sequence of calls to the wcstok function breaks the wide string pointed
    to by s1 into a sequence of tokens, each of which is delimited by a wide
    character from the wide string pointed to by s2. The third argument points
    to a caller-provided wchar_t pointer into which the wcstok function stores
    information necessary for it to continue scanning the same wide string.

    The first call in a sequence has a non-null first argument and stores an
    initial value in the object pointed to by ptr. Subsequent calls in the
    sequence have a null first argument and the object pointed to by ptr is
    required to have the value stored by the previous call in the sequence,
    which is then updated. The separator wide string pointed to by s2 may be
    different from call to call.

    The first call in the sequence searches the wide string pointed to by s1
    for the first wide character that is not contained in the current separator
    wide string pointed to by s2. If no such wide character is found, then
    there are no tokens in the wide string pointed to by s1 and the wcstok
    function returns a null pointer. If such a wide character is found, it is
    the start of the first token.

    The wcstok function then searches from there for a wide character that is
    contained in the current separator wide string. If no such wide character
    is found, the current token extends to the end of the wide string pointed
    to by s1, and subsequent searches in the same wide string for a token
    return a null pointer. If such a wide character is found, it is overwritten
    by a null wide character, which terminates the current token.

    In all cases, the wcstok function stores sufficient information in the
    pointer pointed to by ptr so that subsequent calls, with a null pointer for
    s1 and the unmodified pointer value for ptr, shall start searching just
    past the element overwritten by a null wide character (if any).

    @return   The wcstok function returns a pointer to the first wide character
              of a token, or a null pointer if there is no token.
**/
wchar_t *wcstok(wchar_t * __restrict s1, const wchar_t * __restrict s2, wchar_t ** __restrict ptr);

/** The wmemchr function locates the first occurrence of C in the initial n
    wide characters of the object pointed to by S.

    @return   The wmemchr function returns a pointer to the located wide
              character, or a null pointer if the wide character does not occur
              in the object.
**/
wchar_t *wmemchr(const wchar_t *S, wchar_t C, size_t n);

/* ###################  String Manipulation   ############################# */

/** The wcslen function computes the length of the wide string pointed to by S.

    @return   The wcslen function returns the number of wide characters that
              precede the terminating null wide character.
**/
size_t wcslen(const wchar_t *S);

/** The wmemset function copies the value of C into each of the first n wide
    characters of the object pointed to by S.

    @return   The wmemset function returns the value of S.
**/
wchar_t *wmemset(wchar_t *S, wchar_t C, size_t n);

/* #################  Date and Time Conversion  ########################### */

/**
The wcsftime function is equivalent to the strftime function, except that:
  - The argument s points to the initial element of an array of wide characters into which
the generated output is to be placed.
  - The argument maxsize indicates the limiting number of wide characters.
  - The argument format is a wide string and the conversion specifiers are replaced by
corresponding sequences of wide characters.
  - The return value indicates the number of wide characters.

If the total number of resulting wide characters including the terminating null wide
character is not more than maxsize, the wcsftime function returns the number of
wide characters placed into the array pointed to by s not including the terminating null
wide character. Otherwise, zero is returned and the contents of the array are
indeterminate.
**/
size_t wcsftime(wchar_t * __restrict S, size_t maxsize, const wchar_t * __restrict format, const struct tm * __restrict timeptr);

/* #############  Multibyte <--> Wide Character Conversion  ############### */

/** The btowc function determines whether C constitutes a valid single-byte
    character in the initial shift state.

    @return   The btowc function returns WEOF if c has the value EOF or if
              (unsigned char)C does not constitute a valid single-byte
              character in the initial shift state. Otherwise, it returns the
              wide character representation of that character.
**/
wint_t btowc(int C);

/** The wctob function determines whether C corresponds to a member of the extended
    character set whose multibyte character representation is a single byte when in the initial
    shift state.

    @return     The wctob function returns EOF if C does not correspond to a multibyte
                character with length one in the initial shift state. Otherwise, it
                returns the single-byte representation of that character as an
                unsigned char converted to an int.
**/
int wctob(wint_t C);

/** If ps is not a null pointer, the mbsinit function determines whether the
    pointed-to mbstate_t object describes an initial conversion state.

    @return     The mbsinit function returns nonzero if ps is a null pointer
                or if the pointed-to object describes an initial conversion
                state; otherwise, it returns zero.
**/
int mbsinit(const mbstate_t *ps);

/* #######  Restartable Multibyte <--> Wide Character Conversion  ######### */

/** The mbrlen function is equivalent to the call:<BR>
@verbatim
    mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
@endverbatim
    where internal is the mbstate_t object for the mbrlen function, except that
    the expression designated by ps is evaluated only once.

    @param[in]  s     Pointer to a multibyte character sequence.
    @param[in]  n     Maximum number of bytes to examine.
    @param[in]  pS    Pointer to the conversion state object.

    @retval   0       The next n or fewer characters complete a NUL.
    @retval   1..n    The number of bytes that complete the multibyte character.
    @retval   -2      The next n bytes contribute to an incomplete (but potentially valid) multibyte character.
    @retval   -1      An encoding error occurred.
**/
size_t mbrlen(const char * __restrict S, size_t n, mbstate_t * __restrict pS);

/** Restartable Multibyte to Wide character conversion.
If S is a null pointer, the mbrtowc function is equivalent to the call:<BR>
@verbatim
        mbrtowc(NULL, "", 1, ps)
@endverbatim

In this case, the values of the parameters pwc and n are ignored.

If S is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
the byte pointed to by S to determine the number of bytes needed to complete the next
multibyte character (including any shift sequences). If the function determines that the
next multibyte character is complete and valid, it determines the value of the
corresponding wide character and then, if pwc is not a null pointer, stores that value in
the object pointed to by pwc. If the corresponding wide character is the null wide
character, the resulting state described is the initial conversion state.

    @retval   0             if the next n or fewer bytes complete the multibyte
                            character that corresponds to the null wide
                            character (which is the value stored).
    @retval   between_1_and_n_inclusive   if the next n or fewer bytes complete
                            a valid multibyte character (which is the value
                            stored); the value returned is the number of bytes
                            that complete the multibyte character.
    @retval   (size_t)(-2)  if the next n bytes contribute to an incomplete
                            (but potentially valid) multibyte character, and
                            all n bytes have been processed (no value is stored).
    @retval   (size_t)(-1)  if an encoding error occurs, in which case the next
                            n or fewer bytes do not contribute to a complete and
                            valid multibyte character (no value is stored); the
                            value of the macro EILSEQ is stored in errno, and
                            the conversion state is unspecified.
**/
size_t mbrtowc(wchar_t * __restrict pwc, const char * __restrict S, size_t n, mbstate_t * __restrict ps);

/**
If S is a null pointer, the wcrtomb function is equivalent to the call:<BR>
@verbatim
        wcrtomb(buf, L'\0', ps)
@endverbatim
where buf is an internal buffer.

If S is not a null pointer, the wcrtomb function determines the number of bytes needed
to represent the multibyte character that corresponds to the wide character given by wc
(including any shift sequences), and stores the multibyte character representation in the
array whose first element is pointed to by S. At most MB_CUR_MAX bytes are stored. If
wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
to restore the initial shift state; the resulting state described is the initial conversion state.

    @return   The wcrtomb function returns the number of bytes stored in the
              array object (including any shift sequences). When wc is not a
              valid wide character, an encoding error occurs: the function
              stores the value of the macro EILSEQ in errno and
              returns (size_t)(-1); the conversion state is unspecified.
**/
size_t wcrtomb(char * __restrict S, wchar_t wc, mbstate_t * __restrict ps);

/** Convert a sequence of multibyte characters into a sequence of wide characters.
    The mbsrtowcs function converts a sequence of multibyte characters that begins in the
    conversion state described by the object pointed to by ps, from the array indirectly
    pointed to by src into a sequence of corresponding wide characters. If dst is not a null
    pointer, the converted characters are stored into the array pointed to by dst. Conversion
    continues up to and including a terminating null character, which is also stored.
    Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
    not form a valid multibyte character, or (if dst is not a null pointer) when len wide
    characters have been stored into the array pointed to by dst. Each conversion takes
    place as if by a call to the mbrtowc function.

    If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
    pointer (if conversion stopped due to reaching a terminating null character) or the address
    just past the last multibyte character converted (if any). If conversion stopped due to
    reaching a terminating null character and if dst is not a null pointer, the resulting state
    described is the initial conversion state.

    @param[in]    dst   Destination for the Wide character sequence.
    @param[in]    src   Pointer to Pointer to MBCS char. sequence to convert.
    @param[in]    len   Length of dest, in WIDE characters.
    @param[in]    ps    Pointer to the conversion state object to be used for this conversion.

    @return   If the input conversion encounters a sequence of bytes that do
              not form a valid multibyte character, an encoding error occurs:
              the mbsrtowcs function stores the value of the macro EILSEQ in
              errno and returns (size_t)(-1); the conversion state is
              unspecified. Otherwise, it returns the number of multibyte
              characters successfully converted, not including the terminating
              null character (if any).
**/
size_t mbsrtowcs(wchar_t * __restrict dst, const char ** __restrict src, size_t len, mbstate_t * __restrict ps);

/** The wcsrtombs function converts a sequence of wide characters from the array
    indirectly pointed to by src into a sequence of corresponding multibyte
    characters that begins in the conversion state described by the object
    pointed to by ps. If dst is not a null pointer, the converted characters
    are then stored into the array pointed to by dst.  Conversion continues
    up to and including a terminating null wide character, which is also
    stored. Conversion stops earlier in two cases: when a wide character is
    reached that does not correspond to a valid multibyte character, or
    (if dst is not a null pointer) when the next multibyte character would
    exceed the limit of len total bytes to be stored into the array pointed
    to by dst. Each conversion takes place as if by a call to the wcrtomb
    function.)

    If dst is not a null pointer, the pointer object pointed to by src is
    assigned either a null pointer (if conversion stopped due to reaching
    a terminating null wide character) or the address just past the last wide
    character converted (if any). If conversion stopped due to reaching a
    terminating null wide character, the resulting state described is the
    initial conversion state.

    @param[in]    dst   Destination for the MBCS sequence.
    @param[in]    src   Pointer to Pointer to wide char. sequence to convert.
    @param[in]    len   Length of dest, in bytes.
    @param[in]    ps    Pointer to the conversion state object to be used for this conversion.

    @return     If conversion stops because a wide character is reached that
                does not correspond to a valid multibyte character, an
                encoding error occurs: the wcsrtombs function stores the
                value of the macro EILSEQ in errno and returns (size_t)(-1);
                the conversion state is unspecified. Otherwise, it returns
                the number of bytes in the resulting multibyte character
                sequence, not including the terminating null character (if any).
**/
size_t wcsrtombs(char * __restrict dst, const wchar_t ** __restrict src, size_t len, mbstate_t * __restrict ps);

#endif  /* _WCHAR_H */