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