diff options
Diffstat (limited to 'lib/libc/locale/mbtowc.3')
| -rw-r--r-- | lib/libc/locale/mbtowc.3 | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/lib/libc/locale/mbtowc.3 b/lib/libc/locale/mbtowc.3 new file mode 100644 index 00000000000..14f09e2e78f --- /dev/null +++ b/lib/libc/locale/mbtowc.3 @@ -0,0 +1,179 @@ +.\" $OpenBSD: mbtowc.3,v 1.1 2005/05/11 18:44:12 espie Exp $ +.\" $NetBSD: mbtowc.3,v 1.5 2003/09/08 17:54:31 wiz Exp $ +.\" +.\" Copyright (c)2002 Citrus Project, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd February 3, 2002 +.Dt MBTOWC 3 +.Os +.\" ---------------------------------------------------------------------- +.Sh NAME +.Nm mbtowc +.Nd converts a multibyte character to a wide character +.\" ---------------------------------------------------------------------- +.Sh SYNOPSIS +.Fd #include <stdlib.h> +.Ft int +.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" +.Sh DESCRIPTION +The +.Fn mbtowc +usually converts the multibyte character pointed to by +.Fa s +to a wide character, and stores it in the wchar_t object pointed to by +.Fa pwc +if +.Fa pwc +is non-null and +.Fa s +points to a valid character. +This function may inspect at most n bytes of the array beginning from +.Fa s . +.Pp +In state-dependent encodings, +.Fa s +may point to the special sequence bytes to change the shift-state. +Although such sequence bytes correspond to no individual +wide-character code, +.Fn mbtowc +changes its own state by the sequence bytes and treats them +as if they are a part of the subsequence multibyte character. +.Pp +Unlike +.Xr mbrtowc 3 , +the first +.Fa n +bytes pointed to by +.Fa s +need to form an entire multibyte character. +Otherwise, this function causes an error. +.Pp +Calling any other functions in +.Em libc +never change the internal +state of the +.Fn mbtowc , +except for calling +.Xr setlocale 3 +with the +.Dv LC_CTYPE +category changed to that of the current locale. +Such +.Xr setlocale 3 +calls cause the internal state of this function to be indeterminate. +.Pp +The behaviour of +.Fn mbtowc +is affected by the +.Dv LC_CTYPE +category of the current locale. +.Pp +These are the special cases: +.Bl -tag -width 012345678901 +.It s == NULL +.Fn mbtowc +initializes its own internal state to an initial state, and +determines whether the current encoding is state-dependent. +This function returns 0 if the encoding is state-independent, +otherwise non-zero. +In this case, +.Fa pwc +is completely ignored. +.It pwc == NULL +.Fn mbtowc +executes the conversion as if +.Fa pwc +is non-null, but a result of the conversion is discarded. +.It n == 0 +In this case, +the first +.Fa n +bytes of the array pointed to by +.Fa s +never form a complete character. +Thus, the +.Fn mbtowc +always fails. +.El +.\" ---------------------------------------------------------------------- +.Sh RETURN VALUES +Normally, +.Fn mbtowc +returns: +.Bl -tag -width 012345678901 +.It 0 +.Fa s +points to a null byte +.Pq Sq \e0 . +.It positive +Number of bytes for the valid multibyte character pointed to by +.Fa s . +There are no cases where the value returned is greater than +the value of the +.Dv MB_CUR_MAX +macro. +.It -1 +.Fa s +points to an invalid or an incomplete multibyte character. +The +.Fn mbtowc +also sets errno to indicate the error. +.El +.Pp +When +.Fa s +is equal to NULL, +.Fn mbtowc +returns: +.Bl -tag -width 0123456789 +.It 0 +The current encoding is state-independent. +.It non-zero +The current encoding is state-dependent. +.El +.\" ---------------------------------------------------------------------- +.Sh ERRORS +.Fn mbtowc +may cause an error in the following cases: +.Bl -tag -width Er +.It Bq Er EILSEQ +.Fa s +points to an invalid or incomplete multibyte character. +.El +.\" ---------------------------------------------------------------------- +.Sh SEE ALSO +.Xr mblen 3 , +.Xr mbrtowc 3 , +.Xr setlocale 3 +.\" ---------------------------------------------------------------------- +.Sh STANDARDS +The +.Fn mbtowc +function conforms to +.St -ansiC . +The restrict qualifier is added at +.\" .St -isoC99 . +ISO/IEC 9899/1999 +.Pq Dq ISO C99 . |