--- _SB/Libc/locale/FreeBSD/mbtowc.3 2004-11-25 11:38:18.000000000 -0800 +++ _SB/Libc/locale/FreeBSD/mbtowc.3.edit 2006-06-28 16:55:51.000000000 -0700 @@ -41,7 +41,8 @@ .Dt MBTOWC 3 .Os .Sh NAME -.Nm mbtowc +.Nm mbtowc , +.Nm mbtowc_l .Nd convert a character to a wide-character code .Sh LIBRARY .Lb libc @@ -49,30 +50,48 @@ .In stdlib.h .Ft int .Fo mbtowc -.Fa "wchar_t * restrict wcharp" "const char * restrict mbchar" -.Fa "size_t nbytes" +.Fa "wchar_t *restrict pwc" +.Fa "const char *restrict s" +.Fa "size_t n" +.Fc +.In stdlib.h +.In xlocale.h +.Ft int +.Fo mbtowc_l +.Fa "wchar_t *restrict pwc" +.Fa "const char *restrict s" +.Fa "size_t n" +.Fa "locale_t loc" .Fc .Sh DESCRIPTION The .Fn mbtowc function converts a multibyte character -.Fa mbchar -into a wide character according to the current conversion state, +.Fa s +into a wide character, according to the current conversion state, and stores the result in the object pointed to by -.Fa wcharp . +.Fa pwc . Up to -.Fa nbytes +.Fa n bytes are examined. .Pp A call with a null -.Fa mbchar +.Fa s pointer returns nonzero if the current encoding requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state. +.Pp +While the +.Fn mbtowc +function uses the current locale, the +.Fn mbtowc_l +function may be passed a locale directly. See +.Xr xlocale 3 +for more information. .Sh RETURN VALUES If -.Fa mbchar +.Fa s is .Dv NULL , the @@ -81,14 +100,14 @@ zero otherwise. .Pp Otherwise, if -.Fa mbchar +.Fa s is not a null pointer, .Fn mbtowc either returns 0 if -.Fa mbchar +.Fa s represents the null wide character, or returns the number of bytes processed in -.Fa mbchar , +.Fa s , or returns \-1 if no multibyte character could be recognized or converted. In this case, @@ -110,7 +129,8 @@ .Xr mbrtowc 3 , .Xr mbstowcs 3 , .Xr multibyte 3 , -.Xr wctomb 3 +.Xr wctomb 3 , +.Xr xlocale 3 .Sh STANDARDS The .Fn mbtowc