1 /** @file ../include/wchar.h
8 Note: This description also covers the following functions -
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
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.
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.
27 // Illustrates how to use btowc API
28 wint_t example_btowc(int c)
31 // converting single byte to wide-character
33 // return the character that was converted
40 /* Illustrates how to use wctob API */
41 int example_wctob(void)
46 /* represent a wide-char in a single byte*/
48 /* return the single byte */
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.
69 /** @fn fgetwc(FILE *stream)
72 Note: This description also covers the following functions -
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 .
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 .
84 acts essentially identical to fgetwc.
87 is equivalent to getwc with the argument stdin.
91 /* Illustrates how to use fgetwc API */
94 wint_t example_fgetwc(void)
99 /* opening the input file */
100 fp = fopen("input.txt","r");
103 wprintf(L"Error: File open
107 /* Read a character from the opened file */
109 /* Close the file open for reading */
111 /* return the character read from the file */
117 /* Illustrates how to use getwc API */
120 wint_t example_getwc(void)
125 /* opening the input file */
126 fp = fopen("input.txt","r");
129 wprintf(L"Error: File open
133 /* Read a character from the opened file */
135 /* Close the file open for reading */
137 /* return the character read from the file */
143 /* Illustrates how to use getwchar API */
146 wint_t example_getwchar(void)
150 /* Read a character from standard input */
152 /* return the character read */
168 @externallyDefinedApi
172 /** @fn fgetws(wchar_t * ws, int n, FILE * 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.
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.
188 /* Illustrates how to use fgetws API */
189 wchar_t *example_fgetws(wchar_t *buf)
194 /* for example, 10 characters to be read */
196 /* opening the input file */
197 fp = fopen("input.txt","r");
200 wprintf(L"Error: File open
204 /* Read characters from the opened file */
205 retval = fgetws(buf, n, fp);
206 /* Close the file open for reading */
208 /* return the character read from the file */
221 @externallyDefinedApi
224 /** @fn fputwc(wchar_t wc, FILE *stream)
228 Note: This description also covers the following functions -
231 @return The fputwc, putwc, and putwchar functions
232 return the wide character written.
233 If an error occurs, the value WEOF is returned.
236 writes the wide character wc to the output stream pointed to by stream.
239 acts essentially identically to fputwc.
241 The putwchar function
242 is identical to putwc with an output stream of stdout.
246 /* Illustrates how to use putwc API */
249 wint_t example_putwc(void)
254 /* opening the file to write*/
255 fp = fopen("input.txt","w");
258 wprintf(L"Error: File open
262 /* write a character into fp */
263 rval = putwc(wc, fp);
264 /* Close the file opened for writing */
266 /* return the value that was written */
272 /* Illustrates how to use fputwc API */
275 wint_t example_fputwc(void)
280 /* opening the file to write*/
281 fp = fopen("input.txt","w");
284 wprintf(L"Error: File open
288 /* write a character into fp */
289 rval = fputwc(wc, fp);
290 /* Close the file opened for writing */
292 /* return the value that was written */
298 /* Illustrates how to use putwchar API */
301 wint_t example_putwchar(void)
306 /* write a character onto the standard output */
308 /* return the character that was written */
327 @externallyDefinedApi
331 /** @fn fputws(const wchar_t * ws, FILE * fp)
334 @return The fputws function
335 returns 0 on success and -1 on error.
337 The fputws function writes the wide character string pointed to by ws to the stream pointed to by fp.
343 /* Illustrates how to use fputws API */
344 int example_fputws(wchar_t *buf)
348 /* open the file for writing*/
349 fp = fopen("write.txt","r");
352 wprintf(L"Error: File open
356 /* Write the characters into the file */
357 retval = fputws(buf, fp);
358 /* Close the file open for writing */
360 /* return the number of characters written */
374 @externallyDefinedApi
378 /** @fn fwide(FILE *stream, int 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.
386 determines the orientation of the stream pointed at by stream.
388 If the orientation of stream has already been determined fwide leaves it unchanged. Otherwise fwide sets the orientation of stream according to mode.
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.
396 /* Illustrates how to use fwide API */
397 int example_fwide(void)
403 fp = fopen("input.txt","r");
406 wprintf(L"Error: File open
410 /* set the mode to wide*/
412 /* set the orientation of the file */
413 retval = fwide(fp, mode);
414 /* check the return value */
417 wprintf(L"Mode set to WIDE
422 wprintf(L"Error setting the mode to wide!!
425 /* set the mode to determine the orientation */
427 /* Read back the orientation that was set */
428 retval = fwide(fp ,mode);
431 wprintf("Mode not changed
436 wprintf("Error, mode changed!!
439 /* Close the file open for writing */
441 /* return the mode of fp */
458 @externallyDefinedApi
462 /** @fn fwprintf(FILE * stream, const wchar_t * format, ...)
467 Note: This description also covers the following functions -
468 swprintf() snwprintf() vsnwprintf() wprintf() vfwprintf() vswprintf() vwprintf()
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.
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.
475 These functions return the number of characters printed (not including the trailing ‘\\0’ used to end output to strings).
477 The swprintf , snwprintf , vswprintf and vsnwprintf functions will fail if n or more wide characters were requested to be written.
483 1. swprintf and snwprintf can be used interchangeably.
485 2. vswprintf and vsnwprintf can be used interchangeably.
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:
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:
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.
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.
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.
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).
503 '+' A sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used.
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.
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.
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.
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:
518 Modifier d, i o, u, x, X n
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 *
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 .
535 The following length modifier is valid for the a, A, e, E, f, F, g, or G conversion:
541 Modifier a, A, e, E, f, F, g, G
548 The following length modifier is valid for the c or s conversion:
551 l (ell) wint_t wchar_t *
557 A character that specifies the type of conversion to be applied.
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.
561 The conversion specifiers and their meanings are:
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.
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.
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.
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.
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.
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.
581 C Treated as c with the l (ell) modifier.
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.
585 If the l (ell) modifier is used, the wint_t argument is converted to a wchar_t and written.
587 S Treated as s with the l (ell) modifier.
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.
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.
593 p The void * pointer argument is printed in hexadecimal (as if by ‘%#x’ or ‘%#lx’).
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.
597 % A ‘%’ is written. No argument is converted. The complete conversion specification is ‘%%’.
601 The decimal point character is defined in the program’s locale (category LC_NUMERIC).
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.
610 /* Illustrates how to use wprintf API */
611 int example_wprintf(void)
615 /* prints the integers on the standard output */
616 rval = wprintf(L"%d", input);
617 /* return the number of wide characters that were written */
630 /* Illustrates how to use fwprintf API */
631 int example_fwprintf(void)
635 wchar_t *wcs = L"abc";
636 /* open the file for writing*/
637 fp = fopen("write.txt","w");
640 wprintf(L"Error: File open
644 /* print the characters into the file */
645 retval = fwprintf(fp, L"%s", wcs);
646 /* Close the file opened for writing */
648 /* return the number of wide characters that were written */
656 /* Illustrates how to use swprintf API */
657 int example_swprintf(wchar_t *buf, int maxlen)
659 wchar_t *wcs = L"abcdef";
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 */
671 /* Illustrates how to use vwprintf API */
672 int example_vwprintf(va_list input)
675 /* prints the integers on the standard output */
676 rval = vwprintf(L"%d", input);
677 /* return the number of wide characters that were written */
685 /* Illustrates how to use vfwprintf API */
686 int example_vfwprintf(va_list input)
691 /* open the file for writing*/
692 fp = fopen("write.txt","w");
695 wprintf(L"Error: File open
699 /* print the characters into the file */
700 retval = vfwprintf(fp, L"%s", input);
701 /* Close the file opened for writing */
703 /* return the number of wide characters that were written */
711 /* Illustrates how to use vswprintf API */
712 int example_vswprintf(wchar_t *buf, int maxlen, va_list input)
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 */
723 Security considerations:
729 Long double length modifiers are not supported. The maximum floating point
730 precision is 15 digits.
744 @externallyDefinedApi
747 /** @fn fwscanf(FILE * stream, const wchar_t * format, ...)
752 Refer to wscanf() for the documentation
766 @externallyDefinedApi
769 /** @fn getwc(FILE *stream)
772 Refer to fgetwc() for the documentation
785 @externallyDefinedApi
789 /** @fn getwchar(void)
791 Refer to fgetwc() for the documentation
804 @externallyDefinedApi
807 /** @fn mbrlen(const char * s, size_t n, mbstate_t * ps)
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.
818 The mbrlen function inspects at most n bytes pointed to by s to determine the number of bytes needed to complete the next
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
831 mbrtowc(NULL, s, n, ps);
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.
839 A function that calculates the number of characters in a multibyte
843 nchars(const char *s)
845 size_t charlen, chars;
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) {
861 The mbrlen function will fail if:
862 [EILSEQ] An invalid multibyte sequence was detected.
863 [EINVAL] The conversion state is invalid.
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.
877 @externallyDefinedApi
880 /** @fn mbrtowc(wchar_t * pwc, const char * s, size_t n, mbstate_t * ps)
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.
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
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
898 If s is NULL, mbrtowc behaves as if pwc was NULL, s was an empty string ("")
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
907 The behavior of the mbrtowc is affected by LC_CTYPE category of the current locale.
914 /* Illustrates how to use mbrtowc API */
915 size_t example_mbrtowc()
922 /* converting multibyte sequence to a wide-char sequence */
923 len = mbrtowc(wc,(const char *) s, n, &ps;);
924 /* checking for error value */
927 wprintf(L"mbrtowc returned error!!
930 /* returning no of bytes consumed */
938 The mbrtowc function will fail if:
939 [EILSEQ] An invalid multibyte sequence was detected.
940 [EINVAL]The conversion state is invalid.
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.
956 @externallyDefinedApi
959 /** @fn mbsinit(const mbstate_t *ps)
962 @return The mbsinit function returns non-zero if ps is NULL or describes an initial conversion state,
963 otherwise it returns zero.
965 The mbsinit function determines whether the mbstate_t
966 object pointed to by ps describes an initial conversion state.
968 The behavior of the mbsinit is affected by LC_CTYPE category of the current locale.
974 /* Illustrates how to use mbsinit API */
975 int example_mbsinit(void)
980 /* testing for the initial state */
981 state = mbsinit(&mbs;);
982 /* return the state */
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.
1003 @externallyDefinedApi
1006 /** @fn mbsrtowcs(wchar_t * dst, const char ** src, size_t len, mbstate_t * ps)
1012 Note: This description also covers the following functions -
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).
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'.)
1021 If dst is NULL no characters are stored.
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.
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
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.
1034 The behavior of the mbsrtowcs and mbsnrtowcs is affected by LC_CTYPE category of the current locale.
1038 /* Illustrates how to use mbsrtowcs API */
1042 size_t example_mbsrtowcs(wchar_t *wc, char *s, size_t n)
1046 /* converting multibyte string to a wide-char string */
1047 len = mbsrtowcs(wc, &s;, n, &mbs;);
1048 /* checking for error */
1051 wprintf(L"mbsrtowcs returned error!!
1054 /* returning no of bytes consumed */
1060 /* Illustrates how to use mbsrntowcs API */
1064 size_t example_mbsnrtowcs(wchar_t *wc, char *s, size_t n, size_t nms)
1068 /* converting multibyte string to a wide-char string */
1069 len = mbsnrtowcs(wc, &s;, nms, n, &mbs;);
1070 /* checking for error */
1073 wprintf(L"mbsnrtowcs returned error!!
1076 /* returning no of bytes consumed */
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.
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.
1102 @externallyDefinedApi
1106 /** @fn putwc(wchar_t wc, FILE *stream)
1110 Refer to fputwc() for the documentation
1121 @externallyDefinedApi
1124 /** @fn putwchar(wchar_t wc)
1127 Refer to fputwc() for the documentation
1138 @externallyDefinedApi
1141 /** @fn swprintf(wchar_t * s, size_t n, const wchar_t * fmt, ...)
1147 Refer to fwprintf() for the documentation
1161 @externallyDefinedApi
1164 /** @fn swscanf(const wchar_t * str, const wchar_t *fmt, ...)
1169 Refer to wscanf() for the documentation
1183 @externallyDefinedApi
1186 /** @fn ungetwc(wint_t wc, FILE *stream)
1189 @return The ungetwc function
1191 the wide character pushed-back after the conversion, or WEOF if the operation fails.
1192 If the value of the argument c character equals WEOF ,
1193 the operation will fail and the stream will remain unchanged.
1195 The ungetwc function pushes the wide character wc (converted to an wchar_t )
1196 back onto the input stream pointed to by stream .
1197 The pushed-backed wide characters will be returned by subsequent reads on the
1198 stream (in reverse order).
1199 A successful intervening call, using the same stream, to one of the file
1200 positioning functions fseek , fsetpos ,
1201 or rewind will discard the pushed back wide characters.
1203 One wide character of push-back is guaranteed,
1204 but as long as there is
1205 sufficient memory, an effectively infinite amount of pushback is allowed.
1207 If a character is successfully pushed-back,
1208 the end-of-file indicator for the stream is cleared.
1214 /* Illustrates how to use ungetwc API */
1215 wint_t example_ungetwc(void)
1221 /* opening the file to write*/
1222 fp = fopen("input.txt","w");
1225 wprintf(L"Error: File open
1229 /* character to written back to the fp */
1231 /* write the character into the fp */
1232 rval = ungetwc(wc, fp);
1233 /* check for error */
1236 wprintf(L"ungetwc returned error!!
1239 /* Read the character from fp */
1240 /* this char should be the same as the char */
1241 /* that was written by ungetwc */
1243 /* Close the file opened for writing */
1245 /* return the value that was written */
1257 @externallyDefinedApi
1260 /** @fn vfwprintf(FILE * stream, const wchar_t * , va_list ap)
1265 Refer to fwprintf() for the documentation
1279 @externallyDefinedApi
1282 /** @fn vswprintf(wchar_t *s, size_t n, const wchar_t *fmt, va_list ap)
1288 Refer to fwprintf() for the documentation
1302 @externallyDefinedApi
1305 /** @fn vwprintf(const wchar_t * fmt, va_list ap)
1309 Refer to fwprintf() for the documentation
1323 @externallyDefinedApi
1326 /** @fn wcrtomb(char * mbchar, wchar_t wc, mbstate_t * ps)
1330 @return The wcrtomb functions returns the length (in bytes) of the multibyte sequence
1331 needed to represent wc ,
1332 or ( size_t-1) if wc is not a valid wide character code.
1334 The wcrtomb function stores a multibyte sequence representing the
1336 including any necessary shift sequences, to the
1338 storing a maximum of MB_CUR_MAX bytes.
1340 If s is NULL , wcrtomb behaves as if s pointed to an internal buffer and wc was a null wide character (L'\\0').
1342 The mbstate_t argument, ps ,
1343 is used to keep track of the shift state.
1344 If it is NULL , wcrtomb uses an internal, static mbstate_t
1345 object, which is initialized to the initial conversion state
1348 The behavior of the wcrtomb is affected by LC_CTYPE category of the current locale.
1355 /* Illustrates how to use wcrtomb API */
1356 int example_wcrtomb(wchar_t wc)
1358 char s[MAX_CUR_MAX];
1362 /* represent a wide-char in a single byte*/
1363 len = wcrtomb(s, wc, &mbs;);
1364 /* return the number of bytes */
1372 The wcrtomb function will fail if:
1373 [EILSEQ] An invalid wide character code was specified.
1374 [EINVAL] The conversion state is invalid.
1379 The current implementation of wcrtomb is not affected by the LC_CTYPE category of the current locale.
1380 It works only for UTF8 character set.
1390 @externallyDefinedApi
1393 /** @fn wcscat(wchar_t * s1, const wchar_t * s2)
1397 Refer to wmemchr() for the documentation
1422 @externallyDefinedApi
1425 /** @fn wcschr(const wchar_t *s, wchar_t c)
1429 Refer to wmemchr() for the documentation
1454 @externallyDefinedApi
1457 /** @fn wcscmp(const wchar_t *s1, const wchar_t *s2)
1461 Refer to wmemchr() for the documentation
1486 @externallyDefinedApi
1489 /** @fn wcscoll(const wchar_t *ws1, const wchar_t *ws2)
1492 @return The wcscoll function
1493 returns an integer greater than, equal to, or less than 0,
1494 if ws1 is greater than, equal to, or less than ws2 . No return value is reserved to indicate errors;
1495 callers should set errno to 0 before calling wcscoll .
1496 If it is non-zero upon return from wcscoll ,
1497 an error has occurred.
1499 The wcscoll function compares the null-terminated strings ws1 and ws2 according to the current locale collation order.
1501 locale, wcscoll is equivalent to wcscmp .
1506 /* Illustrates how to use wcscoll API */
1507 int example_wcscoll (void)
1509 /* compares the two strings */
1510 if( wcscoll(L"abcdef",L"abcdeg") != L'f'-L'g')
1519 The wcscoll function will fail if:
1520 [EILSEQ] An invalid wide character code was specified.
1521 [ENOMEM] Cannot allocate enough memory for temporary buffers.
1526 The current implementation of wcscoll is not affected by the LC_CTYPE category of the current locale. It is equivalent to wcscmp in this implementation.
1536 The current implementation of wcscoll only works in single-byte LC_CTYPE locales, and falls back to using wcscmp in locales with extended character sets.
1541 @externallyDefinedApi
1544 /** @fn wcscpy(wchar_t * s1, const wchar_t * s2)
1548 Refer to wmemchr() for the documentation
1573 @externallyDefinedApi
1577 /** @fn wcscspn(const wchar_t *s1, const wchar_t *s2)
1581 Refer to wmemchr() for the documentation
1606 @externallyDefinedApi
1610 /** @fn wcsftime(wchar_t * wcs, size_t maxsize, const wchar_t * format, const struct tm * timeptr)
1615 @return wcsftime shall return the number of wide-character codes placed into the array pointed to by wcs , not including the terminating null wide-character code. Otherwise, zero is returned and the contents of the array are unspecified.
1617 The wcsftime function is equivalent to the strftime function except for the types of its arguments.
1618 Refer to strftime() for a detailed description.
1624 /* Illustatrates how to use wcsftime API */
1625 int example_wcsftime()
1627 wchar_t datestring[50];
1631 /* get the current time */
1632 time_t t = time(NULL);
1634 /* get the local time from the current time */
1635 tm = localtime(&t;);
1636 /* convert date and time to a wide-character string */
1637 retval = wcsftime(datestring,15,L"%A",tm);
1639 /* If the total number of resulting wide-character codes */
1640 /* including the terminating null wide-character code is */
1641 /* no more than maxsize, wcsftime() shall return the number */
1642 /* of wide-character codes placed into the array pointed to */
1643 /* by wcs, not including the terminating null wide-character */
1644 /* code. Otherwise, zero is returned and the contents of the */
1645 /* array are unspecified.*/
1654 @externallyDefinedApi
1658 /** @fn wcslen(const wchar_t *s)
1661 Refer to wmemchr() for the documentation
1686 @externallyDefinedApi
1691 /** @fn wcsncat(wchar_t * s1, const wchar_t * s2, size_t n)
1696 Refer to wmemchr() for the documentation
1721 @externallyDefinedApi
1726 /** @fn wcsncmp(const wchar_t *s1, const wchar_t * s2, size_t n)
1731 Refer to wmemchr() for the documentation
1756 @externallyDefinedApi
1760 /** @fn wcsncpy(wchar_t * dst, const wchar_t * src, size_t n)
1765 Refer to wmemchr() for the documentation
1790 @externallyDefinedApi
1794 /** @fn wcspbrk(const wchar_t *s1, const wchar_t *s2)
1798 Refer to wmemchr() for the documentation
1823 @externallyDefinedApi
1827 /** @fn wcsrchr(const wchar_t *s, wchar_t c)
1831 Refer to wmemchr() for the documentation
1856 @externallyDefinedApi
1860 /** @fn wcsrtombs(char * dst, const wchar_t ** src, size_t len, mbstate_t * ps)
1866 Note: This description also covers the following functions -
1869 @return The wcsrtombs and wcsnrtombs functions return the number of bytes stored in
1870 the array pointed to by dst (not including any terminating null), if successful, otherwise it returns ( size_t-1) .
1872 The wcsrtombs function converts a string of wide characters indirectly pointed to by src to a corresponding multibyte character string stored in the array
1874 No more than len bytes are written to dst .
1877 no characters are stored.
1879 If dst is not NULL ,
1880 the pointer pointed to by src is updated to point to the character after the one that conversion stopped at.
1881 If conversion stops because a null character is encountered, *src is set to NULL .
1885 is used to keep track of the shift state.
1886 If it is NULL , wcsrtombs uses an internal, static mbstate_t
1887 object, which is initialized to the initial conversion state
1890 The wcsnrtombs function behaves identically to wcsrtombs ,
1891 except that conversion stops after reading at most nwc characters from the buffer pointed to by src .
1892 The behavior of the wcsrtombs and wcsrntombs is affected by LC_CTYPE category of the current locale.
1898 /* Illustrates how to use wcsrtombs API */
1899 size_t example_wcsrtombs(wchar_t *wcs, char *s, size_t n)
1903 /* converting multibyte string to a wide-char string */
1904 len = wcsrtombs(s, &wcs;, n, &mbs;);
1905 /* returning no of bytes that make up the multibyte sequence */
1913 /* Illustrates how to use wcsnrtombs API */
1914 size_t example_wcsnrtombs(wchar_t *wcs, char *s, size_t n, szie_t nmwc)
1918 /* converting multibyte string to a wide-char string */
1919 len = wcsrtombs(s, &wcs;, nwc, n, &mbs;);
1920 /* returning no of bytes that make up the multibyte sequence */
1928 The current implementation of wcsrtombs and wcsnrtombs is not affected by the LC_CTYPE category of the current locale.
1929 It works only for UTF8 character set.
1939 @externallyDefinedApi
1943 /** @fn wcsspn(const wchar_t *s1, const wchar_t *s2)
1947 Refer to wmemchr() for the documentation
1972 @externallyDefinedApi
1977 /** @fn wcsstr(const wchar_t * s, const wchar_t * find)
1981 Refer to wmemchr() for the documentation
2006 @externallyDefinedApi
2011 /** @fn wcsxfrm(wchar_t * dest, const wchar_t * src, size_t len)
2015 @return Upon successful completion, wcsxfrm returns the length of the transformed string not including
2016 the terminating null character.
2017 If this value is len or more, the contents of dest are indeterminate.
2019 The wcsxfrm function transforms a null-terminated wide character string pointed to by src according to the current locale collation order
2020 then copies the transformed string
2022 No more than len wide characters are copied into dest ,
2023 including the terminating null character added.
2025 (it helps to determine an actual size needed
2026 for transformation), dest is permitted to be a NULL pointer.
2028 Comparing two strings using wcscmp after wcsxfrm is equivalent to comparing
2029 two original strings with wcscoll .
2035 /* Illustrates how to use wcpcpy API */
2036 int example_wcpcpy()
2038 /* input string for which length to be found */
2039 wchar_t *src = L"testcase";
2040 wchar_t *dest = NULL;
2043 /* allocate memory for the destination string */
2044 dest = (wchar_t *)malloc((wcslen(src)+1)*sizeof(wchar_t));
2046 /* perform the operation */
2048 length = wcsxfrm(dest,src,9);
2051 wprintf(L"ERROR : Cannot allocate memory");
2061 The current implementation of wcsxfrm works only for "C" locale.
2071 The current implementation of wcsxfrm only works in single-byte LC_CTYPE locales, and falls back to using wcsncpy in locales with extended character sets. Comparing two strings using wcscmp after wcsxfrm is not always equivalent to comparison with wcscoll ; wcsxfrm only stores information about primary collation weights into dst ,
2072 whereas wcscoll compares characters using both primary and secondary weights.
2077 @externallyDefinedApi
2082 /** @fn wctob(wint_t c)
2085 Refer to btowc() for the documentation
2094 @externallyDefinedApi
2099 /** @fn wcstod(const wchar_t * nptr, wchar_t ** endptr)
2103 Refer to wcstof() for the documentation
2112 @externallyDefinedApi
2117 /** @fn wcstok(wchar_t * s, const wchar_t * delim, wchar_t ** last)
2121 @return The wcstok function
2122 returns a pointer to the beginning of each subsequent token in the string,
2123 after replacing the token itself with a null wide character (L'//0').
2124 When no more tokens remain, a null pointer is returned.
2127 is used to isolate sequential tokens in a null-terminated wide character
2129 These tokens are separated in the string by at least one of the
2130 characters in delim .
2131 The first time that wcstok is called, s should be specified; subsequent calls, wishing to obtain further tokens
2132 from the same string, should pass a null pointer instead.
2133 The separator string, delim ,
2134 must be supplied each time, and may change between calls.
2135 The context pointer last must be provided on each call.
2137 The wcstok function is the wide character counterpart of the strtok_r function.
2144 /* Illustrates how to use wcstok API */
2145 int example_wcstok()
2147 /* source wide character string */
2148 const wchar_t *seps = L"onetwhr";
2149 wchar_t *last, *tok, text[] = L"onetwothree";
2151 tok = wcstok(text, seps, &last;);
2162 The following code fragment splits a wide character string on ASCII space, tab and newline characters and writes the tokens to
2166 const wchar_t *seps = L"
2168 wchar_t *last, *tok, text[] = L"
2171 for (tok = wcstok(text, seps, &last;); tok != NULL;
2172 tok = wcstok(NULL, seps, &last;))
2185 Some early implementations of wcstok omit the context pointer argument, last, and maintain state across calls in a static variable like strtok does.
2189 @externallyDefinedApi
2194 /** @fn wcstol(const wchar_t * nptr, wchar_t ** endptr, int base)
2199 Note: This description also covers the following functions -
2200 wcstoul() wcstoll() wcstoull() wcstoq() wcstouq() wcstoimax() wcstoumax()
2202 @return errno may be set to indicate the error. If the correct value is outside
2203 the range of representable values {LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or {LLONG_MAX}
2204 is returned (according to the sign of the value) and errno set to [ERANGE].
2206 The wcstol , wcstoul , wcstoll , wcstoull , wcstoimax and wcstoumax functions are wide-character versions of the strtol , strtoul , strtoll , strtoull , strtoimax and strtoumax functions, respectively.
2207 Refer to their manual pages (for example strtol )
2209 The wcstoq and wcstouq are respectively equivalent to wcstoll and wcstoull.
2214 /* Illustrates how to use wcstoumax API */
2215 uintmax_t example_wcstoumax()
2218 wchar_t *src = L"478";
2221 /* convert the wide character string to uintmax_t */
2222 longVal = wcstoumax(src,NULL,10);
2223 /* return the converted long value */
2230 /* Illustrates how to use wcstoimax API */
2231 intmax_t example_wcstoimax()
2234 wchar_t *src = L"478";
2237 /* convert the wide character string to intmax_t */
2238 longVal = wcstoimax(src,NULL,10);
2239 /* return the converted long value */
2246 /* Illustrates how to use wcstol API */
2247 long example_wcstol()
2250 wchar_t *src = L"478";
2253 /* call the API to convert src string to long value */
2254 longVal = wcstol(src,NULL,10);
2255 /* return the converted long value */
2262 /* Illustrates how to use wcstoul API */
2263 unsigned long example_wcstoul()
2266 wchar_t *src = L"478";
2267 unsigned long longVal;
2269 /* call the API to convert src string to unsigned */
2271 longVal = wcstoul(src,NULL,10);
2272 /* return the converted long value */
2279 /* Illustatrates how to use wcstoll API */
2280 long long example_wcstoll()
2282 /* input string for which length to be found */
2283 wchar_t *src = L"478";
2286 /* perform the conversion operation from wide */
2287 /* char string to long long value */
2288 longVal = wcstoll(src,NULL,10);
2296 /* Illustatrates how to use wcstoull API */
2297 unsigned long long example_wcstoull()
2299 /* input string for which length to be found */
2300 wchar_t *src = L"478";
2301 unsigned long long longVal;
2303 /* perform the conversion operation from wide */
2304 /*char string to unsigned long long value */
2305 longVal = wcstoull(src,NULL,10);
2313 /* Illustrates how to use wcstoq API */
2314 long long int example_wcstoq()
2316 /* src string that contains decimal digits */
2317 wchar_t *src = L"478";
2318 long long int longVal;
2319 /* convert the decimal wide char string to long long int value */
2320 longVal = wcstoq(src,NULL,10);
2321 /* return longVal and its value should be 478 */
2328 /* Illustrates how to use wcstouq API */
2329 unsigned long long int example_wcstouq()
2331 /* src string that contains decimal digits */
2332 wchar_t *src = L"478";
2333 unsigned long long int longVal;
2334 /* convert the decimal wide char string to unsigned long long int value */
2335 longVal = wcstouq(src,NULL,10);
2336 /* return longVal, which should be 478 */
2348 @externallyDefinedApi
2353 /** @fn wcstoul(const wchar_t * nptr, wchar_t ** endptr, int base)
2358 Refer to wcstol() for the documentation
2367 @externallyDefinedApi
2372 /** @fn wmemchr(const wchar_t *s, wchar_t c, size_t n)
2377 Note: This description also covers the following functions -
2378 wmemcmp() wmemcpy() wmemmove() wmemset() wcscat() wcschr() wcscmp() wcscpy() wcscspn() wcslcat() wcslcpy() wcslen() wcsncat() wcsncmp() wcsncpy() wcspbrk() wcsrchr() wcsspn() wcsstr()
2380 @return wmemchr function returns a pointer to the first occurrence of c among the n wide characters starting at s , or NULL if c does not occur among these. wcslcpy function returns wcslen(src); if retval \>= siz, truncation occurred wcslcat function returns wcslen(initial dst) + wcslen(src); if retval \>= sizet,
2386 The function wcslcat() appends a copy of the wide-character string
2387 pointed to by s2 (including the terminating null wide-character code) to the end
2388 of the wide-character string pointed to by s1. The initial wide-character code
2389 of string pointed to by s2 overwrites the null wide-character code at the end of s1. wcslcat() concatenates at most n-1 characters.
2393 The function wcslcpy() copies the wide-character string pointed to by s2 (including the terminating null wide-character code) into the array pointed to by s1.
2394 It will copy at most n-1 characters.
2398 The functions implement string manipulation operations over wide character
2400 For a detailed description, refer to documents for the respective single-byte
2401 counterpart, such as memchr .
2406 /* Illustrates how to use wmemcmp API */
2407 int example_wmemcmp()
2409 /* source wide character string */
2410 wchar_t *ws1 = L"test case",*ws2 = L"test case";
2412 /* comparing the 2 wide-char strings */
2413 retval = wmemcmp(ws1,ws2,500);
2414 /* checking for the return value */
2424 /* Illustrates how to use wmemcpy API */
2425 int example_wmemcpy()
2427 /* source wide character string */
2428 wchar_t ws1[50]=L"abcdefghij",*retval,ws2[50]=L"test";
2429 /* compare the strings */
2430 retval = wmemcpy(ws1,ws2,6);
2431 for(int i=0;i<6;i++)
2433 if(retval[i] != ws2[i] || ws1[i] != ws2[i])
2442 /* Illustrates how to use wmemmove API */
2443 int example_wmemmove()
2445 /* source wide character string */
2446 wchar_t ws1[50]=L"abcdefghij",*retval,ws2[5] = L"abc";
2449 /* move the contents of ws2 to ws1 */
2450 retval = wmemmove(ws1,ws2,3);
2451 /* compare the contents */
2454 if(ws1[i] != ws2[i])
2463 /* Illustrates how to use wmemset API */
2464 int example_wmemset()
2466 /* source wide character string */
2467 wchar_t ws1[50]=L"abcdefghij", *retval;
2469 /* setting the wide-string ws1 */
2470 retval = wmemset(ws1,L'a',7);
2471 /* comparing the contents */
2483 /* Illustrates how to use wmemchr API */
2484 wchar_t *example_wmemchr(void)
2486 wchar_t *wcs = L"lmnopqr";
2490 /* number of wide characters to be searched */
2492 /* search for the occurence of wchar wc in wide-char string wcs */
2493 res = wmemchr(wcs, wc, n);
2494 /* return the pointer */
2501 /* Illustrates how to use wcslen API */
2502 size_t example_wcslen(void)
2504 wchar_t *wcs = L"defqwert";
2506 /* compute the length of the wide-char string */
2508 /* return the length of the wide-char string */
2515 /* Illustrates how to use wcscat API */
2516 void example_wcscat(void)
2518 wchar_t wcs[100] = L"abc";
2519 wchar_t *wcs1 = L"def";
2521 /* concatenate the two strings */
2522 res = wcscat(wcs, wcs1);
2523 /* print the string that resulted from concatenation */
2524 wprintf(L"Output wide-char string is : %ls
2536 /* Illustrates how to use wcschr API */
2537 int example_ wcschr ()
2539 /* source wide character string */
2540 wchar_t search_char[15] = L"&&&&$%%%%%TTU";
2543 for(i = 0 ; search_char[i]; i++)
2545 wstr = wcschr(L"", search_char[i]);
2556 int example_wcscmp()
2558 /* source wide character string */
2559 wchar_t *wcs1 = "string1";
2560 wchar_t *wcs2 = "string2";
2562 i = wcscmp(wcs1, wcs2);
2566 i = wcscmp(wcs1, L"string1");
2576 /* Illustrates how to use wcscpy API */
2577 int example_wcscpy ()
2579 /* source wide character string */
2583 /* copy the wide-char string into wcs1*/
2584 res = wcscpy(wcs1, L"Hello world");
2586 if(wcscmp(res, L"Hello world") != 0)
2595 /* Illustrates how to use wcslcpy API */
2596 int example_wcslcpy ()
2598 /* source wide character string */
2599 wchar_t src[25] = L"Source";
2600 wchar_t dest[20]= L"Destination";
2602 /* copy the wide-char string into dest*/
2604 size_t t = wcslcpy(dest,src,4);
2606 if(wcscmp(dest,L"Sou")!=0)
2615 /* Illustrates how to use wcslcat API */
2616 int example_wcslcat ()
2618 /* source wide character string */
2619 wchar_t src[25] = L"Source";
2620 wchar_t dest[20]= L"Destination";
2622 /* concate the wide-char string into dest*/
2624 size_t t = wcslcat(dest,src,14);
2626 if(wcscmp(dest,"DestinationSo")!=0)
2635 /* Illustrates how to use wcscspnAPI */
2636 int example_wcscspn ()
2638 /* source wide character string */
2639 wchar_t wcs1[30] = L"1234567890ABCDE!@#$$";
2640 wchar_t *wcs2[20] = { L"abcdefghijkl",
2646 L"as1sd2ds3ds48f5fd"
2650 for( i = 0; i < 3 ; i ++)
2652 if( wcslen(wcs1) != wcscspn(wcs1,wcs2[i]))
2662 /* Illustrates how to use wcsncat API */
2663 int example_wcsncat ()
2665 /* source wide character string */
2669 wcscpy(str, L"Hello");
2670 res = wcsncat(str,L" world",12);
2671 if(wcscmp(str, L"Hello world") != 0)
2680 /* Illustrates how to use wcsncmp API */
2681 int example_wcsncmp()
2683 /* source wide character string */
2684 wchar_t *wcs1 = L"Hello world";
2685 if(wcsncmp(wcs1,wcs1,wcslen(wcs1)))
2694 /* Illustrates how to use wcsncpy API */
2695 int example_wcsncpy ()
2697 /* source wide character string */
2698 wchar_t wcs1[15] = L"Hello world";
2700 res = wcsncpy(wcs1,wcs1,wcslen(wcs1));
2701 if(wcscmp(res,wcs1))
2709 /* Illustrates how to use wcspbrk API */
2710 int example_wcspbrk ()
2712 /* source wide character string */
2713 wchar_t *wcs = L"abcdefghijkl";
2714 wchar_t *res1 = wcspbrk(wcs, L"");
2724 /* Illustrates how to use wcsrchr API */
2725 int example_wcsrchr ()
2727 /* source wide character string */
2728 wchar_t search_char[15] = L"&&&&$%%%%%TTU";
2732 for(i = 0 ; search_char[i]; i++)
2734 wstr = wcsrchr(L"", search_char[i]);
2746 /* Illustrates how to use wcsspn API */
2747 int example_wcsspn()
2749 /* source wide character string */
2750 wchar_t wcs1[30] = L"1234567890ABCDE!@#$$";
2751 if(wcslen(wcs1) != wcsspn(wcs1,wcs1))
2759 /* Illustrates how to use wcsstr API */
2760 int example_wcsstr()
2762 /* source wide character string */
2763 wchar_t *buf[20] = { L"fkhsdf%%38",L"rtti123123", };
2764 wchar_t *str = wcsstr(buf[0],L"\0");
2765 wchar_t *str1 = wcsstr(buf[1],L"\0");
2766 if(wcscmp(str,buf[0]))
2768 if(wcscmp(str1,buf[1]))
2797 @externallyDefinedApi
2802 /** @fn wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n)
2807 Refer to wmemchr() for the documentation
2832 @externallyDefinedApi
2837 /** @fn wmemcpy(wchar_t * s1, const wchar_t * s2, size_t n)
2842 Refer to wmemchr() for the documentation
2867 @externallyDefinedApi
2872 /** @fn wmemmove(wchar_t *s1, const wchar_t *s2, size_t n)
2877 Refer to wmemchr() for the documentation
2902 @externallyDefinedApi
2907 /** @fn wmemset(wchar_t *s, wchar_t c, size_t n)
2912 Refer to wmemchr() for the documentation
2937 @externallyDefinedApi
2942 /** @fn wprintf(const wchar_t *fmt, ...)
2946 Refer to fwprintf() for the documentation
2960 @externallyDefinedApi
2965 /** @fn wscanf(const wchar_t *fmt, ...)
2969 Note: This description also covers the following functions -
2970 fwscanf() swscanf() vwscanf() vswscanf() vfwscanf()
2975 the number of input items assigned, which can be fewer than provided
2976 for, or even zero, in the event of a matching failure.
2978 indicates that, while there was input available,
2979 no conversions were assigned;
2980 typically this is due to an invalid input character,
2981 such as an alphabetic character for a '\%d'
2983 The value EOF is returned if an input failure occurs before any conversion such as an
2985 If an error or end-of-file occurs after conversion
2987 the number of conversions which were successfully completed is returned.
2989 The wscanf family of functions scans input according to a format as described below.
2990 This format may contain conversion specifiers ;
2991 the results from such conversions, if any,
2992 are stored through the pointer arguments.
2994 reads input from the standard input stream stdin , fwscanf reads input from the stream pointer stream ,
2995 and swscanf reads its input from the wide character string pointed to by str .
2996 The vfwscanf function
2997 is analogous to vfwprintf and reads input from the stream pointer stream using a variable argument list of pointers.
2998 The vwscanf function scans a variable argument list from the standard input and
2999 the vswscanf function scans it from a wide character string;
3000 these are analogous to
3001 the vwprintf and vswprintf functions respectively.
3002 Each successive pointer argument must correspond properly with
3003 each successive conversion specifier
3004 (but see the * conversion below).
3005 All conversions are introduced by the \% (percent sign) character.
3007 may also contain other characters.
3008 White space (such as blanks, tabs, or newlines) in the format string match any amount of white space, including none, in the input.
3010 matches only itself.
3012 when an input character does not match such a format character.
3014 when an input conversion cannot be made (see below).
3021 Following the % character introducing a conversion there may be a number of flag characters, as follows: * Suppresses assignment. The conversion that follows occurs as usual, but no pointer is used; the result of the conversion is simply discarded.
3022 hh Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a char (rather than int ) .
3023 h Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a short int (rather than int ) .
3024 l (ell) Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a long int (rather than int ) , that the conversion will be one of a, e, f, or g and the next pointer is a pointer to double (rather than float ) , or that the conversion will be one of c or s and the next pointer is a pointer to an array of wchar_t (rather than char ) .
3026 Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a long long int (rather than int ) .
3027 L Indicates that the conversion will be one of a, e, f, or g and the next pointer is a pointer to long double .
3028 j Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a intmax_t (rather than int ) .
3029 t Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a ptrdiff_t (rather than int ) .
3030 z Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a size_t (rather than int ) .
3031 q (deprecated.) Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a long long int (rather than int ) .
3034 In addition to these flags, there may be an optional maximum field width, expressed as a decimal integer, between the % and the conversion. If no width is given, a default of "infinity" is used (with one exception, below); otherwise at most this many characters are scanned in processing the conversion. Before conversion begins, most conversions skip white space; this white space is not counted against the field width.
3036 The following conversions are available: % Matches a literal ‘%’. That is, "%%" in the format string matches a single input ‘%’ character. No conversion is done, and assignment does not occur.
3037 d Matches an optionally signed decimal integer; the next pointer must be a pointer to int .
3038 i Matches an optionally signed integer; the next pointer must be a pointer to int . The integer is read in base 16 if it begins with ‘0x’ or ‘0X’, in base 8 if it begins with ‘0’, and in base 10 otherwise. Only characters that correspond to the base are used.
3039 o Matches an octal integer; the next pointer must be a pointer to unsigned int .
3040 u Matches an optionally signed decimal integer; the next pointer must be a pointer to unsigned int .
3041 x, X Matches an optionally signed hexadecimal integer; the next pointer must be a pointer to unsigned int .
3042 a, A, e, E, f, F, g, G
3043 Matches a floating-point number in the style of wcstod. The next pointer must be a pointer to float (unless l or L is specified.)
3044 s Matches a sequence of non-white-space wide characters; the next pointer must be a pointer to char , and the array must be large enough to accept the multibyte representation of all the sequence and the terminating NUL character. The input string stops at white space or at the maximum field width, whichever occurs first.
3045 If an l qualifier is present, the next pointer must be a pointer to wchar_t , into which the input will be placed.
3048 c Matches a sequence of width count wide characters (default 1); the next pointer must be a pointer to char , and there must be enough room for the multibyte representation of all the characters (no terminating NUL is added). The usual skip of leading white space is suppressed. To skip white space first, use an explicit space in the format.
3049 If an l qualifier is present, the next pointer must be a pointer to wchar_t , into which the input will be placed.
3052 [ Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to char , and there must be enough room for the multibyte representation of all the characters in the string, plus a terminating NUL character. The usual skip of leading white space is suppressed. The string is to be made up of characters in (or not in) a particular set; the set is defined by the characters between the open bracket [ character and a close bracket ] character. The set excludes those characters if the first character after the open bracket is a circumflex ^. To include a close bracket in the set, make it the first character after the open bracket or the circumflex; any other position will end the set. To include a hyphen in the set, make it the last character before the final close bracket; some implementations of wscanf use "A-Z" to represent the range of characters between ‘A’ and ‘Z’. The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out.
3053 If an l qualifier is present, the next pointer must be a pointer to wchar_t , into which the input will be placed.
3055 p Matches a pointer value (as printed by ‘%p’ in wprintf); the next pointer must be a pointer to void .
3056 n Nothing is expected; instead, the number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to int . This is not a conversion, although it can be suppressed with the * flag.
3060 The decimal point character is defined in the program’s locale (category LC_NUMERIC).
3062 For backwards compatibility, a "conversion" of ‘%\0’ causes an immediate return of EOF.
3070 /* Illustrates how to use wscanf API */
3071 int example_wscanf(void)
3075 /* Display a message to the user to input an integer */
3076 wprintf(L"Enter an integer : ");
3077 /* Read an integer from the standard input */
3078 rval = wscanf(L"%d", &input;);
3080 /* return the number of inputs that were read */
3088 /* Illustrates how to use swscanf API */
3089 int example_swscanf(void)
3093 wchar_t *bufptr = L"abcdefg";
3094 /* Read a string from the buffer bufptr*/
3095 rval = swscanf(bufptr, L"%s", wcs);
3097 /* The string that was read into wcs is printed */
3100 /* return the number of inputs that were read */
3108 /* Illustrates how to use fwscanf API */
3109 int example_fwscanf(void)
3115 /* open the file for writing*/
3116 fp = fopen("write.txt","w");
3119 wprintf(L"Error: File open
3123 /* Read a string from fp*/
3124 rval = fwscanf(fp, L"%s", wcs);
3126 /* Close the file that was opened */
3129 /* return the number of inputs that were read */
3137 /* Illustrates how to use vwscanf API */
3138 int example_vwscanf(va_list arg)
3142 /* Read a string from standard input */
3143 rval = vwscanf(L"%s", arg);
3145 /* return the number of inputs that were read */
3153 /* Illustrates how to use vswscanf API */
3154 int example_vswscanf(va_list arg)
3157 wchar_t bufptr = L"abc";
3159 /* Read a string from bufptr */
3160 rval = vswscanf(bufptr, L"%s", arg);
3162 /* return the number of inputs that were read */
3170 /* Illustrates how to use vfwscanf API */
3171 int example_vfwscanf(va_list arg)
3176 /* open the file for writing*/
3177 fp = fopen("write.txt","w");
3180 wprintf(L"Error: File open
3185 rval = vfwscanf(fp, L"%s", arg);
3187 /* Close the file that was opened */
3190 /* return the number of inputs that were read */
3199 /* Illustrates how to use wscanf API */
3200 int example_wscanf(void)
3204 /* Display a message to the user to input an integer */
3205 wprintf(L"Enter an integer : ");
3206 /* Read an integer from the standard input */
3207 rval = wscanf(L"%d", &input;);
3209 /* return the number of inputs that were read */
3217 /* Illustrates how to use swscanf API */
3218 int example_swscanf(void)
3222 wchar_t *bufptr = L"abcdefg";
3223 /* Read a string from the buffer bufptr*/
3224 rval = swscanf(bufptr, L"%s", wcs);
3226 /* The string that was read into wcs is printed */
3229 /* return the number of inputs that were read */
3237 /* Illustrates how to use fwscanf API */
3238 int example_fwscanf(void)
3244 /* open the file for writing*/
3245 fp = fopen("write.txt","w");
3248 wprintf(L"Error: File open
3252 /* Read a string from fp*/
3253 rval = fwscanf(fp, L"%s", wcs);
3255 /* Close the file that was opened */
3258 /* return the number of inputs that were read */
3266 /* Illustrates how to use vwscanf API */
3267 int example_vwscanf(va_list arg)
3271 /* Read a string from standard input */
3272 rval = vwscanf(L"%s", arg);
3274 /* return the number of inputs that were read */
3282 /* Illustrates how to use vswscanf API */
3283 int example_vswscanf(va_list arg)
3286 wchar_t bufptr = L"abc";
3288 /* Read a string from bufptr */
3289 rval = vswscanf(bufptr, L"%s", arg);
3291 /* return the number of inputs that were read */
3299 /* Illustrates how to use vfwscanf API */
3300 int example_vfwscanf(va_list arg)
3305 /* open the file for writing*/
3306 fp = fopen("write.txt","w");
3309 wprintf(L"Error: File open
3314 rval = vfwscanf(fp, L"%s", arg);
3316 /* Close the file that was opened */
3319 /* return the number of inputs that were read */
3327 Long double length modifiers are not supported.
3340 In addition to the bugs documented in scanf , wscanf does not support the "A-Z"
3341 notation for specifying character ranges with the character
3342 class conversion (' \%[ ').
3347 @externallyDefinedApi
3352 /** @fn wcstoq(const wchar_t * nptr, wchar_t ** endptr, int base)
3357 Refer to wcstol() for the documentation
3366 @externallyDefinedApi
3371 /** @fn wcstouq(const wchar_t * nptr, wchar_t ** endptr, int base)
3376 Refer to wcstol() for the documentation
3385 @externallyDefinedApi
3390 /** @fn wcswcs(const wchar_t *s, const wchar_t *find)
3394 The wcswcs() function locates the first occurrence of the wide-character
3395 string pointed by s (excluding the terminating '\\0' character) in the wide-character
3396 string pointed by find.
3401 /* Illustrates how to use wcswcs API */
3402 int example_wcswcs()
3404 /* source wide character string */
3405 wchar_t *buf[20] = { L"fkhsdf%%38",L"rtti123123", };
3406 wchar_t *str = wcswcs(buf[0],L"\0");
3407 wchar_t *str1 = wcswcs(buf[1],L"\0");
3408 if(wcscmp(str,buf[0]))
3410 if(wcscmp(str1,buf[1]))
3416 @return The wcswcs() on success returns a pointer to the located wide-character string and returns
3417 a NULL pointer if the wide-charcter string was not found. If find is a wide-character string with length as zero, the function returns s.
3425 @externallyDefinedApi
3430 /** @fn getwc(FILE *stream)
3433 Refer to fgetwc() for the documentation
3446 @externallyDefinedApi
3451 /** @fn getwchar(void);
3454 Refer to fgetwc() for the documentation
3467 @externallyDefinedApi
3472 /** @fn putwc(wchar_t wc, FILE *stream)
3476 Refer to fputwc() for the documentation
3487 @externallyDefinedApi
3492 /** @fn putwchar(wchar_t wc)
3495 Refer to fputwc() for the documentation
3506 @externallyDefinedApi
3511 /** @fn vfwscanf(FILE * stream, const wchar_t * format, va_list ap)
3516 Refer to wscanf() for the documentation
3530 @externallyDefinedApi
3535 /** @fn vswscanf(const wchar_t * str, const wchar_t *fmt, va_list ap)
3540 Refer to wscanf() for the documentation
3554 @externallyDefinedApi
3559 /** @fn vwscanf(const wchar_t *fmt, va_list ap)
3563 Refer to wscanf() for the documentation
3577 @externallyDefinedApi
3582 /** @fn wcstof(const wchar_t * nptr, wchar_t ** endptr)
3586 Note: This description also covers the following functions -
3591 The wcstof , wcstod and wcstold functions are the wide-character versions of the strtof , strtod and strtold functions.
3592 Refer to strtod() for details.
3597 /* Illustrates how to use wcstof API */
3598 int example_wcstof()
3601 wchar_t wcs1[21] = L" 1.23abcd";
3602 wchar_t wcs2[5]=L"abcd";
3606 /* convert wide-char string to float */
3607 d = wcstof(wcs1, &eptr;);
3609 /* compare the result */
3610 if((d == 1.23F) && !(wcscmp (eptr, wcs2)))
3619 /* Illustrates how to use wcstold API */
3620 int example_wcstold()
3623 wchar_t wcs1[21] = L" 1.23abcd";
3624 wchar_t wcs2[5]=L"abcd";
3628 /* convert wide-char string to double */
3629 d = wcstod(wcs1, &eptr;);
3631 /* compare the result */
3632 if((d == 1.23) && !(wcscmp (eptr, wcs2)))
3641 /* Illustrates how to use wcstold API */
3642 int example_wcstold()
3645 wchar_t wcs1[21] = L" 1.23abcd";
3646 wchar_t wcs2[5]=L"abcd";
3650 /* convert wide-char string to long double */
3651 d = wcstold(wcs1, &eptr;);
3653 /* compare the result *
3654 if((d == 1.23) && !(wcscmp (eptr, wcs2)))
3668 @externallyDefinedApi
3673 /** @fn wcstold(const wchar_t * nptr, wchar_t ** endptr)
3677 Refer to wcstof() for the documentation
3686 @externallyDefinedApi
3691 /** @fn wcstoll(const wchar_t * nptr, wchar_t ** endptr, int base)
3696 Refer to wcstol() for the documentation
3705 @externallyDefinedApi
3710 /** @fn wcstoull(const wchar_t * nptr, wchar_t ** endptr, int base)
3715 Refer to wcstol() for the documentation
3724 @externallyDefinedApi
3729 /** @fn wcswidth(const wchar_t *pwcs, size_t n)
3732 @return The wcswidth function returns 0 if pwcs is an empty string (L""), -1 if a non-printing wide character is
3733 encountered or the number of column positions occupied otherwise.
3735 The wcswidth function determines the number of column positions required for the first n characters of pwcs ,
3736 or until a null wide character (L'\\0') is encountered.
3738 The behavior of the wcswdith is affected by LC_CTYPE category of the current locale.
3743 /* Illustrates how to use wcswidth API */
3744 int example_wcswidth()
3746 /* wide character string for which width has to */
3748 wchar_t *ws1 = L"test case";
3750 /* compute the width of the ws1 */
3751 retval = wcswidth(ws1,50);
3752 /* return the result */
3760 The current implementation of wcswidth is dependent upon locale support in Symbian OS.
3769 @externallyDefinedApi
3774 /** @fn wcwidth(wchar_t wc)
3776 @return The wcwidth function returns 0 if the wc argument is a null wide character (L'\\0'), -1 if wc is not printable or the number of column positions the character occupies
3779 The wcwidth function determines the number of column positions required to
3780 display the wide character wc .
3782 The behavior of the wcwdith is affected by LC_CTYPE category of the current locale.
3787 /* Illustrates how to use wcwidth API */
3788 int example_wcwidth()
3790 /* wide character for which width has to be determined */
3793 /* determine the width of wc */
3794 retval = wcwidth(wc);
3795 /* return the determined width */
3803 This code fragment reads text from standard input and
3804 breaks lines that are more than 20 column positions wide,
3805 similar to the fold utility:
3810 while ((ch = getwchar()) != WEOF) {
3812 if (w > 0 && column + w >= 20) {
3827 The current implementation of wcwidth is dependent upon the locale support of Symbian OS.
3836 @externallyDefinedApi
3841 /** @fn mbsnrtowcs(wchar_t * dst, const char ** src, size_t nms, size_t len, mbstate_t * ps)
3848 Refer to mbsrtowcs() for the documentation
3858 @externallyDefinedApi
3863 /** @fn wcsnrtombs(char * dst, const wchar_t ** src, size_t nwc, size_t len, mbstate_t * ps)
3870 Refer to wcsrtombs() for the documentation
3880 @externallyDefinedApi
3885 /** @fn wcpcpy(wchar_t *dst , const wchar_t *src)
3888 @return The wcpcpy() function returns a pointer to the end of the wide-character
3889 string dest , that is the return pointer points to the terminating '\\0'.
3893 The wcpcpy() function
3894 copies the wide-character string src to dst (including the terminating '\\0'
3903 /* Illustrates how to use wcpcpy API */
3904 int example_wcpcpy()
3906 /* input string for which length to be found */
3907 wchar_t *src = L"testcase";
3908 wchar_t *dest = NULL;
3909 wchar_t *destEndPtr = NULL;
3911 /* allocate memory for the destination string */
3912 dest = (wchar_t *)malloc((wcslen(src)+1)*sizeof(wchar_t));
3914 /* perform the operation */
3916 destEndPtr = (wchar_t *)wcpcpy(dest,src);
3919 if(!wcscmp(dest,src))
3936 @externallyDefinedApi
3941 /** @fn wcpncpy(wchar_t *dst , const wchar_t *src, size_t n)
3945 @return The wcpncpy() function returns a pointer to the wide character one past
3946 the last non-null wide character written.
3948 The wcpncpy() function copies at most n wide characters from the wide-character string src , including the terminating L'\\0' character, to dst . Exactly n wide characters are written at dst . If the length wcslen(src) is less than n , the remaining wide characters in the array dst are filled with L'\\0'
3949 characters. If the length wcslen(src) is greater than or equal to n , the string dst will not be L'\\0' terminated.
3955 /* Illustrates how to use wcpncpy API */
3956 int example_wcpncpy(void)
3958 /* input string for which length to be found */
3959 wchar_t *src = L"testcase";
3960 wchar_t *dest = NULL;
3961 wchar_t *destEndPtr = NULL;
3963 /* allocate memory for the destination string */
3964 dest = (wchar_t *)malloc((wcslen(src)+1)*sizeof(wchar_t));
3966 /* perform the operation */
3968 destEndPtr = (wchar_t *)wcpncpy(dest,src,wcslen(src)+1);
3971 /* checking for error */
3972 if(!wcscmp(dest,src))
3974 wprintf(L"wcpncpy succeeded
3981 wprintf(L"wcpncpy failed!!
3995 @externallyDefinedApi
4000 /** @fn wcscasecmp(const wchar_t *s1, const wchar_t *s2)
4003 @return The wcscasecmp() returns an integer greater than, equal to, or less than
4004 0, according as s1 is lexicographically greater than, equal to, or less than s2 after translation of each corresponding character to lower-case. The
4005 strings themselves are not modified.
4007 The wcscasecmp() function
4008 compares the null-terminated wide-character strings s1 and s2 .
4013 /* Illustrates how to use wcscasecmp API */
4014 int example_wcscasecmp(void)
4016 /* input strings which needs to be compared */
4017 wchar_t *ws1=L"testcasecmp";
4018 wchar_t *ws2=L"TESTCASECMP";
4020 /* function call to compare the two strings which */
4021 /* differ in case */
4022 int retval = wcscasecmp(ws1,ws2);
4023 /* returns 0 if they are equal or > 1 */
4024 /* if first string is greater than second string else -1 */
4035 @externallyDefinedApi
4040 /** @fn wcsdup(const wchar_t *srcwcs)
4042 @return The wcsdup function returns a pointer to the new wide-character string, or NULL if sufficient memory was not available.
4044 The wcsdup() function allocates sufficient memory for a
4045 copy of the wide-string srcwcs, does the copy,
4046 and returns a pointer to it. The pointer may
4047 subsequently be used as an argument to the function free .
4049 If insufficient memory is available, NULL is returned and errno is set to
4055 /* Illustrates how to use wcsdup API */
4056 int example_wcsdup(void)
4058 /* input string for which length has to be found */
4059 wchar_t *srcws=L"testwcsdup";
4060 wchar_t *destws = NULL;
4062 /* invoke the API wcsdup to duplicate the string */
4063 destws = wcsdup(srcws);
4064 /* return no error if src str and dest str are equal else return an error */
4065 if(!(wcscmp(srcws,destws)))
4084 @externallyDefinedApi
4089 /** @fn wcsncasecmp(const wchar_t *s1, const wchar_t *s2, size_t n)
4093 @return The wcsncasecmp() returns an integer greater than, equal to, or less than 0,
4094 according as s1 is lexicographically greater than, equal to, or less than s2 after translation of each corresponding character to lower-case.
4095 The strings themselves are not modified.
4097 The wcsncasecmp() function compares atmost n wide-characters from the null-terminated wide-character strings s1 and s2 .
4102 /* Illustrates how to use wcsncasecmp API */
4103 int example_wcsncasecmp()
4105 /* input strings which need to be compared */
4106 wchar_t *ws1=L"testcasecmp";
4107 wchar_t *ws2=L"TESTCASECMP";
4109 /* function call to compare the two strings which */
4110 /* differ in case */
4111 int retval = wcsncasecmp(ws1,ws2,11);
4112 /* returns 0 if they are equal except the case or >1 */
4113 /* if first string is greater than second string else -1 */
4124 @externallyDefinedApi
4129 /** @fn wcsnlen(const wchar_t *s, size_t maxlen)
4133 The wcsnlen() function computes the length of the wide-character string s not including the terminating NUL character. It looks at only
4134 first maxlen wide-characters in s and never beyond s+maxlen.
4139 /* Illustrates how to use wcsnlen API */
4140 size_t example_wcsnlen()
4142 /* input string for which length to be found */
4143 wchar_t *ws=L"testwcsnlen";
4145 /* find the length of the wide char string by */
4146 /* calling wcsnlen */
4147 size_t retval = wcsnlen(ws,14);
4148 /* return the number of wide chars in the string */
4149 /* if retval is less than 14 Else return 14 as the */
4150 /* length of the string */
4155 @return The wcsnlen() returns the number of wide-characters that precede the terminating
4156 NUL character if it is less than maxlen or maxlen if there is a terminating NUL character among maxlen characters pointed by s.
4164 @externallyDefinedApi
4169 /** @fn wrealpath(const wchar_t *path, wchar_t *resolved)
4172 @return The wrealpath function returns resolved path on success.
4173 If an error occurs, wrealpath returns NULL, and resolved path contains the path which caused the problem.
4176 The wrealpath function resolves all extra "/"
4177 characters and references to /./ and /../ in path, and copies the resulting absolute path into
4178 the memory referenced by resolved path. The resolved path argument must refer to a buffer capable of storing at least PATH_MAX characters.
4180 The wrealpath function will resolve both absolute and relative paths
4181 and return the absolute path corresponding to path. All but the last component of path must exist when wrealpath is called.
4189 #include<stdio.h> //printf
4190 #include<sys/stat.h> //S_IWUSR
4191 #include<sys/syslimits.h> //PATH_MAX
4192 #include<unistd.h> //chdir
4197 wchar_t resolvepath[PATH_MAX];
4199 wchar_t *rpath = NULL;
4201 fp = wfopen(L"c:\xyz.txt", L"w");
4204 printf("wfopen failed!!");
4208 wmkdir(L"c:\tmdir", S_IWUSR);
4210 int c = wchdir(L"c:\");
4213 printf("wchdir failed!!");
4217 rpath = wrealpath(L".\tmdir\..\xyz.txt", resolvepath);
4218 printf("resolvepath: L%s
4226 wrmdir(L"c:\tmdir");
4227 wunlink(L"c:\xyz.txt");
4234 resolvepath: C:\xyz.txt
4246 /** @fn wrmdir(const wchar_t *_path)
4248 @return The wrmdir() function returns the value 0 if successful; otherwise the
4249 value -1 is returned and the global variable errno is set to indicate the
4252 The wrmdir system call
4253 removes a directory file
4254 whose name is given by _path. The directory must not have any entries other
4260 /* Detailed description: This test code demonstrates usage of wrmdir systemcall, it removes directory
4261 * Example from the current working directory.
4263 * Preconditions: Expects empty directoy "Example" in current working directory.
4268 if(wrmdir(L"Example") < 0 )
4270 printf("wrmdir failed
4274 printf("Directory Example removed
4280 Directory Example removed
4288 @capability Deferred @ref RFs::RmDir(const TDesC16&)
4295 /** @fn wstat(const wchar_t *name, struct stat *st)
4298 @return Upon successful completion, the value 0 is returned; otherwise the
4299 value -1 is returned and the global variable errno is set to indicate the error.
4302 The wstat system call obtains information about the file pointed to by name. Read, write or execute
4303 permission of the named file is not required, but all directories
4304 listed in the path name leading to the file must be searchable.
4306 The sb argument is a pointer to a stat structure as defined by \#include \<sys/stat.h\> and into which information is
4307 placed concerning the file.
4309 The fields of struct stat
4310 related to the file system are as follows: st_dev The numeric ID of the device containing the file. st_ino The file's inode number. st_nlink The number of hard links to the file.
4312 The st_dev and st_ino fields together identify the file uniquely within the system.
4314 The time-related fields of struct stat
4315 are as follows: st_atime Time when file data last accessed.
4316 Changed by the .Xr utimes 2, read and readv system calls. st_mtime Time when file data last modified. st_ctime Time when file status was last changed (inode data modification). st_birthtime Time when the inode was created.
4318 If _POSIX_SOURCE is not defined, the time-related fields are defined as:
4320 #ifndef _POSIX_SOURCE
4321 #define st_atime st_atimespec.tv_sec
4322 #define st_mtime st_mtimespec.tv_sec
4323 #define st_ctime st_ctimespec.tv_sec
4327 The size-related fields of the struct stat
4328 are as follows: st_size The file size in bytes. st_blksize The optimal I/O block size for the file. st_blocks The actual number of blocks allocated for the file in 512-byte units.
4329 As short symbolic links are stored in the inode, this number may
4332 The access-related fields of struct stat
4333 are as follows: st_uid The user ID of the file's owner. st_gid The group ID of the file. st_mode Status of the file (see below).
4335 The status information word st_mode has the following bits:
4337 #define S_IFMT 0170000 // type of file
4338 #define S_IFIFO 0010000 // named pipe (fifo)
4339 #define S_IFCHR 0020000 // character special
4340 #define S_IFDIR 0040000 // directory
4341 #define S_IFBLK 0060000 // block special
4342 #define S_IFREG 0100000 // regular
4343 #define S_IFLNK 0120000 // symbolic link
4344 #define S_IFSOCK 0140000 // socket
4345 #define S_IFWHT 0160000 // whiteout
4346 #define S_ISUID 0004000 // set user id on execution
4347 #define S_ISGID 0002000 // set group id on execution
4348 #define S_ISVTX 0001000 // save swapped text even after use
4349 #define S_IRUSR 0000400 // read permission, owner
4350 #define S_IWUSR 0000200 // write permission, owner
4351 #define S_IXUSR 0000100 // execute/search permission, owner
4355 For a list of access modes, see #include <sys/stat.h> The following macros are available
4356 to test whether a st_mode value passed in the m argument corresponds to a file of the specified type:
4357 S_ISBLK (m); Test for a block special file.
4358 S_ISCHR (m); Test for a character special file.
4359 S_ISDIR (m); Test for a directory.
4360 S_ISFIFO (m); Test for a pipe or FIFO special file.
4361 S_ISLNK (m); Test for a symbolic link.
4363 NOTE: Inode structure is not supported by Symbian OS and hence link count updation is not possible.
4364 Check for symbolic link would always fail because of this reason.
4366 S_ISREG (m); Test for a regular file.
4367 S_ISSOCK (m); Test for a socket.
4368 S_ISWHT (m); Test for a whiteout.
4371 The macros evaluate to a non-zero value if the test is true or to the value
4372 0 if the test is false.
4375 st_dev The numeric ID of the device containing the file.
4376 st_ino The file's inode number.
4378 The number of hard links to the file.
4382 st_atime Time when file data last accessed.
4383 Changed by the .Xr utimes 2, read and readv system calls.
4384 st_mtime Time when file data last modified.
4385 st_ctime Time when file status was last changed (inode data modification).
4387 Time when the inode was created.
4391 st_size The file size in bytes.
4393 The optimal I/O block size for the file.
4394 st_blocks The actual number of blocks allocated for the file in 512-byte units.
4395 As short symbolic links are stored in the inode, this number may
4400 st_uid The user ID of the file's owner.
4401 st_gid The group ID of the file.
4403 Status of the file (see below).
4407 Test for a block special file.
4408 Test for a character special file.
4409 Test for a directory.
4410 Test for a pipe or FIFO special file.
4411 Test for a symbolic link. NOTE: Inode structure is not supported by Symbian OS and hence link count updation is not possible.
4412 Check for symbolic link would always fail because of this reason.
4413 Test for a regular file.
4415 Test for a whiteout.
4422 /* Detailed description: Sample usage of wstat system call
4423 * Preconditions: Example.txt file should be present in working directory
4427 #include <sys/types.h>
4428 #include <sys/stat.h>
4433 if(wstat(L"Example.txt" , &buf;) < 0 )
4435 printf("Failed to wstat Example.txt
4439 printf("wstat system call succeded
4447 wstat system call succeded
4456 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
4463 /** @fn wstat64(const wchar_t *name, struct stat64 *st)
4466 @return Upon successful completion, the value 0 is returned; otherwise the
4467 value -1 is returned and the global variable errno is set to indicate the error.
4469 The wstat64() function is a 64-bit version of wstat.
4477 /** @fn wsystem(const wchar_t *cmd)
4479 @return The wsystem function
4480 returns the exit status of the child process as returned by
4481 process' exit reason
4482 or -1 if an error occurred when spawning a new process.
4484 The wsystem function
4485 spawns another process with the argument cmd. The calling process waits for the child process
4486 to finish executing.
4488 If cmd is a NULL pointer, wsystem will return non-zero to indicate that wsystem is suporrted
4489 and zero if it is not supported.
4496 #include <stdio.h> //printf
4503 printf( "Calling wsystem()...
4506 /* helloworld.exe is an executable that just prints
4507 * "Hello world!" and it should be created before
4508 * executing this example code.
4510 retVal = wsystem(L"c:\sys\bin\helloworld.exe");
4512 /* Print the return value of wsystem() */
4513 printf( "wsystem() returned: %d", retVal );
4521 Calling wsystem()...
4522 wsystem() returned: -1
4536 /** @fn wunlink(const wchar_t *_path)
4538 @return Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno set to indicate the error.
4540 The wunlink system call removes the link named by _path from its file system.
4542 Symbian OS simulates links so there is no reference count and files are unaware
4543 of links. Calling unlink on a file will always close the file, regardless of
4544 whether there is another link.
4546 The _path argument may not be a directory.
4551 * Detailed description: Example to wunlink a link file
4552 * Precondition: A file by name "Link" should exist in
4559 if(wunlink(L"C:\Link"))
4561 printf("wunlink on link file failed");
4563 printf("wunlink on link file succeeded");
4569 wunlink on link file succeeded.
4577 @capability Deferred @ref RFs::Att(const TDesC16&, unsigned&)
4578 @capability Deferred @ref RFs::SetAtt(const TDesC16&, unsigned, unsigned)
4579 @capability Deferred @ref RFs::Delete(const TDesC16&)
4587 /** @fn wpopen(const wchar_t* command, const wchar_t* wmode )
4590 @return The wpopen function returns NULL if the fork
4592 or if it cannot allocate memory. And returns stream pointer on success.
4594 The wpopen function opens a process by creating a pipe and invoking the shell (creating a process). Since a pipe is by definition unidirectional, The wmode argument may specify only reading or writing, not both; the resulting stream is correspondingly read-only ("r") or write-only "w". If type is anything other than this, then the behavior is undefined.
4596 The command argument is a pointer to a null-terminated wide character string containing a shell command line.
4597 This command is passed to /bin/sh using the - c flag; interpretation, if any, is performed by the shell.
4599 The return value from wpopen is a normal standard I/O stream in all respects
4600 save that it must be closed with pclose rather than fclose. Writing to such a stream
4601 writes to the standard input of the command;
4602 the command's standard output is the same as that of the process that called wpopen, unless this is altered by the command itself.
4603 Conversely, reading from a "wpopened"
4604 stream reads the command's standard output, and
4605 the command's standard input is the same as that of the process that called wpopen.
4607 Note that output wpopen streams are fully buffered by default.
4622 Since the standard input of a command opened for reading
4623 shares its seek offset with the process that called wpopen, if the original process has done a buffered read,
4624 the command's input position may not be as expected.
4625 Similarly, the output from a command opened for writing
4626 may become intermingled with that of the original process.
4627 The latter can be avoided by calling fflush before wpopen. Failure to execute the shell
4628 is indistinguishable from the shell's failure to execute command,
4629 or an immediate exit of the command.
4630 The only hint is an exit status of 127. The wpopen function always calls sh, never calls csh.
4639 /** @fn wopen(const wchar_t *file, int flags, ...)
4643 @return If successful, wopen returns a non-negative integer, termed a file descriptor.
4644 It returns -1 on failure, and sets errno to indicate the error.
4646 The wide character file-name specified by the wide character string file is opened
4647 for reading and/or writing as specified by the
4648 argument flags and the file descriptor returned to the calling process.
4649 The flags argument may indicate the file is to be
4650 created if it does not exist (by specifying the O_CREAT flag).
4651 In this case wopen requires a third argument mode_t mode ,
4652 and the file is created with mode mode as described in chmod and modified by the process' umask value (see umask
4656 The flags specified are formed by or 'ing the following values
4659 O_RDONLYopen for reading only
4660 O_WRONLYopen for writing only
4661 O_RDWRopen for reading and writing
4662 O_APPENDappend on each write
4663 O_CREATcreate file if it does not exist
4664 O_TRUNCtruncate size to 0
4665 O_EXCLerror if create and file exists
4668 Opening a file with O_APPEND set causes each write on the file
4669 to be appended to the end.
4670 If O_TRUNC is specified and the
4671 file exists, the file is truncated to zero length.
4672 If O_EXCL is set with O_CREAT and the file already
4673 exists, wopen returns an error.
4675 implement a simple exclusive access locking mechanism.
4676 If O_EXCL is set and the last component of the path is
4677 a symbolic link, wopen will fail even if the symbolic
4678 link points to a non-existent name.
4682 If successful, wopen returns a non-negative integer, termed a file descriptor.
4683 It returns -1 on failure.
4684 The file pointer used to mark the current position within the
4685 file is set to the beginning of the file.
4687 When a new file is created it is given the group of the directory
4690 The new descriptor is set to remain wopen across execve system calls; see close and fcntl .
4692 The system imposes a limit on the number of file descriptors
4693 wopen simultaneously by one process.
4694 The getdtablesize system call returns the current system limit.
4703 1) Mode values for group and others are ignored
4705 2) Execute bit and setuid on exec bit are ignored.
4707 3) The default working directory of a process is initalized to C: \p rivate \U ID
4708 (UID of the calling application) and any data written into this directory persists
4709 between phone resets.
4711 4) If the specified file is a symbolic link and the file it is pointing to
4712 is invalid, the symbolic link file will be automatically removed.
4714 5) A file in cannot be created with write-only permissions. Attempting to create
4715 a file with write-only permissions will result in a file with read-write permission.
4717 6) Creating a new file with the O_CREAT flag does not alter the time stamp
4718 of the parent directory.
4720 7) A file has only two time stamps: access and modification. Creation time
4721 stamp of the file is not supported and access time stamp is initially set equal
4722 to modification time stamp.
4727 /*This example creates a file in the current working directory and
4728 * opens it in read-write mode.
4730 #include <sys/types.h>
4731 #include <sys/stat.h>
4736 fd = wopen(L"Example.txt" , O_CREAT | O_EXCL , 0666) ;
4739 printf("Failed to create and wopen file in current working directory
4743 printf("File created and opened in current working directory
4751 File created and opened in current working directory
4757 @see getdtablesize()
4767 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
4773 /** @fn wopen64(const wchar_t *file, int flags, ...)
4777 @return If successful, wopen returns a non-negative integer, termed a file descriptor.
4778 It returns -1 on failure, and sets errno to indicate the error.
4780 The wopen64() function is a 64-bit version of wopen.
4789 /** @fn wfopen(const wchar_t *file, const wchar_t *mode)
4792 @return Upon successful completion wfopen returns a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.
4795 "r" Open text file for reading.
4796 The stream is positioned at the beginning of the file.
4797 "r+" Open for reading and writing.
4798 The stream is positioned at the beginning of the file.
4799 "w" Truncate to zero length or create text file for writing.
4800 The stream is positioned at the beginning of the file.
4801 "w+" Open for reading and writing.
4802 The file is created if it does not exist, otherwise it is truncated.
4803 The stream is positioned at the beginning of the file.
4804 "a" Open for writing.
4805 The file is created if it does not exist.
4806 The stream is positioned at the end of the file.
4807 Subsequent writes to the file will always end up at the then current
4808 end of file, irrespective of any intervening fseek or similar.
4809 "a+" Open for reading and writing.
4810 The file is created if it does not exist.
4811 The stream is positioned at the end of the file.
4812 Subsequent writes to the file will always end up at the then current
4813 end of file, irrespective of any intervening fseek or similar.
4818 The mode string can also include the letter "b" either as a third character or
4819 as a character between the characters in any of the two-character strings described above.
4820 This is strictly for compatibility with -isoC and has no effect; the "b" is ignored.
4822 Reads and writes may be intermixed on read/write streams in any order,
4823 and do not require an intermediate seek as in previous versions of stdio. This is not portable to other systems, however; ANSI C requires that
4824 a file positioning function intervene between output and input, unless
4825 an input operation encounters end-of-file.
4831 /* this program shows opening in write mode,write data and close */
4832 /* again open in append mode and write data */
4833 /* Check file c:\wfopen.txt */
4838 wchar_t* name = L"c:\wfopen.txt";
4839 if ((fp = wfopen (name, L"wb")) == NULL)
4841 printf("Error creating file");
4846 fprintf(fp, "This is the first line
4848 printf("Wrote to file
4853 if ((fp = wfopen (name, L"a")) == NULL)
4855 printf("Error opening file");
4858 printf("Opened file for appending
4860 fprintf(fp, "This is the second line
4863 printf("closed file, check output in c:\ wfopen.txt file
4875 Opened file for appending
4876 closed file, check output in c:\ wfopen.txt file
4882 [EINVAL] The mode argument to wfopen, was invalid.
4883 The wfopen, functions may also fail and set errno for any of the errors specified for the routine malloc. The wfopen function may also fail and set errno for any of the errors specified for the routine wopen.
4888 1) Mode values for group and others will be ignored for file creation,execute bit and setuid on exec bit on an file don't have any effect while file creation.
4889 Default working directory of a process is initialized to C:\private\UID (UID of the calling application) and any data written into this directory persists between phone resets.
4891 2) If the specified file is a symbolic link and the file it is pointing to
4892 is invalid the symbolic link file will be automatically removed.
4897 A file in cannot be created with write-only permission and attempting to
4898 create one will result in a file with read-write permission. Creating a new file
4899 with the O_CREAT flag does not alter the time stamp of its parent directory. The
4900 newly created entry has only two time stamps: access and modification. Creation
4901 time stamp is not supported and access time stamp is initially equal to modification
4902 time stamp. open, fclose and fflush.
4912 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
4918 /** @fn wfopen64(const wchar_t *file, const wchar_t *mode)
4921 @return Upon successful completion wfopen returns a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.
4923 The wfopen64() function is a 64-bit version of wfopen.
4933 /** @fn wrename(const wchar_t *oldpath, const wchar_t *newpath)
4936 @return The wrename() function returns the value 0 if successful; otherwise it returns
4937 -1 and sets the global variable errno to indicate the error.
4939 The wrename system call
4940 causes the link with the wide character name oldpath to be renamed with the wide character name newpath. If newpath exists, it is first removed.
4941 Both oldpath and newpath must be of the same type (that is, both directories or both
4942 non-directories), and must reside on the same file system.
4944 If the final component of from is a symbolic link the symbolic link is renamed, not the file or
4945 directory to which it points.
4947 If a file with a symbolic link pointing to it is renamed, then
4948 a subsequent open call on the symbolic link file would automatically remove the link file, i.e
4949 consider a symbolic file link.x pointing to a file abc.x. If the file abc.x is
4950 renamed to abcd.x then, a subsequent open call on link.x file would automatically remove link.x file.
4954 wrename fails if from and to are files and are in use (i.e. if any either of the files is open).
4956 Parent directory time stamps are uneffected.
4958 The new entry has only two time stamps: modification and access. The access
4959 time stamp is initially equal to modification time stamp.
4965 /* Detailed description : This sample code demonstrates usage of wrename system call.
4966 * Preconditions : Example.cfg file should be present in the current working directory.
4972 if(wrename(L"Example.txt" , L"Example2.txt") < 0 ) {
4973 printf("Failed to wrename Example.txt
4977 printf("wrename successful
4991 The wrename system call will fail and neither of the argument files will be affected if:
4992 [EINVAL] Invalid argument.
4993 [ENAMETOOLONG] A component of a path exceeded 255 characters.
4994 [ENOENT] The named file does not exist.
4995 [EACCES] Search permission is denied for a component of the path prefix.
4996 [EACCES] The from argument is a parent directory of to, or an attempt is made to wrename ‘.’ or ‘..’.
5005 @capability Deferred @ref RFs::Rename(const TDesC& anOldName,const TDesC& aNewName)
5006 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
5007 @capability Deferred @ref RFs::RmDir(const TDesC16&)
5008 @capability Deferred @ref RFs::SetAtt(const TDesC16&, unsigned, unsigned)
5009 @capability Deferred @ref RFs::Delete(const TDesC16&)
5017 /** @fn wchdir(const wchar_t *_path)
5019 @return Upon successful completion, the value 0 is returned; otherwise the
5020 value -1 is returned and the global variable errno is set to indicate the
5023 The _path argument points to the pathname of a directory which is a wide character string.
5024 The wchdir system call
5025 causes the named directory
5026 to become the current working directory, that is,
5027 the starting point for _path searches of pathnames not beginning with
5034 #include<wchar.h> /* wmkdir, wrmdir */
5035 #include <sys/stat.h> /* S_IRWXU */
5036 #include <stdio.h> /* printf */
5039 int ret_wmkdir = wmkdir(L"dirName", S_IRWXU); /* create directory */
5042 printf("error creating directory");
5047 int ret_wchdir = wchdir(L"dirName"); /* change directory */
5050 printf("error changing directory");
5055 printf("working directory changed");
5057 wrmdir(L"dirname"); /* remove directory */
5065 working directory changed
5072 @capability Deferred @ref RFs::Att(const TDesC16&, unsigned&)
5073 @capability Deferred @ref RFs::SetSessionPath(const TDesC16&)
5081 /** @fn wchmod(const wchar_t *_path, mode_t _mode)
5084 @return Upon successful completion, the value 0 is returned; otherwise the
5085 value -1 is returned and the global variable errno is set to indicate the
5088 The file permission bits of the wide character file-name specified by _path are changed to _mode. The wchmod system call verifies that the process owner (user) either owns the file specified by _path is the super-user.
5089 A mode is created from or’d permission bit masks defined in \#include \<sys/stat.h\>:
5092 #define S_IRWXU 0000700 // RWX mask for owner
5093 #define S_IRUSR 0000400 // R for owner
5094 #define S_IWUSR 0000200 // W for owner
5095 #define S_IXUSR 0000100 // X for owner
5096 #define S_IRWXG 0000070 // RWX mask for group
5097 #define S_IRGRP 0000040 // R for group
5098 #define S_IWGRP 0000020 // W for group
5099 #define S_IXGRP 0000010 // X for group
5100 #define S_IRWXO 0000007 // RWX mask for other
5101 #define S_IROTH 0000004 // R for other
5102 #define S_IWOTH 0000002 // W for other
5103 #define S_IXOTH 0000001 // X for other
5104 #define S_ISUID 0004000 // set user id on execution
5105 #define S_ISGID 0002000 // set group id on execution
5106 #ifndef __BSD_VISIBLE
5107 #define S_ISTXT 0001000 // sticky bit
5111 Note : sticky bit and setuid on exec bit are not supported, permission values for users is considered while premissions values for group and others are ignored(As there is no concept of group and others). An attempt to change file permission to write-only changes the file permission to read-write. Permissions for directory will be ignored.
5116 #include <wchar.h> /* wchmode, wfopen */
5117 #include <sys/stat.h> /* S_IWUSR */
5118 #include <stdio.h> /* printf */
5121 FILE * wfp = wfopen(L"fileName.txt", L"wb"); /* create file */
5124 fclose(wfp); /* close file */
5125 int ret = wchmod(L"fileName", S_IWUSR); /* change mode */
5128 printf("error changing mode");
5133 printf("mode changed");
5138 printf("error creating file");
5157 @capability Deferred @ref RFs::SetAtt(const TDesC16&, unsigned, unsigned)
5165 /** @fn wgetcwd(wchar_t *_buf, size_t _size)
5168 @return Upon successful completion, a pointer to the pathname is returned.
5169 Otherwise a NULL pointer is returned and the global variable errno is set to indicate the error.
5170 In addition, wgetcwd copies the error message associated with errno into the memory referenced by _buf.
5172 The wgetcwd function copies the absolute pathname of the current working directory
5173 into the memory referenced by _buf which is a wchar_t pointer
5174 and returns a pointer to _buf. The size argument is the _size, in bytes, of the array referenced by _buf.
5176 If _buf is NULL, space is allocated as indicated by size to store the pathname and the current working directory is
5177 returned as long as the _size bytes are sufficient to hold the working directory name.
5178 This space may later be free'd.
5180 This routine has traditionally been used by programs to save the
5181 name of a working directory for the purpose of returning to it.
5182 A much faster and less error-prone method of accomplishing this is to
5183 open the current directory ('.')
5184 and use the fchdir function to return.
5191 #define BUF_SIZE 100
5196 long size = BUF_SIZE;
5197 wchar_t *buf = NULL;
5198 wchar_t *ptr = NULL;
5200 c = wchdir("c:\"); /* change directory to c: */
5202 buf = (wchar_t *)malloc((size_t)size);
5204 if (buf != NULL && c == 0)
5206 ptr = wgetcwd(buf, (size_t)size); /* call wgetcwd to fetch the current directory */
5207 printf("wgetcwd returned: %s
5217 wgetcwd returned: c:\
5223 The wgetcwd function returns the default working directory as c:\\private\\XXXXXXXX (where XXXXXXXX is the UID of the process) as the
5224 default session path is initialised to c:\\private\\current_process'_UID in Symbian OS.
5240 /** @fn wmkdir(const wchar_t *_path, mode_t _mode)
5243 @return The wmkdir() function returns the value 0 if successful; otherwise the
5244 value -1 is returned and the global variable errno is set to indicate the
5247 The directory with the wide character name _path is created with the access permissions specified by _mode.
5253 Parent directory time stamps are not updated.
5257 #include <sys/stat.h>
5262 if(wmkdir(L"Example" , 0666) < 0 )
5264 printf("Directory creation failed
5268 printf("Directory Example created
5276 Directory Example created
5286 @capability Deferred @ref RFs::MkDir(const TDesC16&)
5294 /** @fn wclosedir(WDIR *wdp)
5296 @return The wclosedir function returns 0 on success and on failure -1 is returned and the global variable errno is set to indicate the error..
5300 The wclosedir function closes the named directory stream and frees the structure associated with the dirp pointer.
5306 /* Detailed description: This test code demonstrates usage of wclose system call.*
5307 * Preconditions: Expects Test directory to be present in current working directory.
5314 if(!(DirHandle = wopendir(L"Test") ) )
5316 printf("Failed to open directoy Test
5320 if(wclosedir(DirHandle) < 0 )
5322 printf("Close dir failed
5326 printf("Directory Test closed
5334 Directory Test closed
5351 /** @fn wreaddir(WDIR *wdp)
5353 @return The wreaddir function returns a pointer to a wdirent structure,
5354 or NULL if an error occurs or end-of-file is reached.
5358 The wreaddir function
5359 returns a wdirent pointer to the next directory entry.
5360 It returns NULL upon reaching the end of the directory or detecting an invalid wreaddir operation on the directory stream. The new position reverts to the one associated with the directory stream when the wtelldir operation was performed.
5364 Note: wreaddir operates on a static directory structure created by wopendir . Asynchronous operations on the directory itself will not
5365 be reflected in calls to wreaddir .
5371 /* Detailed description: Sample usage of wreaddir call
5372 * Preconditions: Example Directory should be present in current working directory and should contain atleast one file/directory.
5380 struct wdirent *Dir;
5381 dirName = wopendir(L"Example");
5382 if(dirName == NULL ) {
5383 printf("Failed to open directory
5387 if(!(Dir = wreaddir(dirName)) ) {
5388 printf("Read dir failed
5392 printf("Directory Example read
5401 Directory Example read
5429 /** @fn wreaddir64(WDIR *wdp)
5431 @return The wreaddir64 function returns a pointer to a wdirent64 structure,
5432 or NULL if an error occurs or end-of-file is reached.
5434 The wreaddir64() function is a 64-bit version of wreaddir.
5442 /** @fn wrewinddir(WDIR *wdp)
5444 @return The wrewinddir function returns no value.
5448 The wrewinddir function
5449 function resets the position of the named directory stream pointed by 'dirp' to the beginning of the directory.
5455 /* Detailed description: Sample usage of wreaddir call
5456 * Preconditions: Example Directory should be present in current working directory and should contain say 4 files/directories.
5465 struct wdirent *Dir;
5466 dirName = wopendir(L"Example");
5467 if(dirName == NULL ) {
5468 printf("Failed to open directory
5472 wseekdir(dirName, 3)
5473 if((offset = wtelldir(dirName))!= 3) {
5479 if((offset = wtelldir(dirName))!= 0) {
5513 /** @fn waccess(const wchar_t *fn, int flags)
5516 @return Upon successful completion, the value 0 is returned; otherwise the
5517 value -1 is returned and the global variable errno is set to indicate the
5520 The waccess system call checks the accessibility of the
5521 file named by the fn argument for the access permissions indicated by the flags argument.
5522 The value of flags is either the bitwise-inclusive OR of the access permissions to be
5523 checked (R_OK for read permission, W_OK for write permission, and X_OK for execute/search permission),
5524 or the existence test ( F_OK. )
5526 For additional information, see the File access Permission
5527 section of intro . X_OK, the file may not actually have execute permission bits set.
5528 Likewise for R_OK and W_OK.
5530 Note that as execute-bit for files is not supported waccess system call for X_OK is undefined.
5534 /* Detailed description: This sample code checks read-ok accessibility of file Example.c
5535 * Precondtions: Example.txt file should be present in working directory.
5541 if(waccess("Example.c" ,R_OK) < 0)
5543 printf("Read operation on the file is not permitted
5547 printf("Read operation permitted on Example.c file
5555 Read operation permitted on Example.c file
5563 @capability Deferred @ref RFs::Entry(const TDesC16&, TEntry&)
5571 /** @fn wcreat(const wchar_t *file, mode_t mode)
5574 @return wopen and wcreat return the new file descriptor, or -1 if an error occurred
5575 (in which case errno is set appropriately).
5577 This interface is made obsolete by: wopen
5580 is the same as: wopen(path, O_CREAT | O_TRUNC | O_WRONLY, mode);
5584 Creating a new file doesn't alter the time stamp of the parent directory.
5586 The newly created entry has two time stamps: access and modification. Both
5587 are initially the same.
5589 Symbian OS does not support a creation time stamp.
5596 * Detailed description : This test code demonstrates wcreat api usage, it creates a
5597 * in current working directory(if file exists then it is truncated.
5598 *Preconditions : None
5600 #include <sys/types.h>
5601 #include <sys/stat.h>
5607 fd = wcreat(L"Example.txt" , 0666);
5610 printf("File creation failed
5614 printf("Example.txt file created
5622 Example.txt file created
5634 /** @fn wcreat64(const wchar_t *file, mode_t mode)
5637 @return wcreat64() return the new file descriptor, or -1 if an error occurred
5638 (in which case errno is set appropriately).
5640 The wcreat64() function is a 64-bit version of wcreat.
5648 /** @fn wseekdir(WDIR *wdp, off_t index)
5652 Refer to wtelldir() for the documentation
5666 /** @fn wcsupr(wchar_t *wcs)
5669 The wcsupr() function
5670 converts each letter from the wide-character string wcs to upper-case.
5671 The conversion is determined by the LC_CTYPE category setting of the locale.
5672 Other characters are not affected. It returns a pointer to the altered string.
5673 Because the modification is done in place, the pointer returned is the same as
5674 the pointer passed as the input argument.
5676 @return The wcsupr() returns a pointer to the altered string, on successful conversion of wcs, else it returns NULL pointer.
5681 /* Illustrates how to use wcsupr API */
5682 int example_wcsupr(void)
5684 /* input string which needs to be converted to upper-case */
5685 wchar_t src[9]=L"testcase";
5687 /* expected result string */
5688 wchar_t *exp=L"TESTCASE";
5690 wchar_t *res = NULL;
5692 /* function call to convert the src to upper-case */
5694 /* compare res string with exp string, if they are equal then return 0, else return -1 */
5695 if( res != NULL && !wcscmp(res,exp))
5714 /** @fn wcslwr(wchar_t *wcs)
5717 The wcslwr() function
5718 converts each letter from the wide-character string wcs to lower-case.
5719 The conversion is determined by the LC_CTYPE category setting of the locale.
5720 Other characters are not affected. It returns a pointer to the altered string.
5721 Because the modification is done in place, the pointer returned is the same as
5722 the pointer passed as the input argument.
5724 @return The wcslwr() returns a pointer to the altered string, on successful conversion of wcs, else it returns NULL pointer.
5729 /* Illustrates how to use wcslwr API */
5730 int example_wcslwr(void)
5732 /* input string which needs to be converted to lower-case */
5733 wchar_t src[9]=L"TESTCASE";
5735 /* expected result string */
5736 wchar_t *exp=L"testcase";
5738 wchar_t *res = NULL;
5740 /* function call to convert the src to lower-case */
5742 /* compare res string with exp string, if they are equal then return 0, else return -1 */
5743 if( res != NULL && !wcscmp(res,exp))
5763 /** @fn wcsset(wchar_t *wcs, wchar_t wc)
5767 The wcsset() function sets all the characters of the wide-character string wcs to the wide-character specified by wc, except the terminating null character. It returns a pointer to the altered string, which is same
5768 as the source string passed to wcsset as it is modified in place.
5770 @return The wcsset() returns a pointer to the altered string, on success, else it returns NULL pointer.
5775 /* Illustrates how to use wcsset API */
5776 int example_wcsset(void)
5778 /* input string which needs to be set to the character specified by wc. */
5779 wchar_t wcs[9]=L"kohinoor";
5782 /* expected result string */
5783 wchar_t *exp=L"KKKKKKKK";
5785 wchar_t *res = NULL;
5787 /* function call to set all the chars in wcs to wc*/
5788 res = wcsset(wcs, wc);
5789 /* compare res string with exp string, if they are equal then return 0, else return -1 */
5790 if( res != NULL && !wcscmp(res,exp))
5807 /** @fn wcsnset(wchar_t *wcs, wchar_t wc, size_t maxSize)
5812 The wcsnset() function sets first maxSize characters of the wide-character string wcs to the wide-character specified by wc. If maxSize is greater than the length of wcs, then length of wcs is used instead of maxSize.
5813 It returns a pointer to the altered string, which is same
5814 as the source string passed to wcsnset as it is modified in place.
5816 @return The wcsnset() returns a pointer to the altered string, on success, else it returns NULL pointer.
5821 /* Illustrates how to use wcsnset API */
5822 int example_wcsnset(void)
5824 /* input string which needs to be set to the character specified by wc. */
5825 wchar_t wcs[9]=L"kohinoor";
5829 /* expected result string */
5830 wchar_t *exp=L"KKKinoor";
5832 wchar_t *res = NULL;
5834 /* function call to set first n chars in wcs to wc*/
5835 res = wcsnset(wcs, wc, n);
5836 /* compare res string with exp string, if they are equal then return 0, else return -1 */
5837 if( res != NULL && !wcscmp(res,exp))
5854 /** @fn wcsrev(wchar_t *wcs)
5857 The wcsrev() function reverses the order of the characters in the wide-character string wcs. The terminating null character remains in place.The arguments and return value of wcsrev are wide-character strings; It returns a pointer to the altered string.
5858 the pointer returned is the same as the pointer passed as the input argument.
5860 @return The wcsrev() returns a pointer to the reverted string, on success, else it returns NULL pointer.
5865 /* Illustrates how to use wcsrev API */
5866 int example_wcsrev(void)
5868 /* input string which needs to be reverted. */
5869 wchar_t src[9]=L"kohinoor";
5871 /* expected result string */
5872 wchar_t *exp=L"roonihok";
5874 wchar_t *res = NULL;
5876 /* function call to revert the src */
5878 /* compare res string with exp string, if they are equal then return 0, else return -1 */
5879 if( res != NULL && !wcscmp(res,exp))
5895 /** @fn wcsicmp(const wchar_t *wcs1, const wchar_t *wcs2)
5899 The wcsicmp() function
5900 compares the two null-terminated wide-character strings wcs1 and wcs2, by converting them into lower-case.
5901 It returns an integer value indicating the status of
5904 @return The wcsicmp() returns an integer greater than, equal to, or less than 0,
5905 according as wcs1 is lexicographically greater than, equal to, or less than wcs2 after translation of each corresponding character to lower-case.
5906 The strings themselves are not modified.
5911 /* Illustrates how to use wcsicmp API */
5912 int example_wcsicmp(void)
5914 /* input strings which needs to be compared */
5915 wchar_t *ws1=L"testcasecmp";
5916 wchar_t *ws2=L"TESTCASECMP";
5918 /* function call to compare the two strings which */
5919 /* differ in case */
5920 int retval = wcsicmp(ws1,ws2);
5921 /* returns 0 if they are equal or > 1 */
5922 /* if first string is greater than second string else -1 */
5937 /** @fn wstrdate(const wchar_t *datestr)
5940 The wstrdate() function gets the system date and converts it into wide-character
5941 string. This copies the current system date into the string pointed by datestr in the format dd/mm/yyyy, the datestr buffer must be atleast 11 bytes long. It returns a pointer to
5942 the datestr string. Because the modification is done in place, the pointer returned
5943 is the same as the pointer passed as the input argument.
5945 @return The wstrdate() returns a pointer to the date string on succes, otherwise
5946 it returns a NULL pointer and sets the errno accordingly.
5952 /* Illustrates how to use wstrdate API */
5953 int example_wstrdate(void)
5955 /* input string which is updated with the system date. */
5956 wchar_t datestr[20];
5958 wchar_t *res = NULL;
5960 /* function call to get the system date in wide-char format */
5961 res = wstrdate(datestr);
5962 if( !res && !datestr)
5964 printf(" res - %s and datestr - %s",res, datestr);
5977 res - 21/11/2006 and datestr - 21/11/2006
5983 The wstrdate function will fail if:
5984 [EFAULT] The supplied argument datestr is invalid.
5998 /** @fn wstrtime(const wchar_t *timestr)
6001 The wstrtime() function gets the system time and converts it into wide-character
6002 string. This copies the current system time into the string pointed by timestr in the format hh:mm:ss. The timestr buffer must be at least 9 bytes long. The function returns a pointer
6003 to the timestr string. Because the modification is done in place, the pointer
6004 returned is the same as the pointer passed as the input argument.
6006 @return The wstrtime() returns a pointer to the time string on success, otherwise
6007 it returns a NULL pointer and sets the errno accordingly.
6012 /* Illustrates how to use wstrtime API */
6013 int example_wstrtime(void)
6015 /* input string which is updated with the system time. */
6016 wchar_t timestr[20];
6018 wchar_t *res = NULL;
6020 /* function call to get the system time in wide-char format */
6021 res = wstrtime(timestr);
6022 if( !res && !timestr)
6024 printf(" res - %s and timestr - %s",res, timestr);
6037 res - 15:46:36 and timestr - 15:46:36
6053 /** @fn wfdopen(int fd ,const wchar_t * mode)
6056 @return Upon successful completion wfdopen returns a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.
6058 The wfdopen function
6059 associates a stream with the existing file descriptor, fd. The mode argument is used just as in the function wfopen .
6061 The mode of the stream must be compatible with the mode of the file descriptor.
6062 In other words the type specified by the stream must be allowed by the file access mode of the open file.
6063 When the stream is closed via fclose, fd is also closed.
6068 [EINVAL] The mode argument to wfdopen, was invalid.
6069 The function wfdopen may also fail and set errno for any of the errors specified for the routine wopen.
6076 All the limitations that apply to wfopen apply to wfdopen also.
6089 /** @fn wfreopen(const wchar_t * file, const wchar_t * mode,FILE *fp)
6093 @return Upon successful completion wfreopen returns a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.
6095 The wfreopen function
6096 opens the file whose name is the string pointed to by file and associates the stream pointed to by fp with it.
6097 The original stream (if it exists) is closed.
6098 The mode argument is used just as in the wfopen function.
6100 If the file argument is NULL, wfreopen attempts to re-open the file associated with fp with a new mode.
6101 The new mode must be compatible with the mode that the stream was originally
6102 opened with: Streams originally opened with mode "r"
6103 can only be reopened with that same mode. Streams originally opened with mode "a"
6104 can be reopened with the same mode, or mode "w." Streams originally opened with mode "w"
6105 can be reopened with the same mode, or mode "a." Streams originally opened with mode "r+," "w+,"
6107 can be reopened with any mode.
6109 The primary use of the wfreopen function
6110 is to change the file associated with a
6111 standard text stream (stderr, stdin, or stdout).
6119 /* wfreopen example: redirecting stdout */
6124 wfreopen (L"c:\myfile.txt",L"w",stdout);
6125 printf ("This sentence is redirected to a file.");
6133 Contents of myfile.txt:This sentence is redirected to a file.
6134 The output here is redirected from stdout to file myfile.txt
6140 All the limitations that apply to wfopen apply to wfreopen also.
6153 /** @fn wfreopen64(const wchar_t * file, const wchar_t * mode,FILE *fp)
6157 @return Upon successful completion wfreopen64 returns a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.
6159 The wfreopen64() function is a 64-bit version of wfreopen64.
6166 /** @fn getws(wchar_t * str)
6168 @return Upon successful completion, getws returns str. The getws function does not distinguish between end-of-file and error: Callers
6169 must use feof and ferror to determine which occurred.
6174 is equivalent to fgetws with an infinite size and a stream of stdin, except that the wide character newline(if any) is not stored in the string.
6175 It is the caller's responsibility to ensure that the input line,
6176 if any, is sufficiently short to fit in the string.
6184 /* Illustrates how to use getws API */
6187 FILE* stdop = freopen("c:\stdop","w+",stdout);
6188 FILE* stdip = freopen("c:\stdip","w+",stdin);
6189 FILE* stder = freopen("c:\stder","w+",stderr);
6190 wchar_t* buf = (wchar_t*)malloc(sizeof(wchar_t)*50);
6193 size_t size = fwrite("abdcef
6194 ", 1, 6, stdip); //write to stdin
6196 stdip = freopen("c:\stdip","r", stdin);
6197 getws(s); // read a line (from stdin)
6198 putws(s); //write to stdout
6200 stdop = freopen("c:\stdop","r", stdout);
6201 fgetws(buf,7,stdop); //read from stdout
6202 if(wcsncmp(s, buf,6))
6223 Security considerations:
6225 The getws function cannot be used securely. Because of its lack of bounds
6226 checking, and the inability for the calling program to determine reliably the
6227 length of the next incoming line, the use of this function enables malicious users
6228 to arbitrarily change a running program's functionality through a buffer
6229 overflow attack. It is strongly suggested that the fgetws function be used in all cases.
6244 /** @fn wremove(const wchar_t *file)
6246 @return Upon successful completion, wremove returns 0. Otherwise, it returns -1 is and sets the global
6247 variable errno to indicate the error.
6249 The wremove function removes the file or directory specified by the wide character name referred by file.
6251 If file specifies a directory, wremove (file); is the equivalent of wrmdir (file); Otherwise, it is the equivalent of wunlink (file);
6255 /* this program shows deleting a file using wremove */
6259 wchar_t* name = L"C:\input.txt";
6260 FILE *fp = wfopen(name, L"w+");
6263 printf ("fopen failed
6267 fprintf(fp,"hello world");
6271 fp=wfopen(name,L"r");
6274 printf ("file has been deleted already
6279 printf("wremove failed
6289 file has been deleted already
6302 /** @fn putws(wchar_t * str)
6304 @return The putws function
6305 returns 0 on success and -1 on error.
6307 The putws function writes the wide character string pointed to by str to the stdout stream.
6315 /* Illustrates how to use putws API */
6320 FILE* stdop = freopen("c:\stdop","w+",stdout);
6322 putws(L"Hello World"); //write to stdout
6326 op = freopen("c:\stdop","r",stdout);
6328 fgetws(buf, 12, op); //read from stdout
6334 if(!(wcsncmp(L"Hello World", buf, 11)))
6355 /** @fn wtelldir(const WDIR *wdp)
6358 Note: This description also covers the following functions -
6361 @return wtelldir function returns current location associated with the named directory stream on success or -1 on failure.
6363 The wtelldir function
6364 returns the current location associated with the named directory stream .
6365 Values returned by wtelldir are good only for the lifetime of the DIR pointer, dirp ,
6366 from which they are derived.
6367 If the directory is closed and then
6368 reopened, prior values returned by wtelldir will no longer be valid.
6370 The wseekdir function
6371 sets the position of the next wreaddir operation on the directory stream .
6372 The new position reverts to the one associated with the directory stream when the wtelldir operation was performed.
6382 #include<sys/types.h>
6385 //declare the variables for dir pointer and dir position.
6386 wchar_t *dirName =L"c: est_wseekdir";
6388 // Open the directory
6389 WDIR *dirp = wopendir (dirName);
6393 //read the directory.
6396 //get the dirp pointer position by calling telldir API.
6397 dirpos = wtelldir(dirp);
6398 //print the position of the dirp pointer.
6399 printf("dirp is pointing at position %ld.",dirpos);
6401 wseekdir(dirp , 0) ;
6403 dirpos = wtelldir(dirp);
6404 //print the position of the dirp pointer.
6405 printf("dirp is pointing at position %ld.",dirpos);
6414 Dirp is pointing at position 2.
6415 Dirp is pointing at position 1.
6430 /** @fn wopendir(const wchar_t *_wpath)
6432 @return The wopendir function returns a pointer to the directory stream or NULL if an error occurred.
6434 The wopendir function
6435 opens the directory given by the wide-character name _wpath, associates a directory stream with it and positions it at the first entry
6437 returns a pointer to be used to identify the directory stream in subsequent operations.
6438 The pointer NULL is returned if _wpath cannot be accessed, or if it cannot malloc enough memory to hold the whole thing.
6444 /* Detailed description: This test code demonstrates usage of wopendir system call, open directory wide name "test".
6445 * Preconditions: Expects "test" directory to be present in the current working directory.
6453 if(!(WDirHandle = wopendir(L"test") ) )
6455 printf("Failed to open directory test
6459 printf("Directory test opened
6461 wclosedir(WDirHandle);
6468 Directory test opened
6481 @externallyDefinedApi
6485 /** @fn wcslcat(wchar_t *s1, const wchar_t *s2, size_t n)
6490 Refer to wmemchr() for the documentation
6518 /** @fn wcslcpy(wchar_t *s1, const wchar_t *s2, size_t n)
6523 Refer to wmemchr() for the documentation
6551 /** @fn wasctime(const struct tm *tm)
6554 Refer to wctime() for the documentation
6566 /** @fn wctime(const time_t *clock)
6569 Note: This description also covers the following functions -
6572 @return The functions wasctime and wctime return a pointer to the resulting wide-character string.
6574 The function wctime takes a time value representing the time in seconds since the
6575 Epoch (00:00:00 UTC, January 1, 1970) as an argument. See time
6577 The function wctime adjusts the time value for the current time zone in the same
6578 manner as localtime and returns a pointer to a 26-wide character string of the
6579 form: Thu Nov 24 18:22:48 1986
6580 \\0 All the fields have constant width.
6582 The function wasctime converts the broken down time in the structure tm , pointed at by *tm , to the form shown in the example above.
6585 External declarations as well as the tm structure definition are in the #include <time.h> include file. The tm structure includes
6586 at least the following fields:
6588 int tm_sec;/* seconds (0 - 60) */
6589 int tm_min;/* minutes (0 - 59) */
6590 int tm_hour;/* hours (0 - 23) */
6591 int tm_mday;/* day of month (1 - 31) */
6592 int tm_mon;/* month of year (0 - 11) */
6593 int tm_year;/* year - 1900 */
6594 int tm_wday;/* day of week (Sunday = 0) */
6595 int tm_yday;/* day of year (0 - 365) */
6596 int tm_isdst;/* is summer time in effect? */
6597 char *tm_zone;/* abbreviation of timezone name */
6598 long tm_gmtoff;/* offset from UTC in seconds */
6602 field tm_isdst is non-zero if summer time is in effect.
6604 The field tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive
6605 values indicating east of the Prime Meridian.
6611 //Example usage of wasctime and wctime:
6618 t = time (NULL); //Get current time in seconds from Epoc
6619 //Fill tm struct w.r.t localtime using localtime
6620 timeptr = localtime (&t;);
6621 //Use this to convert it to a string indicating time w.r.t localtime
6622 wasc_time = wasctime (timeptr);
6623 wprintf (L"Time from wasctime w.r.t localtime : %s", wasc_time);
6624 wprintf(L"Time from wctime w.r.t localtime : %s0, wctime(&t;) );
6631 Time from wasctime w.r.t localtime : Thu Jun 22 10:42:27 2006
6632 Time from wctime w.r.t localtime : Thu Jun 22 10:42:27 2006
6644 These functions leave their result in an internal static object and return
6645 a pointer to that object.
6646 Subsequent calls to these
6647 functions will modify the same object. The C Standard provides no mechanism for a program to modify its current local
6648 timezone setting and the POSIX -standard method is not reentrant. (However, thread-safe implementations
6649 are provided in the POSIX threaded environment.) The tm_zone field of a returned tm structure points to a static array of characters which will also be overwritten
6650 by any subsequent calls (as well as by subsequent call to tzset )
6658 /** @fn wsetlocale(int category, const wchar_t *locale)
6661 @return Upon successful completion, wsetlocale returns the wide char string associated with the specified category for the requested locale. The wsetlocale function returns NULL and fails to change the locale
6662 if the given combination of category and locale make no sense.
6665 The wsetlocale function sets the C library's notion
6666 of natural language formatting style
6667 for particular sets of routines.
6668 Each such style is called a 'locale'
6669 and is invoked using an appropriate name passed as a wide char string.
6671 The wsetlocale function can recognise several categories of routines.
6672 The categories and the sets of routines recognised by wsetlocale are listed below:
6675 LC_ALL Set the entire locale generically.
6676 LC_COLLATE Set a locale for string collation routines. Currently locale setting does not have effect on
6678 LC_CTYPE This controls recognition of upper and lower case,
6679 alphabetic or non-alphabetic characters,
6680 and so on. Currently locale setting does not have effect on this category.
6682 Set a locale for message catalogs. Currently this category is not supported.
6684 Set a locale for formatting monetary values;
6685 this affects the localeconv function.
6686 LC_NUMERIC Set a locale for formatting numbers.
6687 This controls the formatting of decimal points
6688 in input and output of floating point numbers
6689 in functions such as printf and scanf, as well as values returned by localeconv.
6690 LC_TIME Set a locale for formatting dates and times using the strftime function.
6694 Only three locales are defined by default,
6695 the empty string which denotes the native environment, the C
6697 locales, which denote the C language environment.
6698 A locale argument of NULL causes wsetlocale to return the current locale.
6699 By default, C programs start in the C
6701 The only functions in the library that set the locale are wsetlocale and setlocale; the locale is never changed as a side effect of some other routine.
6709 //Set the locale to UK English
6710 wchar_t* locale = wsetlocale(LC_ALL,L"en_GB.ISO-8859-1");
6711 //Check whether locale setting is succesful or not
6714 wprintf(L"Locale setting is successful
6716 wprintf(L"Locale is set to %s
6721 wprintf(L"Locale setting failed
6730 Locale setting is successful
6731 Locale is set to en_GB.ISO-8859-1
6745 /** @fn wperror(const wchar_t *s)
6748 Note: This description also covers the following functions -
6751 @return The function wcserror returns the appropriate error description wide char string, or an unknown error message if the error code is unknown. The value of errno is not changed for a successful call, and is set to a nonzero value upon error.
6753 The functions wcserror and wperror look up the error message string corresponding to an
6756 The function wcserror function accepts an error number argument errnum (error number) and returns a pointer to the corresponding
6759 The function wperror finds the error message corresponding to the current
6760 value of the global variable errno and writes it, followed by a newline, to the
6761 standard error file descriptor.
6762 If the argument s is non- NULL and does not point to the null character,
6763 this wide char string is prepended to the message
6764 string and separated from it by
6765 a colon and space (": ");
6766 otherwise, only the error message string is printed.
6768 If the error number is not recognized, these functions return an error message
6769 string containing "Unknown error: "
6770 followed by the error number in decimal.
6771 The wcserror function returns EINVAL as a warning.
6772 Error numbers recognized by this implementation fall in
6773 the range 0 \<errnum \<sys_nerr .
6775 If insufficient storage is provided in strerrbuf (as specified in buflen )
6776 to contain the error string, wcserror returns ERANGE and strerrbuf will contain an error message that has been truncated and NUL terminated to fit the length specified by buflen .
6788 wchar_t *ptr = wcserror(ERANGE);
6789 wprintf(L"wcserror(ERANGE) = %s
6797 wcserror(ERANGE) = Numerical result out of range
6806 For unknown error numbers, the function wcserror will return its result in a static buffer which
6807 may be overwritten by subsequent calls. The return type for wcserror is missing a type-qualifier. The type-qualifier must be const wchar_t * .
6815 /** @fn wcserror(int num)
6818 Refer to wperror() for the documentation
6830 /** @fn wfindnext(intptr_t handle, struct _wfinddata_t * fileinfo)
6834 Refer to wfindfirst() for the documentation
6843 /** @fn wfindfirst(const wchar_t* filespec, struct _wfinddata_t* fileinfo)
6847 Note: This description also covers the following functions -
6848 wfindnext() findclose()
6850 @return If successful, wfindfirst return a unique search handle identifying the file or group
6851 of files matching the filespec specification. The handle can be used in a subsequent
6852 call to wfindnext or to findclose. Otherwise, wfindfirst returns -1 and sets
6853 errno accordingly. If successful, wfindnext returns 0. Otherwise, returns -1 and sets errno to a value indicating the nature of the failure. If successful, findclose returns 0. Otherwise, it returns -1 and sets errno to ENOENT
6857 [EINVAL] Invalid parameter: filespec or fileinfo was NULL. Or, the operating system returned an unexpected error.
6858 [ENOENT] File specification that could not be matched.
6860 The wfindfirst function provides information about the first instance of a file name that matches the file specified in the filespec argument. Any wildcard combination supported by the host operating system can be used in filespec. File information is returned in a _wfinddata_t structure, defined in wchar.h. The _wfinddata_t structure includes the following elements.
6863 unsigned attrib File attribute
6866 time_t time_create Time of file creation (-1L for Symbian OS)
6868 time_t time_access Time of the last file access (-1L for Symbian OS)
6870 time_t time_write Time of the last write to file
6872 size_t size Length of the file in bytes
6874 wchar_t name[260] Null-terminated name of matched file/directory, without the path
6878 This attribute is returned in the attrib field of the _wfinddata_t structure and can have the following values (defined in wchar.h).
6893 The wfindnext finds the next name, if any, that matches the filespec argument in a previous call to wfindfirst and then alters the fileinfo structure contents accordingly.
6895 The findclose closes the specified search handle and releases the associated resources.
6906 struct _wfinddata_t c_file;
6908 // Find .txt file in current directory
6909 if( (hFile = wfindfirst( L"*.txt", &c;_file )) == -1L )
6910 printf( "No *.txt files in current directory" );
6915 wprintf( L" File %d = %s ",i,c_file.name);
6917 } while( wfindnext( hFile, &c;_file ) == 0 );
6933 Does not support any attribute to find out the sub-directories
6934 (i.e., attribute _A_SUBDIR not supported).
6941 /** @fn findclose(intptr_t handle)
6944 Refer to wfindfirst() for the documentation
6953 /** @fn wcsnicmp(const wchar_t *wcs1, const wchar_t *wcs2, size_t n)
6958 The wcsnicmp() function
6959 compares the first n characters from two null-terminated wide-character strings wcs1 and wcs2, by converting them into lower-case.
6960 It returns an integer value indicating the status of
6963 @return The wcsnicmp() returns an integer greater than, equal to, or less than 0,
6964 according as wcs1 is lexicographically greater than, equal to, or less than wcs2 after translation of each corresponding character to lower-case.
6965 The strings themselves are not modified.
6970 /* Illustrates how to use wcsnicmp API */
6971 int example_wcsnicmp(void)
6973 /* input strings which needs to be compared */
6974 wchar_t *ws1=L"testcasecmp";
6975 wchar_t *ws2=L"TESTCASECMP";
6977 /* function call to compare the two strings which */
6978 /* differ in case */
6979 int retval = wcsnicmp(ws1,ws2,12);
6980 /* returns 0 if they are equal or > 1 */
6981 /* if first string is greater than second string else -1 */
6997 /** @fn wcsicoll(const wchar_t *wcs1, const wchar_t *wcs2)
7000 @return The wcsicoll function
7001 returns an integer greater than, equal to, or less than 0,
7002 if wcs1 is greater than, equal to, or less than wcs2. No return value is reserved to indicate errors;
7003 callers should set errno to 0 before calling wcsicoll .
7004 If it is non-zero upon return from wcsicoll ,
7005 an error has occurred.
7007 The wcsicoll function compares the null-terminated strings wcs1 and wcs2 according to the current locale collation order, by ignoring the case.
7009 locale, wcsicoll is equivalent to wcsicmp .
7014 /* Illustrates how to use wcsicoll API */
7015 int example_wcsicoll (void)
7017 /* compares the two strings */
7018 if( wcsicoll(L"abcdef",L"abcdeg") != L'f'-L'g')
7027 The current implementation of wcsicoll is not affected by the LC_CTYPE category of the current locale. It is equivalent to wcsicmp in this implementation.
7037 The current implementation of wcsicoll only works in single-byte LC_CTYPE locales, and falls back to using wcsicmp in locales with extended character sets.
7045 /** @fn wcsncoll(const wchar_t *wcs1, const wchar_t *wcs2, size_t n)
7049 @return The wcsncoll function
7050 returns an integer greater than, equal to, or less than 0,
7051 if wcs1 is greater than, equal to, or less than wcs2 . No return value is reserved to indicate errors;
7052 callers should set errno to 0 before calling wcsncoll .
7053 If it is non-zero upon return from wcsncoll ,
7054 an error has occurred.
7056 The wcsncoll function compares the first n chars from the two null-terminated strings wcs1 and wcs2 according to the current locale collation order.
7058 locale, wcsncoll is equivalent to wcscmp .
7063 /* Illustrates how to use wcsncoll API */
7064 int example_wcsncoll (void)
7066 /* compares the two strings */
7067 if( wcsncoll(L"abcdef",L"abcdeg",7) != L'f'-L'g')
7076 The current implementation of wcsncoll is not affected by the LC_CTYPE category of the current locale. It is equivalent to wcscoll in this implementation.
7088 The current implementation of wcsncoll only works in single-byte LC_CTYPE locales, and falls back to using wcscoll in locales with extended character sets.
7097 /** @fn wcsnicoll(const wchar_t *wcs1, const wchar_t *wcs2, size_t n)
7101 @return The wcsnicoll function
7102 returns an integer greater than, equal to, or less than 0,
7103 if wcs1 is greater than, equal to, or less than wcs2 . No return value is reserved to indicate errors;
7104 callers should set errno to 0 before calling wcsnicoll .
7105 If it is non-zero upon return from wcsnicoll ,
7106 an error has occurred.
7108 The wcsnicoll function compares the null-terminated strings wcs1 and wcs2 according to the current locale collation order.
7110 locale, wcsnicoll is equivalent to wcsncasecmp .
7115 /* Illustrates how to use wcsnicoll API */
7116 int example_wcsnicoll (void)
7118 /* compares the two strings */
7119 if( wcsnicoll(L"abcdef",L"abcdeg",7) != L'f'-L'g')
7128 The current implementation of wcsnicoll is not affected by the LC_CTYPE category of the current locale. It is equivalent to wcsncasecmp in this implementation.
7139 The current implementation of wcsnicoll only works in single-byte LC_CTYPE locales, and falls back to using wcsncoll in locales with extended character sets.
7147 /** @fn wtmpnam(wchar_t *s)
7149 @return The wtmpnam function returns a pointer to a file name on success and a NULL pointer on error.
7151 The wtmpnam function returns a pointer to a file name in the P_tmpdir directory which did not reference an existing file at some
7152 indeterminate point in the past. P_tmpdir is defined in the include file stdio.h . If the argument s is non-NULL, the file name is copied to the buffer it references. Otherwise, the
7153 file name is copied to a static buffer. In either case, wtmpnam returns a pointer to the file name.
7155 The buffer referenced by s is expected to be at least L_tmpnam bytes in length. L_tmpnam is defined in the include file stdio.h .
7157 The environment variable TMPDIR (if set), the argument tmpdir (if non-NULL), the directory P_tmpdir , and the directory /tmp are tried in that order as directories in which to store the
7164 #include<stdio.h> //wtmpnam
7165 #include<sys/stat.h> //S_IWUSR
7166 #include<errno.h> //errno
7170 //create a directory c:\system emp
7171 wmkdir(L"c:\system\temp", S_IWUSR);
7173 wchar_t wbuf[L_tmpnam];
7176 //call wtmpnam() to create a file
7177 wchar_t *rval = wtmpnam(wbuf);
7180 //open the file with the name returned by wtmpnam()
7181 FILE *fp = wfopen(buf, L"w");
7185 printf("fopen of file returned by wtmpnam() failed - errno %d ", errno);
7191 fwprintf(fp, L"%ls", L"check");
7195 fp = wfopen(buf, L"r");
7199 fwscanf(fp, L"%ls", rbuf);
7203 printf("read from file: %ls
7205 printf("argument buf: %ls
7207 printf("return value: %ls
7216 read from file: check
7217 argument buf: /System/temp/tmp.0.U9UPTx
7218 return value: /System/temp/tmp.0.U9UPTx
7233 /** @typedef typedef __mbstate_t mbstate_t
7235 An object type other than an array type that can hold the conversion state information necessary to convert between sequences of (possibly multibyte) characters and wide-characters.
7236 If a codeset is being used such that an mbstate_t needs to preserve more than 2 levels of reserved state, the results are unspecified.
7239 @externallyDefinedApi
7243 /** @typedef typedef __wint_t wint_t
7245 An integral type capable of storing any valid value of wchar_t, or WEOF.
7248 @externallyDefinedApi
7254 The minimum value representable by an object of type wchar_t.
7257 @externallyDefinedApi
7262 The maximum value representable by an object of type wchar_t.
7265 @externallyDefinedApi
7270 Constant expression of type wint_t that is returned by several WP functions to indicate end-of-file.
7273 @externallyDefinedApi
7276 /** @fn wpopen3 (const wchar_t* file, const wchar_t* cmd, wchar_t** env, int fids[3])
7282 Note:wpopen3 is a wide-character version of popen3()
7284 @return Upon successful completion, it returns pid of the child.
7290 /* Illustrates how to use wpopen3 API */
7295 int childid= wpopen3( NULL,NULL, NULL, fds);
7296 if (childid == -1 && errno == ENOENT)
7298 printf("wpopen success");