xref: /dragonfly/lib/libc/locale/mblen.3 (revision e1acdbad) 
1.\" $NetBSD: src/lib/libc/locale/mblen.3,v 1.5 2004/01/24 16:58:54 wiz Exp $
2.\" $DragonFly: src/lib/libc/locale/mblen.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 MBLEN 3
30.Os
31.\" ----------------------------------------------------------------------
32.Sh NAME
33.Nm mblen
34.Nd get number of bytes in a multibyte character
35.\" ----------------------------------------------------------------------
36.Sh LIBRARY
37.Lb libc
38.\" ----------------------------------------------------------------------
39.Sh SYNOPSIS
40.In stdlib.h
41.Ft int
42.Fn mblen "const char *s" "size_t n"
43.\" ----------------------------------------------------------------------
44.Sh DESCRIPTION
45The
46.Fn mblen
47function usually determines the number of bytes in
48a multibyte character pointed to by
49.Fa s
50and returns it.
51This function shall only examine max n bytes of the array beginning from
52.Fa s .
53.Pp
54In state-dependent encodings,
55.Fa s
56may point the special sequence bytes to change the shift-state.
57Although such sequence bytes corresponds to no individual
58wide-character code,
59the
60.Fn mblen
61changes the own state by them and treats them
62as if they are a part of the subsequent multibyte character.
63.Pp
64Unlike
65.Xr mbrlen 3 ,
66the first
67.Fa n
68bytes pointed to by
69.Fa s
70need to form an entire multibyte character.
71Otherwise, this function causes an error.
72.Pp
73.Fn mblen
74is equivalent to the following call, except the internal state of the
75.Xr mbtowc 3
76function is not affected:
77.Bd -literal -offset indent
78mbtowc(NULL, s, n);
79.Ed
80.Pp
81Calling any other functions in
82.Lb libc
83never changes the internal
84state of
85.Fn mblen ,
86except for calling
87.Xr setlocale 3
88with the
89.Dv LC_CTYPE
90category changed to that of the current locale.
91Such
92.Xr setlocale 3
93calls cause the internal state of this function to be indeterminate.
94.Pp
95The behaviour of
96.Fn mblen
97is affected by the
98.Dv LC_CTYPE
99category of the current locale.
100.Pp
101These are the special cases:
102.Bl -tag -width 0123456789
103.It "s == NULL"
104.Fn mblen
105initializes its own internal state to an initial state, and
106determines whether the current encoding is state-dependent.
107This function returns 0 if the encoding is state-independent,
108otherwise non-zero.
109.It "n == 0"
110In this case,
111the first
112.Fa n
113bytes of the array pointed to by
114.Fa s
115never form a complete character.
116Thus,
117.Fn mblen
118always fails.
119.El
120.\" ----------------------------------------------------------------------
121.Sh RETURN VALUES
122Normally,
123.Fn mblen
124returns:
125.Bl -tag -width 0123456789
126.It "0"
127.Fa s
128points to a null byte
129.Pq Sq \e0 .
130.It "positive"
131The value returned is
132a number of bytes for the valid multibyte character pointed to by
133.Fa s .
134There are no cases that this value is greater than
135.Fa n
136or the value of the
137.Dv MB_CUR_MAX
138macro.
139.It "-1"
140.Fa s
141points to an invalid or incomplete multibyte character.
142The
143.Fn mblen
144also sets
145.Va errno
146to indicate the error.
147.El
148.Pp
149When
150.Fa s
151is equal to
152.Dv NULL ,
153the
154.Fn mblen
155returns:
156.Bl -tag -width 0123456789
157.It "0"
158The current encoding is state-independent.
159.It "non-zero"
160The current encoding is state-dependent.
161.El
162.\" ----------------------------------------------------------------------
163.Sh ERRORS
164.Fn mblen
165may cause an error in the following case:
166.Bl -tag -width Er
167.It Bq Er EILSEQ
168.Fa s
169points to an invalid or incomplete multibyte character.
170.El
171.\" ----------------------------------------------------------------------
172.Sh SEE ALSO
173.Xr mbrlen 3 ,
174.Xr mbtowc 3 ,
175.Xr setlocale 3
176.\" ----------------------------------------------------------------------
177.Sh STANDARDS
178The
179.Fn mblen
180function conforms to
181.St -ansiC .
182