mbtowc.3 (1339B)
1 .TH MBTOWC 3 2 .SH NAME 3 mbtowc - convert a multibyte sequence to a wide character 4 .SH SYNOPSIS 5 #include <stdlib.h> 6 7 int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n) 8 .SH DESCRIPTION 9 When 10 .I s 11 is not a null pointer, 12 the 13 .BR mbtowc () 14 function examines up to 15 .I n 16 bytes starting at 17 .I s 18 to determine how many bytes form the next complete multibyte character, 19 including any required shift sequences. 20 If a complete, valid multibyte character is found, 21 the corresponding wide character value is computed and, 22 if 23 .I pwc 24 is not a null pointer, 25 stored in the object at 26 .IR pwc . 27 When the converted character is the null wide character, 28 the conversion state is reset to its initial value. 29 .SH RETURN VALUE 30 When 31 .I s 32 is a null pointer, 33 .BR mbtowc () 34 returns non-zero if the current encoding has state-dependent sequences, 35 or zero otherwise. 36 When 37 .I s 38 is not a null pointer, the function returns: 39 .TP 40 0 41 if 42 .I s 43 points to the null character; 44 .TP 45 positive 46 the number of bytes consumed to produce the wide character, 47 when the next 48 .I n 49 or fewer bytes form a valid multibyte character; 50 .TP 51 \-1 52 if the bytes do not form a valid multibyte character. 53 .PP 54 The return value never exceeds 55 .I n 56 or the value of 57 .IR MB_CUR_MAX . 58 .SH STANDARDS 59 ISO/IEC 9899:1999 Section 7.20.7.2 Paragraph 1,2,3,4,5 60 .SH SEE ALSO 61 .BR stdlib.h (3) 62 .BR wchar.h (3)