1.\" $OpenBSD: mblen.3,v 1.4 2022/03/29 18:15:52 naddy 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: March 29 2022 $ 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 usually determines the number of bytes in 45a multibyte character pointed to by 46.Fa s 47and returns it. 48This function shall only examine max n bytes of the array beginning from 49.Fa s . 50.Pp 51In state-dependent encodings, 52.Fa s 53may point the special sequence bytes to change the shift-state. 54Although such sequence bytes corresponds to no individual 55wide-character code, 56the 57.Fn mblen 58changes the own state by them and treats them 59as if they are a 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 functions in 79.Em libc 80never change the internal 81state of the 82.Fn mblen , 83except for calling 84.Xr setlocale 3 85with the 86.Dv LC_CTYPE 87category changed to that of the current locale. 88Such 89.Xr setlocale 3 90calls cause the internal state of this function to be indeterminate. 91.Pp 92The behaviour of 93.Fn mblen 94is affected by the 95.Dv LC_CTYPE 96category of the current locale. 97.Pp 98There are special cases: 99.Bl -tag -width 0123456789 100.It "s == NULL" 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 to by 111.Fa s 112never form a complete character. 113Thus, 114.Fn mblen 115always fails. 116.El 117.\" ---------------------------------------------------------------------- 118.Sh RETURN VALUES 119Normally, 120.Fn mblen 121returns: 122.Bl -tag -width 0123456789 123.It "0" 124.Fa s 125points to a null byte 126.Pq Sq \e0 . 127.It "positive" 128The value returned is 129a number of bytes for the valid multibyte character pointed to by 130.Fa s . 131There are no cases when this value is greater than 132.Fa n 133or the value of the 134.Dv MB_CUR_MAX 135macro. 136.It "-1" 137.Fa s 138points an invalid or incomplete multibyte character. 139The 140.Fn mblen 141function also sets 142.Va errno 143to indicate the error. 144.El 145.Pp 146When 147.Fa s 148is equal to 149.Dv NULL , 150.Fn mblen 151returns: 152.Bl -tag -width 0123456789 153.It "0" 154The current encoding is state-independent. 155.It "non-zero" 156The current encoding is state-dependent. 157.El 158.\" ---------------------------------------------------------------------- 159.Sh ERRORS 160The 161.Fn mblen 162function may cause an error in the following case: 163.Bl -tag -width Er 164.It Bq Er EILSEQ 165.Fa s 166points to an invalid or incomplete multibyte character. 167.El 168.\" ---------------------------------------------------------------------- 169.Sh SEE ALSO 170.Xr mbrlen 3 , 171.Xr mbtowc 3 , 172.Xr setlocale 3 173.\" ---------------------------------------------------------------------- 174.Sh STANDARDS 175The 176.Fn mblen 177function conforms to 178.St -ansiC . 179