diff options
Diffstat (limited to 'lib/libc/locale/mbrtowc.3')
| -rw-r--r-- | lib/libc/locale/mbrtowc.3 | 96 |
1 files changed, 68 insertions, 28 deletions
diff --git a/lib/libc/locale/mbrtowc.3 b/lib/libc/locale/mbrtowc.3 index 10160d1..22b26cd 100644 --- a/lib/libc/locale/mbrtowc.3 +++ b/lib/libc/locale/mbrtowc.3 @@ -24,11 +24,13 @@ .\" .\" $FreeBSD$ .\" -.Dd April 8, 2004 +.Dd May 21, 2013 .Dt MBRTOWC 3 .Os .Sh NAME -.Nm mbrtowc +.Nm mbrtowc , +.Nm mbrtoc16 , +.Nm mbrtoc32 .Nd "convert a character to a wide-character code (restartable)" .Sh LIBRARY .Lb libc @@ -36,35 +38,51 @@ .In wchar.h .Ft size_t .Fo mbrtowc -.Fa "wchar_t * restrict pwc" "const char * restrict s" "size_t n" +.Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +.In uchar.h +.Ft size_t +.Fo mbrtoc16 +.Fa "char16_t * restrict pc" "const char * restrict s" "size_t n" +.Fa "mbstate_t * restrict ps" +.Fc +.Ft size_t +.Fo mbrtoc32 +.Fa "char32_t * restrict pc" "const char * restrict s" "size_t n" .Fa "mbstate_t * restrict ps" .Fc .Sh DESCRIPTION The -.Fn mbrtowc -function inspects at most +.Fn mbrtowc , +.Fn mbrtoc16 +and +.Fn mbrtoc32 +functions inspect at most .Fa n bytes pointed to by .Fa s to determine the number of bytes needed to complete the next multibyte character. If a character can be completed, and -.Fa pwc +.Fa pc is not .Dv NULL , the wide character which is represented by .Fa s is stored in the -.Vt wchar_t +.Vt wchar_t , +.Vt char16_t +or +.Vt char32_t it points to. .Pp If .Fa s is .Dv NULL , -.Fn mbrtowc -behaves as if -.Fa pwc +these functions behave as if +.Fa pc was .Dv NULL , .Fa s @@ -81,15 +99,24 @@ argument, is used to keep track of the shift state. If it is .Dv NULL , -.Fn mbrtowc -uses an internal, static +these functions use an internal, static .Vt mbstate_t object, which is initialized to the initial conversion state at program startup. +.Pp +As a single +.Vt char16_t +is not large enough to represent certain multibyte characters, the +.Fn mbrtoc16 +function may need to be invoked multiple times to convert a single +multibyte character sequence. .Sh RETURN VALUES The -.Fn mbrtowc -functions returns: +.Fn mbrtowc , +.Fn mbrtoc16 +and +.Fn mbrtoc32 +functions return: .Bl -tag -width indent .It 0 The next @@ -100,10 +127,13 @@ represent the null wide character .It >0 The next .Fa n -or fewer bytes -represent a valid character, -.Fn mbrtowc -returns the number of bytes used to complete the multibyte character. +or fewer bytes represent a valid character, these functions +return the number of bytes used to complete the multibyte character. +.It Po Vt size_t Pc Ns \-1 +An encoding error has occurred. +The next +.Fa n +or fewer bytes do not contribute to a valid multibyte character. .It Po Vt size_t Pc Ns \-2 The next .Fa n @@ -111,16 +141,23 @@ contribute to, but do not complete, a valid multibyte character sequence, and all .Fa n bytes have been processed. -.It Po Vt size_t Pc Ns \-1 -An encoding error has occurred. -The next -.Fa n -or fewer bytes do not contribute to a valid multibyte character. +.El +.Pp +The +.Fn mbrtoc16 +function also returns: +.Bl -tag -width indent +.It Po Vt size_t Pc Ns \-3 +The next character resulting from a previous call has been stored. +No bytes from the input have been consumed. .El .Sh ERRORS The -.Fn mbrtowc -function will fail if: +.Fn mbrtowc , +.Fn mbrtoc16 +and +.Fn mbrtoc32 +functions will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte sequence was detected. @@ -134,6 +171,9 @@ The conversion state is invalid. .Xr wcrtomb 3 .Sh STANDARDS The -.Fn mbrtowc -function conforms to -.St -isoC-99 . +.Fn mbrtowc , +.Fn mbrtoc16 +and +.Fn mbrtoc32 +functions conform to +.St -isoC-2011 . |
