diff options
Diffstat (limited to 'man3/mbtowc.3')
| -rw-r--r-- | man3/mbtowc.3 | 31 |
1 files changed, 23 insertions, 8 deletions
diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 index 837edab2c3..1fd59bd579 100644 --- a/man3/mbtowc.3 +++ b/man3/mbtowc.3 @@ -23,7 +23,9 @@ mbtowc \- convert a multibyte sequence to a wide character .SH DESCRIPTION The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is not NULL. -In this case, the \fBmbtowc\fP() function inspects at most \fIn\fP +In this case, the +.BR mbtowc () +function inspects at most \fIn\fP bytes of the multibyte string starting at \fIs\fP, extracts the next complete multibyte character, converts it to a wide character and stores it at @@ -34,20 +36,25 @@ If \fIs\fP does not point to a '\\0' byte, it returns the number of bytes that were consumed from \fIs\fP, otherwise it returns 0. .PP If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte -character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP() +character, or if they contain an invalid multibyte sequence, +.BR mbtowc () returns \-1. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift sequences. .PP A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this -case the \fBmbtowc\fP() function behaves as above, excepts that it does not +case the +.BR mbtowc () +function behaves as above, excepts that it does not store the converted wide character in memory. .PP A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are ignored. -The \fBmbtowc\fP() function +The +.BR mbtowc () +function .\" The Dinkumware doc and the Single Unix specification say this, but .\" glibc doesn't implement this. resets the shift state, only known to this function, @@ -55,11 +62,15 @@ to the initial state, and returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "RETURN VALUE" -If \fIs\fP is not NULL, the \fBmbtowc\fP() function returns the number of +If \fIs\fP is not NULL, the +.BR mbtowc () +function returns the number of consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, or \-1 upon failure. .PP -If \fIs\fP is NULL, the \fBmbtowc\fP() function +If \fIs\fP is NULL, the +.BR mbtowc () +function returns non-zero if the encoding has non-trivial shift state, or zero if the encoding is stateless. .SH "CONFORMING TO" @@ -69,9 +80,13 @@ C99 .BR mbrtowc (3), .BR mbstowcs (3) .SH NOTES -The behaviour of \fBmbtowc\fP() depends on the LC_CTYPE category of the +The behaviour of +.BR mbtowc () +depends on the LC_CTYPE category of the current locale. .PP This function is not multi-thread safe. -The function \fBmbrtowc\fP(3) provides +The function +.BR mbrtowc (3) +provides a better interface to the same functionality. |