1.\" $NetBSD: mblen.3,v 1.2 2002/03/18 07:56:28 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 consisting a multibyte character 34.\" ---------------------------------------------------------------------- 35.Sh LIBRARY 36.Lb libc 37.\" ---------------------------------------------------------------------- 38.Sh SYNOPSIS 39.Fd #include \*[Lt]stdlib.h\*[Gt] 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 consisting in 47a multibyte character pointed by 48.Fa s 49and return 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 subsequence multibyte character. 62.Pp 63Unlike 64.Xr mbrlen 3 , 65the first 66.Fa n 67bytes pointed 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.Pp 77.Bd -literal 78mbtowc(NULL, s, n); 79.Ed 80.Pp 81Calling any other functions in the 82.Lb libc 83never change the internal 84state of the 85.Fn mblen , 86except for calling 87.Xr setlocale 3 88with changing LC_CTYPE category of the current locale. 89Such 90.Xr setlocale 3 91call causes the internal state of this function to be indeterminate. 92.Pp 93The behaviour of the 94.Fn mblen 95is affected by LC_CTYPE category of the current locale. 96.Pp 97There are special cases: 98.Bl -tag -width 0123456789 99.It "s == NULL" 100The 101.Fn mblen 102initializes its own internal state to an initial state, and 103determines whether the current encoding is state-dependent. 104This function returns 0 if the encoding is state-independent, 105otherwise non-zero. 106.It "n == 0" 107In this case, 108the first 109.Fa n 110bytes of the array pointed by 111.Fa s 112never form a complete character. Thus, the 113.Fn mblen 114always fails. 115.El 116.\" ---------------------------------------------------------------------- 117.Sh RETURN VALUES 118In the usual cases, the 119.Fn mblen 120returns: 121.Bl -tag -width 0123456789 122.It "0" 123.Fa s 124points a null byte (\'\\0\'). 125.It "positive" 126The value returned is 127a number of bytes for the valid multibyte character pointed by 128.Fa s . 129There is no cases that this value is greater than 130.Fa n 131or the value of MB_CUR_MAX macro. 132.It "-1" 133.Fa s 134points an invalid or incomplete multibyte character. 135The 136.Fn mblen 137also sets errno to indicate the error. 138.El 139.Pp 140In the case that 141.Fa s 142is equal to NULL, the 143.Fn mblen 144returns: 145.Bl -tag -width 0123456789 146.It "0" 147The current encoding is state-independent. 148.It "non-zero" 149The current encoding is state-dependent. 150.El 151.\" ---------------------------------------------------------------------- 152.Sh ERRORS 153The 154.Fn mblen 155may causes an error in the following case: 156.Bl -tag -width Er 157.It Bq Er EILSEQ 158.Fa s 159points an invalid or incomplete multibyte character. 160.El 161.\" ---------------------------------------------------------------------- 162.Sh SEE ALSO 163.Xr mbrlen 3 , 164.Xr mbtowc 3 , 165.Xr setlocale 3 166.\" ---------------------------------------------------------------------- 167.Sh STANDARDS 168The 169.Fn mblen 170function conforms to 171.St -ansiC . 172