1 /** @file  ../include/wchar.h

     2 @internalComponent

     3 */

     4 

     5 /** @fn  btowc(int c)

     6 @param c

     7 

     8 Note: This description also covers the following functions -

     9  wctob() 

    10 

    11 @return   The btowc function returns the wide character converted from the single 

    12   byte c . If c is EOF or not a valid multibyte sequence of length 1 the function 

    13   returns WEOF.

    14 

    15   The btowc function converts a single-byte character into a corresponding 

    16 wide character. If the character is EOF , or not valid in the initial shift state, btowc returns WEOF.

    17 

    18  The wctob function converts a wide character into a corresponding single-byte 

    19   character. If the wide character is WEOF , or not able to be represented as a single byte in the initial 

    20   shift state, wctob returns WEOF.

    21 

    22  

    23 

    24 Examples:

    25 @code

    26 #include <wchar.h>

    27 // Illustrates how to use btowc API

    28 wint_t example_btowc(int c)

    29 {

    30  wint_t wc = L'a';

    31  //  converting single byte to wide-character 

    32  wc = btowc(c);

    33  // return the character that was converted 

    34 return (wc);

    35 }

    36 

    37 @endcode

    38 @code

    39 #include <wchar.h>

    40 /* Illustrates how to use wctob API */

    41 int example_wctob(void)

    42 {

    43  wint_t wc = L'a';

    44  int c;

    45   

    46  /* represent a wide-char in a single byte*/

    47  c = wctob(wc);

    48  /* return the single byte */

    49  return(c);

    50 }

    51 

    52 @endcode

    53 

    54 Limitations:

    55 

    56 The current implementation of btowc and wctob is not affected by the LC_CTYPE category of the current locale.

    57 It works only for UTF8 character set.

    58 

    59 @see mbrtowc()

    60 @see wcrtomb()

    61 

    62 

    63  

    64 

    65 @publishedAll

    66 @externallyDefinedApi

    67 */

    68 

    69 /** @fn  fgetwc(FILE *stream)

    70 @param stream

    71 

    72 Note: This description also covers the following functions -

    73  getwc()  getwchar() 

    74 

    75 @return   If successful these routines return the next wide character from the stream. If the stream is at end-of-file or a read error occurs the routines 

    76 return WEOF. The routines feof and ferror must be used to distinguish between end-of-file 

    77 and error. If an error occurs the global variable errno is set to indicate the error. The end-of-file condition is remembered, 

    78 even on a terminal, and all subsequent attempts to read will return WEOF until the condition is cleared with clearerr .

    79 

    80   The fgetwc function

    81 obtains the next input wide character (if present) from the stream pointed at by stream, or the next character pushed back on the stream via ungetwc .

    82 

    83  The getwc function

    84 acts essentially identical to fgetwc.

    85 

    86  The getwchar function

    87 is equivalent to getwc with the argument stdin.

    88 

    89 Examples:

    90 @code

    91 /* Illustrates how to use fgetwc API */

    92 #include <stdio.h>

    93 #include <wchar.h>

    94 wint_t example_fgetwc(void)

    95 {

    96  FILE *fp = NULL;

    97  wint_t retval;

    98  

    99  /* opening the input file */

   100  fp = fopen("input.txt","r");

   101  if(fp == NULL)

   102  {

   103   wprintf(L"Error: File open

   104 ");

   105   return (-1);

   106  }

   107  /* Read a character from the opened file */

   108  retval = fgetwc(fp);

   109  /* Close the file open for reading */

   110  fclose(fp);

   111  /* return the character read from the file */

   112  return (retval);

   113 }

   114 

   115 @endcode

   116 @code

   117 /* Illustrates how to use getwc API */

   118 #include <stdio.h>

   119 #include <wchar.h>

   120 wint_t example_getwc(void)

   121 {

   122  FILE *fp =  NULL;

   123  wint_t retval;

   124  

   125  /* opening the input file */

   126  fp = fopen("input.txt","r");

   127  if(fp == NULL)

   128  {

   129   wprintf(L"Error: File open

   130 ");

   131   return (-1);

   132  }

   133  /* Read a character from the opened file */

   134  retval = getwc(fp);

   135  /* Close the file open for reading */

   136  fclose(fp);

   137  /* return the character read from the file */

   138  return (retval);

   139 }

   140 

   141 @endcode

   142 @code

   143 /* Illustrates how to use getwchar API */

   144 #include <stdio.h>

   145 #include <wchar.h>

   146 wint_t example_getwchar(void)

   147 {

   148  wint_t retval;

   149  

   150  /* Read a character from standard input */

   151  retval = getwchar();

   152  /* return the character read */

   153  return (retval);

   154 }

   155 

   156 @endcode

   157 @see ferror()

   158 @see fopen()

   159 @see fread()

   160 @see getc()

   161 @see putwc()

   162 @see ungetwc()

   163 

   164 

   165  

   166 

   167 @publishedAll

   168 @externallyDefinedApi

   169 */

   170 

   171 

   172 /** @fn  fgetws(wchar_t *  ws, int n, FILE *  fp)

   173 @param ws

   174 @param n

   175 @param fp

   176 @return   Upon successful completion fgetws returns ws. If end-of-file occurs before any characters are read, fgetws returns NULL and the buffer contents remain unchanged. If an error occurs fgetws returns NULL and the buffer contents are indeterminate. The fgetws function does not distinguish between end-of-file and error, 

   177 and callers must use feof and ferror to determine which occurred.

   178 

   179   The fgetws function reads at most one less than the number of characters 

   180 specified by n from the given fp and stores them in the wide character string ws. Reading stops when a newline character is found, at end-of-file or 

   181 error. The newline, if any, is retained. If any characters are read, and there 

   182 is no error, a '\\0' character is appended to end the string.

   183 

   184 Examples:

   185 @code

   186 #include <stdio.h>

   187 #include <wchar.h>

   188 /* Illustrates how to use fgetws API */

   189 wchar_t *example_fgetws(wchar_t *buf)

   190 {

   191  FILE *fp = NULL;

   192  wint_t retval;

   193  int n;

   194  /* for example, 10 characters to be read */

   195  n = 10;

   196  /* opening the input file */

   197  fp = fopen("input.txt","r");

   198  if(fp == NULL)

   199  {

   200   wprintf(L"Error: File open

   201 ");

   202   return (-1);

   203  }

   204  /* Read characters from the opened file */

   205  retval = fgetws(buf, n, fp);

   206  /* Close the file open for reading */

   207  fclose(fp);

   208  /* return the character read from the file */

   209  return (buf);

   210 }

   211 

   212 @endcode

   213 @see feof()

   214 @see ferror()

   215 @see fgets()

   216 

   217 

   218  

   219 

   220 @publishedAll

   221 @externallyDefinedApi

   222 */

   223 

   224 /** @fn  fputwc(wchar_t wc, FILE *stream)

   225 @param wc

   226 @param stream

   227 

   228 Note: This description also covers the following functions -

   229  putwc()  putwchar() 

   230 

   231 @return   The fputwc, putwc, and putwchar functions

   232 return the wide character written.

   233 If an error occurs, the value WEOF is returned.

   234 

   235   The fputwc function

   236 writes the wide character wc to the output stream pointed to by stream.

   237 

   238  The putwc function

   239 acts essentially identically to fputwc.

   240 

   241  The putwchar function

   242 is identical to putwc with an output stream of stdout.

   243 

   244 Examples:

   245 @code

   246 /* Illustrates how to use putwc API */

   247 #include <stdio.h>

   248 #include <wchar.h>

   249 wint_t example_putwc(void)

   250 {

   251  FILE *fp = NULL;

   252  wchar_t wc = L'a';

   253  wint_t rval;

   254  /* opening the file to write*/

   255  fp = fopen("input.txt","w");

   256  if(fp == NULL)

   257  {

   258   wprintf(L"Error: File open

   259 ");

   260   return (-1);

   261  }

   262 /* write a character into fp */

   263  rval = putwc(wc, fp);

   264  /* Close the file opened for writing */

   265  fclose(fp);

   266  /* return the value that was written */

   267  return (rval);

   268 }

   269 

   270 @endcode

   271 @code

   272 /* Illustrates how to use fputwc API */

   273 #include <stdio.h>

   274 #include <wchar.h>

   275 wint_t example_fputwc(void)

   276 {

   277  FILE *fp = NULL;

   278  wchar_t wc = L'a';

   279  wint_t rval;

   280  /* opening the file to write*/

   281  fp = fopen("input.txt","w");

   282  if(fp == NULL)

   283  {

   284   wprintf(L"Error: File open

   285 ");

   286   return (-1);

   287  }

   288 /* write a character into fp */

   289  rval = fputwc(wc, fp);

   290  /* Close the file opened for writing */

   291  fclose(fp);

   292  /* return the value that was written */

   293  return (rval);

   294 }

   295 

   296 @endcode

   297 @code

   298 /* Illustrates how to use putwchar API */

   299 #include <stdio.h>

   300 #include <wchar.h>

   301 wint_t example_putwchar(void)

   302 {

   303  wint_t rval;

   304  wchar_t wc = L'q';

   305  

   306  /* write a character onto the standard output */

   307  rval = putwchar(wc);

   308  /* return the character that was written */

   309  return (rval);

   310 }

   311 

   312 @endcode

   313  Output of putwchar

   314 @code

   315 q

   316 

   317 @endcode

   318 @see ferror()

   319 @see fopen()

   320 @see getwc()

   321 @see putc()

   322 

   323 

   324  

   325 

   326 @publishedAll

   327 @externallyDefinedApi

   328 */

   329 

   330 

   331 /** @fn  fputws(const wchar_t *  ws, FILE *  fp)

   332 @param ws

   333 @param fp

   334 @return   The fputws function

   335 returns 0 on success and -1 on error.

   336 

   337   The fputws function writes the wide character string pointed to by ws to the stream pointed to by fp.

   338 

   339 Examples:

   340 @code

   341 #include <stdio.h>

   342 #include <wchar.h>

   343 /* Illustrates how to use fputws API */

   344 int example_fputws(wchar_t *buf)

   345 {

   346  FILE *fp = NULL;

   347  int retval;

   348  /* open the file for writing*/

   349  fp = fopen("write.txt","r");

   350  if(fp == NULL)

   351  {

   352   wprintf(L"Error: File open

   353 ");

   354   return (-1);

   355  }

   356  /* Write the characters into the file */

   357  retval = fputws(buf, fp);

   358  /* Close the file open for writing */

   359  fclose(fp);

   360  /* return the number of characters written */

   361  /* into the file */

   362  return (retval);

   363 }

   364 

   365 @endcode

   366 @see ferror()

   367 @see fputs()

   368 @see putwc()

   369 

   370 

   371  

   372 

   373 @publishedAll

   374 @externallyDefinedApi

   375 */

   376 

   377 

   378 /** @fn  fwide(FILE *stream, int mode)

   379 @param stream

   380 @param mode

   381 @return   The fwide function

   382 returns a value according to orientation after the call of fwide; a value less than zero if byte-oriented, a value greater than zero

   383 if wide-oriented, and zero if the stream has no orientation.

   384 

   385   The fwide function

   386 determines the orientation of the stream pointed at by stream.

   387 

   388  If the orientation of stream has already been determined fwide leaves it unchanged. Otherwise fwide sets the orientation of stream according to mode.

   389 

   390  If mode is less than zero stream is set to byte-oriented. If it is greater than zero stream is set to wide-oriented. Otherwise mode is zero and stream is unchanged.

   391 

   392 Examples:

   393 @code

   394 #include <stdio.h>

   395 #include <wchar.h>

   396 /* Illustrates how to use fwide API */

   397 int example_fwide(void)

   398 {

   399  FILE *fp = NULL;

   400  int retval;

   401  int mode;

   402  /* open a file */

   403  fp = fopen("input.txt","r");

   404  if(fp == NULL)

   405  {

   406   wprintf(L"Error: File open

   407 ");

   408   return (-1);

   409  }

   410  /* set the mode to wide*/

   411  mode = 1;

   412  /* set the orientation of the file */

   413  retval = fwide(fp, mode);

   414  /*     check   the     return value */

   415  if(retval ==   1)

   416  {

   417         wprintf(L"Mode set to WIDE

   418 ");

   419  }

   420  else

   421  {

   422         wprintf(L"Error setting the mode to wide!!

   423 ");

   424  }

   425  /* set the mode to determine the orientation */

   426  mode = 0;

   427  /* Read back the orientation that was set */

   428  retval = fwide(fp ,mode);

   429  if(retval == 1)

   430  {

   431         wprintf("Mode not changed

   432 ");

   433  }

   434  else

   435  {

   436         wprintf("Error, mode changed!!

   437 ");

   438  }

   439  /* Close the file open for writing */

   440  fclose(fp);

   441  /* return the mode of fp */

   442  return (retval);

   443 }

   444 

   445 @endcode

   446 @see ferror()

   447 @see fgetc()

   448 @see fgetwc()

   449 @see fopen()

   450 @see fputc()

   451 @see fputwc()

   452 @see freopen()

   453 

   454 

   455  

   456 

   457 @publishedAll

   458 @externallyDefinedApi

   459 */

   460 

   461 

   462 /** @fn  fwprintf(FILE *  stream, const wchar_t *  format, ...)

   463 @param stream

   464 @param format

   465 @param ...

   466 

   467 Note: This description also covers the following functions -

   468  swprintf()  snwprintf()  vsnwprintf()  wprintf()  vfwprintf()  vswprintf()  vwprintf() 

   469 

   470 @return   The functions return the number of wide characters written, excluding the terminating null wide character in case of the functions swprintf , snwprintf , vswprintf and vsnwprintf . They return -1 when an error occurs.

   471 

   472 The wprintf family of functions produces output according to a format as described below. The wprintf and vwprintf functions write output to stdout, the standard output stream; fwprintf and vfwprintf write output to the given output stream; swprintf , snwprintf , vswprintf and vsnwprintf write to the wide character string ws. 

   473 These functions write the output under the control of a format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg) are converted for output. 

   474 

   475 These functions return the number of characters printed (not including the trailing ‘\\0’ used to end output to strings). 

   476 

   477 The swprintf , snwprintf , vswprintf and vsnwprintf functions will fail if n or more wide characters were requested to be written. 

   478 

   479 @code

   480 

   481 Note : 

   482 

   483 1. swprintf and snwprintf can be used interchangeably. 

   484 

   485 2. vswprintf and vsnwprintf can be used interchangeably. 

   486 

   487 

   488 The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the % character. The arguments must correspond properly (after type promotion) with the conversion specifier. After the %, the following appear in sequence: 

   489 @endcode

   490 

   491 @code

   492 An optional field, consisting of a decimal digit string followed by a $, specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. Arguments are numbered starting at 1. If unaccessed arguments in the format string are interspersed with ones that are accessed the results will be indeterminate. 

   493 Zero or more of the following flags:

   494 

   495  '#'  The value should be converted to an "alternate form". For c, d, i, n, p, s, and u conversions, this option has no effect. For o conversions, the precision of the number is increased to force the first character of the output string to a zero (except if a zero value is printed with an explicit precision of zero). For x and X conversions, a non-zero result has the string ‘0x’ (or ‘0X’ for X conversions) prepended to it. For a, A, e, E, f, F, g, and G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be.  

   496 

   497 '0(zero)'  Zero padding. For all conversions except n, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion ( d, i, o, u, i, x, and X), the 0 flag is ignored.  

   498 

   499 '-'  A negative field width flag; the converted value is to be left adjusted on the field boundary. Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.  

   500 

   501 ' (space)'  A blank should be left before a positive number produced by a signed conversion ( a, A, d, e, E, f, F, g, G, or i).  

   502 

   503 '+'  A sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used.  

   504 

   505 '’'  Decimal conversions ( d, u, or i) or the integral portion of a floating point conversion ( f or F) should be grouped and separated by thousands using the non-monetary separator returned by localeconv.  

   506 

   507 

   508 An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width. 

   509 

   510 An optional precision, in the form of a period . followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s conversions. 

   511 

   512 An optional length modifier, that specifies the size of the argument. The following length modifiers are valid for the d, i, n, o, u, x, or X conversion:

   513 

   514 @endcode

   515 

   516 @code

   517 

   518  Modifier            d, i      o, u, x, X        n 

   519 

   520  hh signed char unsigned char signed char *

   521  h short unsigned short short *

   522  l (ell) long unsigned long long *

   523  ll (ell ell) long long unsigned long long long long *

   524  j intmax_t uintmax_t intmax_t *

   525  t ptrdiff_t (see note) ptrdiff_t *

   526  z (see note) size_t (see note)

   527  q (deprecated) quad_t u_quad_t quad_t *

   528 

   529 @endcode

   530 

   531 @code

   532 

   533 Note: the t modifier, when applied to a o, u, x, or X conversion, indicates that the argument is of an unsigned type equivalent in size to a ptrdiff_t . The z modifier, when applied to a d or i conversion, indicates that the argument is of a signed type equivalent in size to a size_t . Similarly, when applied to an n conversion, it indicates that the argument is a pointer to a signed type equivalent in size to a size_t . 

   534 

   535 The following length modifier is valid for the a, A, e, E, f, F, g, or G conversion:

   536 

   537 @endcode

   538 

   539 @code

   540 

   541  Modifier a, A, e, E, f, F, g, G

   542  L long double

   543 

   544 @endcode

   545 

   546 @code   

   547 

   548 The following length modifier is valid for the c or s conversion:

   549 

   550 Modifier c s

   551  l (ell) wint_t  wchar_t * 

   552 

   553 @endcode

   554 

   555 @code

   556 

   557 A character that specifies the type of conversion to be applied. 

   558 

   559 A field width or precision, or both, may be indicated by an asterisk ‘*’ or an asterisk followed by one or more decimal digits and a ‘$’ instead of a digit string. In this case, an int argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. If a single format directive mixes positional (nn$) and non-positional arguments, the results are undefined. 

   560 

   561 The conversion specifiers and their meanings are: 

   562 

   563 

   564 diouxX  

   565   The int (or appropriate variant) argument is converted to signed decimal ( d and i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal ( x and X) notation. The letters "abcdef" are used for x conversions; the letters "ABCDEF" are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros.  

   566 

   567 DOU  

   568   The long int argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been ld, lo, or lu respectively. These conversion characters are deprecated, and will eventually disappear.  

   569 

   570 eE  

   571   The double argument is rounded and converted in the style [-d . ddd e \*[Pm] dd] where there is one digit before the decimal-point 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, no decimal-point character appears. An E conversion uses the letter ‘E’ (rather than ‘e’) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00. 

   572 For a, A, e, E, f, F, g, and G conversions, positive and negative infinity are represented as inf and -inf respectively when using the lowercase conversion character, and INF and -INF respectively when using the uppercase conversion character. Similarly, NaN is represented as nan when using the lowercase conversion, and NAN when using the uppercase conversion. 

   573  

   574 fF  

   575   The double argument is rounded and converted to decimal notation in the style [-ddd . ddd], where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.  

   576 

   577 gG  The double argument is converted in style f or e (or F or E for G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.  

   578 

   579 aA  The double argument is converted to hexadecimal notation in the style [-0x h . hhhp[\*[Pm]d]], where the number of digits after the hexadecimal-point character is equal to the precision specification. If the precision is missing, it is taken as enough to exactly represent the floating-point number; if the precision is explicitly zero, no hexadecimal-point character appears. This is an exact conversion of the mantissa+exponent internal floating point representation; the [-0x h . hhh] portion represents exactly the mantissa; only denormalized mantissas have a zero value to the left of the hexadecimal point. The p is a literal character ‘p’; the exponent is preceded by a positive or negative sign and is represented in decimal, using only enough characters to represent the exponent. The A conversion uses the prefix "0X" (rather than "0x"), the letters "ABCDEF" (rather than "abcdef") to represent the hex digits, and the letter ‘P’ (rather than ‘p’) to separate the mantissa and exponent.  

   580 

   581 C  Treated as c with the l (ell) modifier.  

   582 

   583 c  The int argument is converted to an unsigned char , then to a wchar_t as if by btowc, and the resulting character is written. 

   584 

   585 If the l (ell) modifier is used, the wint_t argument is converted to a wchar_t and written. 

   586  

   587 S  Treated as s with the l (ell) modifier.  

   588 

   589 s  The char * argument is expected to be a pointer to an array of character type (pointer to a string) containing a multibyte sequence. Characters from the array are converted to wide characters and written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating NUL character. 

   590 

   591 If the l (ell) modifier is used, the wchar_t * argument is expected to be a pointer to an array of wide characters (pointer to a wide string). Each wide character in the string is written. Wide characters from the array are written up to (but not including) a terminating wide NUL character; if a precision is specified, no more than the number specified are written (including shift sequences). If a precision is given, no null character need be present; if the precision is not specified, or is greater than the number of characters in the string, the array must contain a terminating wide NUL character. 

   592  

   593 p  The void * pointer argument is printed in hexadecimal (as if by ‘%#x’ or ‘%#lx’).  

   594 

   595 n  The number of characters written so far is stored into the integer indicated by the int * (or variant) pointer argument. No argument is converted. 

   596  

   597 %  A ‘%’ is written. No argument is converted. The complete conversion specification is ‘%%’.  

   598 

   599 @endcode

   600 

   601 The decimal point character is defined in the program’s locale (category LC_NUMERIC). 

   602 

   603 In no case does a non-existent or small field width cause truncation of a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. 

   604 

   605 

   606 Examples:

   607 @code

   608 #include <stdio.h>

   609 #include <wchar.h>

   610 /* Illustrates how to use wprintf API */

   611 int example_wprintf(void)

   612 {

   613  int input = 12345;

   614  int rval;

   615  /* prints the integers on the standard output */

   616  rval = wprintf(L"%d", input);

   617  /* return the number of wide characters that were written */

   618  return(rval);

   619 }

   620 

   621 @endcode

   622  Output

   623 @code

   624 12345

   625 

   626 @endcode

   627 @code

   628 #include <stdio.h>

   629 #include <wchar.h>

   630 /* Illustrates how to use fwprintf API */

   631 int example_fwprintf(void)

   632 {

   633  FILE *fp = NULL;

   634  int retval;

   635  wchar_t *wcs = L"abc";

   636  /* open the file for writing*/

   637  fp = fopen("write.txt","w");

   638  if(fp == NULL)

   639  {

   640   wprintf(L"Error: File open

   641 ");

   642   return (-1);

   643  }

   644  /* print the characters into the file */

   645  retval = fwprintf(fp, L"%s", wcs);

   646  /* Close the file opened for writing */

   647  fclose(fp);

   648  /* return the number of wide characters that were written */

   649  return (retval);

   650 }

   651 

   652 @endcode

   653 @code

   654 #include <stdio.h>

   655 #include <wchar.h>

   656 /* Illustrates how to use swprintf API */

   657 int example_swprintf(wchar_t *buf, int maxlen)

   658 {

   659  wchar_t *wcs = L"abcdef";

   660  int rval;

   661  /* prints the wide char string into the buffer buf */

   662  rval = swprintf(buf, maxlen, L"%s", wcs);

   663  /* return the number of wide characters that were written */

   664  return(rval);

   665 }

   666 

   667 @endcode

   668 @code

   669 #include <stdio.h>

   670 #include <wchar.h>

   671 /* Illustrates how to use vwprintf API */

   672 int example_vwprintf(va_list input)

   673 {

   674  int rval;

   675  /* prints the integers on the standard output */

   676  rval = vwprintf(L"%d", input);

   677  /* return the number of wide characters that were written */

   678  return(rval);

   679 }

   680 

   681 @endcode

   682 @code

   683 #include <stdio.h>

   684 #include <wchar.h>

   685 /* Illustrates how to use vfwprintf API */

   686 int example_vfwprintf(va_list input)

   687 {

   688   FILE *fp = NULL;

   689   int retval;

   690  

   691   /* open the file for writing*/

   692   fp = fopen("write.txt","w");

   693   if(fp == NULL)

   694   {

   695     wprintf(L"Error: File open

   696 ");

   697     return (-1);

   698   }

   699   /* print the characters into the file */

   700   retval = vfwprintf(fp, L"%s", input);

   701   /* Close the file opened for writing */

   702   fclose(fp);

   703   /* return the number of wide characters that were written */

   704   return (retval);

   705 }

   706 

   707 @endcode

   708 @code

   709 #include <stdio.h>

   710 #include <wchar.h>

   711 /* Illustrates how to use vswprintf API */

   712 int example_vswprintf(wchar_t *buf, int maxlen, va_list input)

   713 {

   714  int rval;

   715  /* prints the wide char string into the buffer buf */

   716  rval = vswprintf(buf, maxlen, L"%s", input);

   717  /* return the number of wide characters that were written */

   718  return(rval);

   719 }

   720 

   721 @endcode

   722 

   723 Security considerations:

   724 

   725 Refer to printf() .

   726  

   727 Limitations:

   728 

   729 Long double length modifiers are not supported. The maximum floating point 

   730 precision is 15 digits.

   731 

   732 @see btowc()

   733 @see fputws()

   734 @see printf()

   735 @see putwc()

   736 @see setlocale()

   737 @see wcsrtombs()

   738 @see wscanf()

   739 

   740 

   741  

   742 

   743 @publishedAll

   744 @externallyDefinedApi

   745 */

   746 

   747 /** @fn  fwscanf(FILE *  stream, const wchar_t *  format, ...)

   748 @param stream

   749 @param format

   750 @param ...

   751 

   752 Refer to wscanf() for the documentation

   753 

   754 @see fgetwc()

   755 @see scanf()

   756 @see wcrtomb()

   757 @see wcstod()

   758 @see wcstol()

   759 @see wcstoul()

   760 @see wprintf()

   761 

   762 

   763  

   764 

   765 @publishedAll

   766 @externallyDefinedApi

   767 */

   768 

   769 /** @fn  getwc(FILE *stream)

   770 @param stream

   771 

   772 Refer to  fgetwc() for the documentation

   773 

   774 @see ferror()

   775 @see fopen()

   776 @see fread()

   777 @see getc()

   778 @see putwc()

   779 @see ungetwc()

   780 

   781 

   782  

   783 

   784 @publishedAll

   785 @externallyDefinedApi

   786 */

   787 

   788 

   789 /** @fn  getwchar(void)

   790 

   791 Refer to fgetwc() for the documentation

   792 

   793 @see ferror()

   794 @see fopen()

   795 @see fread()

   796 @see getc()

   797 @see putwc()

   798 @see ungetwc()

   799 

   800 

   801  

   802 

   803 @publishedAll

   804 @externallyDefinedApi

   805 */

   806 

   807 /** @fn  mbrlen(const char *  s, size_t n, mbstate_t *  ps)

   808 @param s

   809 @param n

   810 @param ps

   811 

   812 @return   The mbrlen functions returns: 0 The next n or fewer bytes

   813 represent the null wide character (L'\\0') \>0 The next n or fewer bytes

   814 represent a valid character, mbrlen returns the number of bytes used to complete the multibyte character. ( size_t-2)   The next n contribute to, but do not complete, a valid multibyte character sequence,

   815 and all n bytes have been processed. ( size_t-1)   An encoding error has occurred.

   816 The next n or fewer bytes do not contribute to a valid multibyte character.

   817 

   818   The mbrlen function inspects at most n bytes pointed to by s to determine the number of bytes needed to complete the next

   819 multibyte character.

   820 

   821  The mbstate_t

   822 argument, ps, is used to keep track of the shift state.

   823 If it is NULL, mbrlen uses an internal, static mbstate_t

   824 object, which is initialized to the initial conversion state

   825 at program startup.

   826 

   827  It is equivalent to:

   828 

   829 @code

   830 

   831 mbrtowc(NULL, s, n, ps); 

   832 

   833 @endcode

   834 

   835 Except that when ps is a NULL pointer, mbrlen uses its own static, internal mbstate_t

   836 object to keep track of the shift state. The behavior of the mbrlen is affected by LC_CTYPE category of the current locale.

   837 

   838 Examples:

   839  A function that calculates the number of characters in a multibyte

   840 character string:

   841 @code

   842 size_t

   843 nchars(const char *s)

   844 {

   845         size_t charlen, chars;

   846         mbstate_t mbs;

   847         chars = 0;

   848         memset(&mbs;, 0, sizeof(mbs));

   849         while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs;)) != 0 &&

   850             charlen != (size_t)-1 && charlen != (size_t)-2) {

   851                 s += charlen;

   852                 chars++;

   853         }

   854         return (chars);

   855 }

   856 

   857 @endcode

   858 

   859 Errors:

   860 

   861 The mbrlen function will fail if: 

   862 [EILSEQ] An invalid multibyte sequence was detected.  

   863 [EINVAL] The conversion state is invalid.

   864 

   865 Limitations:

   866 

   867 The current implementation of mbrlen is not affected by the LC_CTYPE category of the current locale.

   868 It works only for UTF8 character set.

   869 

   870 @see mblen()

   871 @see mbrtowc()

   872 

   873 

   874  

   875 

   876 @publishedAll

   877 @externallyDefinedApi

   878 */

   879 

   880 /** @fn  mbrtowc(wchar_t *  pwc, const char *  s, size_t n, mbstate_t *  ps)

   881 @param pwc

   882 @param s

   883 @param n

   884 @param ps

   885 

   886 @return   The mbrtowc functions returns: 0 The next n or fewer bytes

   887 represent the null wide character (L'\\0') \>0 The next n or fewer bytes

   888 represent a valid character, mbrtowc returns the number of bytes used to complete the multibyte character. ( size_t-2)   The next n contribute to, but do not complete, a valid multibyte character sequence,

   889 and all n bytes have been processed. ( size_t-1)   An encoding error has occurred.

   890 The next n or fewer bytes do not contribute to a valid multibyte character.

   891 

   892 

   893   The mbrtowc function inspects at most n bytes pointed to by s to determine the number of bytes needed to complete the next multibyte

   894 character.

   895 If a character can be completed, and pwc is not NULL, the wide character which is represented by s is stored in the wchar_t

   896 it points to.

   897 

   898  If s is NULL, mbrtowc behaves as if pwc was NULL, s was an empty string ("")

   899 and n was 1.

   900 

   901  The mbstate_t

   902 argument, ps, is used to keep track of the shift state.

   903 If it is NULL, mbrtowc uses an internal, static mbstate_t

   904 object, which is initialized to the initial conversion state

   905 at program startup.

   906 

   907  The behavior of the mbrtowc is affected by LC_CTYPE category of the current locale.

   908 

   909 Examples:

   910 @code

   911 #include <stdio.h>

   912 #include <stdlib.h>

   913 #include <wchar.h>

   914 /* Illustrates how to use mbrtowc API */

   915 size_t example_mbrtowc()

   916 {

   917  size_t len;

   918  wchar_t wc[100];

   919  char *s = 'a';

   920  size_t n = 1;

   921  mbstate_t ps;

   922  /* converting multibyte sequence to a wide-char sequence */

   923  len = mbrtowc(wc,(const char *) s, n, &ps;);

   924  /* checking for error value */

   925  if(len < 0)

   926  {

   927         wprintf(L"mbrtowc returned error!!

   928 ");

   929  }

   930  /* returning no of bytes consumed */

   931  return (len);

   932 }

   933 

   934 @endcode

   935 

   936 Errors:

   937 

   938 The mbrtowc function will fail if: 

   939 [EILSEQ] An invalid multibyte sequence was detected.  

   940 [EINVAL]The conversion state is invalid. 

   941 

   942  

   943 Limitations:

   944 

   945 The current implementation of mbrtowc is not affected by the LC_CTYPE category of the current locale.

   946 It works only for UTF8 character set.

   947 

   948 @see mbtowc()

   949 @see setlocale()

   950 @see wcrtomb()

   951 

   952 

   953  

   954 

   955 @publishedAll

   956 @externallyDefinedApi

   957 */

   958 

   959 /** @fn  mbsinit(const mbstate_t *ps)

   960 @param ps

   961 

   962 @return   The mbsinit function returns non-zero if ps is NULL or describes an initial conversion state,

   963 otherwise it returns zero.

   964 

   965   The mbsinit function determines whether the mbstate_t

   966 object pointed to by ps describes an initial conversion state.

   967 

   968  The behavior of the mbsinit is affected by LC_CTYPE category of the current locale.

   969 

   970 Examples:

   971 @code

   972 #include <stdlib.h>

   973 #include <wchar.h>

   974 /* Illustrates how to use mbsinit API */

   975 int example_mbsinit(void)

   976 {

   977  mbstate_t mbs;

   978  int state;

   979  

   980  /* testing for the initial state */

   981  state = mbsinit(&mbs;);

   982  /* return the state */

   983  return(state);

   984 }

   985 

   986 @endcode

   987 

   988 Limitations:

   989 

   990 The current implementation of mbsinit is not affected by the LC_CTYPE category of the current locale.

   991 It works only for UTF8 character set.

   992 

   993 @see mbrlen()

   994 @see mbrtowc()

   995 @see mbsrtowcs()

   996 @see wcrtomb()

   997 @see wcsrtombs()

   998 

   999 

  1000  

  1001 

  1002 @publishedAll

  1003 @externallyDefinedApi

  1004 */

  1005 

  1006 /** @fn  mbsrtowcs(wchar_t *  dst, const char **  src, size_t len, mbstate_t *  ps)

  1007 @param dst

  1008 @param src

  1009 @param len

  1010 @param ps

  1011 

  1012 Note: This description also covers the following functions -

  1013  mbsnrtowcs() 

  1014 

  1015 @return   The mbsrtowcs and mbsnrtowcs functions return the number of wide characters stored in 

  1016 the array pointed to by dst if successful, otherwise it returns ( size_t)(-1).

  1017 

  1018   The mbsrtowcs function converts a sequence of multibyte characters pointed to indirectly by src into a sequence of corresponding wide characters and stores at most len of them in the wchar_t

  1019 array pointed to by dst, until it encounters a terminating null character ('\\0'.)

  1020 

  1021  If dst is NULL no characters are stored.

  1022 

  1023  If dst is not NULL, the pointer pointed to by src is updated to point to the character after the one that conversion stopped at.

  1024 If conversion stops because a null character is encountered, *src is set to NULL.

  1025 

  1026  The mbstate_t

  1027 argument, ps, is used to keep track of the shift state.

  1028 If it is NULL, mbsrtowcs uses an internal, static mbstate_t

  1029 object, which is initialized to the initial conversion state

  1030 at program startup.

  1031 

  1032  The mbsnrtowcs function behaves identically to mbsrtowcs, except that conversion stops after reading at most nms bytes from the buffer pointed to by src.

  1033 

  1034  The behavior of the mbsrtowcs and mbsnrtowcs is affected by LC_CTYPE category of the current locale.

  1035 

  1036 Examples:

  1037 @code

  1038 /* Illustrates how to use mbsrtowcs API */

  1039 #include <stdio.h>

  1040 #include <stdlib.h>

  1041 #include <wchar.h>

  1042 size_t example_mbsrtowcs(wchar_t *wc, char *s, size_t n)

  1043 {

  1044  size_t len;

  1045  mbstate_t mbs;

  1046  /* converting multibyte string to a wide-char string */

  1047  len = mbsrtowcs(wc, &s;, n, &mbs;);

  1048  /* checking for error */

  1049  if(len < 0)

  1050  {

  1051         wprintf(L"mbsrtowcs returned error!!

  1052 ");

  1053  }

  1054  /* returning no of bytes consumed */

  1055  return (len);

  1056 }

  1057 

  1058 @endcode

  1059 @code

  1060 /* Illustrates how to use mbsrntowcs API */

  1061 #include <stdio.h>

  1062 #include <stdlib.h>

  1063 #include <wchar.h>

  1064 size_t example_mbsnrtowcs(wchar_t *wc, char *s, size_t n, size_t nms)

  1065 {

  1066   size_t len;

  1067   mbstate_t mbs;

  1068  /* converting multibyte string to a wide-char string */

  1069   len = mbsnrtowcs(wc, &s;, nms, n, &mbs;);

  1070  /* checking for error */

  1071  if(len < 0)

  1072  {

  1073         wprintf(L"mbsnrtowcs returned error!!

  1074 ");

  1075  }

  1076   /* returning no of bytes consumed */

  1077   return (len);

  1078 }

  1079 

  1080 @endcode

  1081 

  1082 Errors:

  1083 

  1084 The mbsrtowcs and mbsnrtowcs functions will fail if: 

  1085 [EILSEQ]An invalid multibyte character sequence was encountered.  

  1086 [EINVAL] The conversion state is invalid.

  1087 

  1088 

  1089 Limitations:

  1090 

  1091 The current implementation of mbsrtowcs and mbsnrtowcs is not affected by the LC_CTYPE category of the current locale.

  1092 It works only for UTF8 character set.

  1093 

  1094 @see mbrtowc()

  1095 @see mbstowcs()

  1096 @see wcsrtombs()

  1097 

  1098 

  1099  

  1100 

  1101 @publishedAll

  1102 @externallyDefinedApi

  1103 */

  1104 

  1105 

  1106 /** @fn  putwc(wchar_t wc, FILE *stream)

  1107 @param wc

  1108 @param stream

  1109 

  1110 Refer to fputwc() for the documentation

  1111 

  1112 @see ferror()

  1113 @see fopen()

  1114 @see getwc()

  1115 @see putc()

  1116 

  1117 

  1118  

  1119 

  1120 @publishedAll

  1121 @externallyDefinedApi

  1122 */

  1123 

  1124 /** @fn  putwchar(wchar_t wc)

  1125 @param wc

  1126 

  1127 Refer to  fputwc() for the documentation

  1128 

  1129 @see ferror()

  1130 @see fopen()

  1131 @see getwc()

  1132 @see putc()

  1133 

  1134 

  1135