xref: /dragonfly/lib/libc/locale/mbtowc.3 (revision e1acdbad) 
1.\" $NetBSD: src/lib/libc/locale/mbtowc.3,v 1.6 2004/01/24 16:58:54 wiz Exp $
2.\" $DragonFly: src/lib/libc/locale/mbtowc.3,v 1.1 2005/03/12 00:18:01 joerg Exp $
3.\"
4.\" Copyright (c)2002 Citrus Project,
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd February 3, 2002
29.Dt MBTOWC 3
30.Os
31.\" ----------------------------------------------------------------------
32.Sh NAME
33.Nm mbtowc
34.Nd converts a multibyte character to a wide character
35.\" ----------------------------------------------------------------------
36.Sh LIBRARY
37.Lb libc
38.\" ----------------------------------------------------------------------
39.Sh SYNOPSIS
40.In stdlib.h
41.Ft int
42.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
43.Sh DESCRIPTION
44.Fn mbtowc
45usually converts the multibyte character pointed to by
46.Fa s
47to a wide character, and stores it in the wchar_t object pointed to by
48.Fa pwc
49if
50.Fa pwc
51is non-null and
52.Fa s
53points to a valid character.
54This function may inspect at most n bytes of the array beginning from
55.Fa s .
56.Pp
57In state-dependent encodings,
58.Fa s
59may point to the special sequence bytes to change the shift-state.
60Although such sequence bytes correspond to no individual
61wide-character code,
62.Fn mbtowc
63changes its own state by the sequence bytes and treats them
64as if they are a part of the subsequence multibyte character.
65.Pp
66Unlike
67.Xr mbrtowc 3 ,
68the first
69.Fa n
70bytes pointed to by
71.Fa s
72need to form an entire multibyte character.
73Otherwise, this function causes an error.
74.Pp
75Calling any other functions in
76.Lb libc
77never changes the internal state of
78.Fn mbtowc ,
79except for calling
80.Xr setlocale 3
81with changing the
82.Dv LC_CTYPE
83category of the current locale.
84Such
85.Xr setlocale 3
86call causes the internal state of this function to be indeterminate.
87.Pp
88The behaviour of
89.Fn mbtowc
90is affected by the
91.Dv LC_CTYPE
92category of the current locale.
93.Pp
94There are special cases:
95.Bl -tag -width 012345678901
96.It s == NULL
97.Fn mbtowc
98initializes its own internal state to an initial state, and
99determines whether the current encoding is state-dependent.
100This function returns 0 if the encoding is state-independent,
101otherwise non-zero.
102In this case,
103.Fa pwc
104is completely ignored.
105.It pwc == NULL
106.Fn mbtowc
107executes the conversion as if
108.Fa pwc
109is non-null, but a result of the conversion is discarded.
110.It n == 0
111In this case,
112the first
113.Fa n
114bytes of the array pointed to by
115.Fa s
116never form a complete character.
117Thus, the
118.Fn mbtowc
119always fails.
120.El
121.\" ----------------------------------------------------------------------
122.Sh RETURN VALUES
123Normally, the
124.Fn mbtowc
125returns:
126.Bl -tag -width 012345678901
127.It 0
128.Fa s
129points to a null byte
130.Pq Sq \e0 .
131.It positive
132Number of bytes for the valid multibyte character pointed to by
133.Fa s .
134There are no cases that the value returned is greater than
135the value of the
136.Dv MB_CUR_MAX
137macro.
138.It -1
139.Fa s
140points to an invalid or an incomplete multibyte character.
141The
142.Fn mbtowc
143also sets
144.Va errno
145to indicate the error.
146.El
147.Pp
148When
149.Fa s
150is equal to
151.Dv NULL ,
152.Fn mbtowc
153returns:
154.Bl -tag -width 0123456789
155.It 0
156The current encoding is state-independent.
157.It non-zero
158The current encoding is state-dependent.
159.El
160.\" ----------------------------------------------------------------------
161.Sh ERRORS
162.Fn mbtowc
163may cause an error in the following case:
164.Bl -tag -width Er
165.It Bq Er EILSEQ
166.Fa s
167points to an invalid or incomplete multibyte character.
168.El
169.\" ----------------------------------------------------------------------
170.Sh SEE ALSO
171.Xr mblen 3 ,
172.Xr mbrtowc 3 ,
173.Xr setlocale 3
174.\" ----------------------------------------------------------------------
175.Sh STANDARDS
176The
177.Fn mbtowc
178function conforms to
179.St -ansiC .
180The restrict qualifier is added at
181.St -isoC-99 .
182