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