1.\" $NetBSD: mblen.3,v 1.7 2024/02/03 10:55:38 rillig 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, 2024 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 examines at most 51.Fa n 52bytes of the array beginning from 53.Fa s . 54.Pp 55In state-dependent encodings, 56.Fa s 57may point to the special sequence bytes to change the shift-state. 58Although such sequence bytes corresponds to no individual 59wide-character code, 60the 61.Fn mblen 62function changes its own state by them and treats them 63as if they were part of the subsequent multibyte character. 64.Pp 65Unlike 66.Xr mbrlen 3 , 67the first 68.Fa n 69bytes pointed to by 70.Fa s 71need to form an entire multibyte character. 72Otherwise, this function causes an error. 73.Pp 74.Fn mblen 75is equivalent to the following call, except the internal state of the 76.Xr mbtowc 3 77function is not affected: 78.Bd -literal -offset indent 79mbtowc(NULL, s, n); 80.Ed 81.Pp 82Calling any other functions in 83.Lb libc 84never changes the internal 85state of 86.Fn mblen , 87except for calling 88.Xr setlocale 3 89with the 90.Dv LC_CTYPE 91category changed to that of the current locale. 92Such 93.Xr setlocale 3 94calls cause the internal state of this function to be indeterminate. 95.Pp 96The behaviour of 97.Fn mblen 98is affected by the 99.Dv LC_CTYPE 100category of the current locale. 101.Pp 102These are the special cases: 103.Bl -tag -width 0123456789 104.It "s == NULL" 105.Fn mblen 106initializes its own internal state to an initial state, and 107determines whether the current encoding is state-dependent. 108This function returns 0 if the encoding is state-independent, 109otherwise non-zero. 110.It "n == 0" 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 nul byte 129.Pq Sq \e0 . 130.It "positive" 131The value returned is 132the number of bytes for the valid multibyte character pointed to by 133.Fa s . 134The value returned is at most 135.Fa n , 136and at most 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 144function also 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 155function returns: 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