1 .\" $NetBSD: src/lib/libc/locale/mbrlen.3,v 1.6 2004/01/24 16:58:54 wiz Exp $
2 .\" $DragonFly: src/lib/libc/locale/mbrlen.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 get number of bytes in a multibyte character (restartable)
35 .\" ----------------------------------------------------------------------
38 .\" ----------------------------------------------------------------------
42 .Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
43 .\" ----------------------------------------------------------------------
47 function usually determines the number of bytes in
48 a multibyte character pointed to by
51 This function shall only examine max n bytes of the array beginning from
55 is equivalent to the following call (except
57 is evaluated only once):
58 .Bd -literal -offset indent
59 mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal);
64 is an internal state object.
66 In state-dependent encodings,
68 may point to the special sequence bytes to change the shift-state.
69 Although such sequence bytes corresponds to no individual
70 wide-character code, these affect the conversion state object pointed
75 treats the special sequence bytes
76 as if these are a part of the subsequent multibyte character.
81 may accept the byte sequence when it is not a complete character
82 but possibly contains 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 on 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 0123456789
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.
115 bytes of the array pointed to by
117 never form a complete character.
120 always returns (size_t)-2.
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
137 category of the current locale.
140 calls cause the internal state of this function to be indeterminate.
141 This internal state is initialized at startup time of the program.
143 .\" ----------------------------------------------------------------------
148 .Bl -tag -width 0123456789
151 points to a null byte
154 The value returned is
155 a number of bytes for the valid multibyte character pointed to by
157 There are no cases that this value is greater than
164 points to the byte sequence which possibly contains part of a valid
165 multibyte character, but which is incomplete.
170 this case can only occur if the array pointed to by
172 contains a redundant shift sequence.
175 points to an illegal byte sequence which does not form a valid multibyte
181 to indicate the error.
183 .\" ----------------------------------------------------------------------
186 may cause an error in the following case:
190 points to an invalid multibyte character.
193 points to an invalid or uninitialized mbstate_t object.
195 .\" ----------------------------------------------------------------------
200 .\" ----------------------------------------------------------------------
206 The restrict qualifier is added at