1 .\" $NetBSD: src/lib/libc/locale/mbrtowc.3,v 1.6 2004/01/24 16:58:54 wiz Exp $
2 .\" $DragonFly: src/lib/libc/locale/mbrtowc.3,v 1.1 2005/03/12 00:18:01 joerg Exp $
4 .\" Copyright (c)2002 Citrus Project,
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" ----------------------------------------------------------------------
34 .Nd converts a multibyte character to a wide character (restartable)
35 .\" ----------------------------------------------------------------------
38 .\" ----------------------------------------------------------------------
42 .Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" \
43 "mbstate_t * restrict ps"
44 .\" ----------------------------------------------------------------------
48 usually converts the multibyte character pointed to by
50 to a wide character, and stores the wide character
51 to the wchar_t object pointed to by
57 points to a valid character.
58 The conversion happens in accordance with, and changes the conversion
59 state described in the mbstate_t object pointed to by
61 This function may examine at most
63 bytes of the array beginning from
68 points to a valid character and the character corresponds to a null wide
71 places the mbstate_t object pointed to by
73 to an initial conversion state.
79 may accept the byte sequence pointed to by
81 not forming a complete multibyte character
82 but which may be part of a valid character.
83 In this case, this function will accept all such bytes
84 and save them into the conversion state object pointed to by
86 They will be used at subsequent calls of this function to restart
87 the conversion suspended.
93 category of the current locale.
95 These are the special cases:
96 .Bl -tag -width 012345678901
99 sets the conversion state object pointed to by
101 to an initial state and always returns 0.
104 the value returned does not indicate whether the current encoding of
105 the locale is state-dependent.
113 and is equivalent to the following call:
114 .Bd -literal -offset indent
115 mbrtowc(NULL, "", 1, ps);
118 The conversion from a multibyte character to a wide character has
119 taken place and the conversion state may be affected, but the resulting
120 wide character is discarded.
123 uses its own internal state object to keep the conversion state,
126 mentioned in this manual page.
128 Calling any other functions in
130 never changes the internal state of
132 which is initialized at startup time of the program.
134 .\" ----------------------------------------------------------------------
139 .Bl -tag -width 012345678901
141 The next bytes pointed to by
143 form a null character.
147 points to a valid character,
149 returns the number of bytes in the character.
152 points to a byte sequence which possibly contains part of a valid
153 multibyte character, but which is incomplete.
158 this case can only occur if the array pointed to by
160 contains a redundant shift sequence.
163 points to an illegal byte sequence which does not form a valid multibyte
169 to indicate the error.
171 .\" ----------------------------------------------------------------------
174 may cause an error in the following case:
178 points to an invalid or incomplete multibyte character.
181 points to an invalid or uninitialized mbstate_t object.
183 .\" ----------------------------------------------------------------------
188 .\" ----------------------------------------------------------------------
194 The restrict qualifier is added at