1.\" $NetBSD: src/lib/libc/locale/mbrlen.3,v 1.6 2004/01/24 16:58:54 wiz Exp $ 2.\" $DragonFly: src/lib/libc/locale/mbrlen.3,v 1.1 2005/03/12 00:18:01 joerg 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 February 3, 2002 29.Dt MBRLEN 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm mbrlen 34.Nd get number of bytes in a multibyte character (restartable) 35.\" ---------------------------------------------------------------------- 36.Sh LIBRARY 37.Lb libc 38.\" ---------------------------------------------------------------------- 39.Sh SYNOPSIS 40.In wchar.h 41.Ft int 42.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps" 43.\" ---------------------------------------------------------------------- 44.Sh DESCRIPTION 45The 46.Fn mbrlen 47function usually determines the number of bytes in 48a multibyte character pointed to by 49.Fa s 50and returns it. 51This function shall only examine max n bytes of the array beginning from 52.Fa s . 53.Pp 54.Fn mbrlen 55is equivalent to the following call (except 56.Fa ps 57is evaluated only once): 58.Bd -literal -offset indent 59mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal); 60.Ed 61.Pp 62Here, 63.Fa internal 64is an internal state object. 65.Pp 66In state-dependent encodings, 67.Fa s 68may point to the special sequence bytes to change the shift-state. 69Although such sequence bytes corresponds to no individual 70wide-character code, these affect the conversion state object pointed 71to by 72.Fa ps , 73and the 74.Fn mbrlen 75treats the special sequence bytes 76as if these are a part of the subsequent multibyte character. 77.Pp 78Unlike 79.Xr mblen 3 , 80.Fn mbrlen 81may accept the byte sequence when it is not a complete character 82but possibly contains part of a valid character. 83In this case, this function will accept all such bytes 84and save them into the conversion state object pointed to by 85.Fa ps . 86They will be used on subsequent calls of this function to restart 87the conversion suspended. 88.Pp 89The behaviour of 90.Fn mbrlen 91is affected by the 92.Dv LC_CTYPE 93category of the current locale. 94.Pp 95These are the special cases: 96.Bl -tag -width 0123456789 97.It "s == NULL" 98.Fn mbrlen 99sets the conversion state object pointed to by 100.Fa ps 101to an initial state and always returns 0. 102Unlike 103.Xr mblen 3 , 104the value returned does not indicate whether the current encoding of 105the locale is state-dependent. 106.Pp 107In this case, 108.Fn mbrlen 109ignores 110.Fa n . 111.It "n == 0" 112In this case, 113the first 114.Fa n 115bytes of the array pointed to by 116.Fa s 117never form a complete character. 118Thus, 119.Fn mbrlen 120always returns (size_t)-2. 121.It "ps == NULL" 122.Fn mbrlen 123uses its own internal state object to keep the conversion state, 124instead of 125.Fa ps 126mentioned in this manual page. 127.Pp 128Calling any other functions in 129.Lb libc 130never changes the internal 131state of 132.Fn mbrlen , 133except for calling 134.Xr setlocale 3 135with a changing 136.Dv LC_CTYPE 137category of the current locale. 138Such 139.Xr setlocale 3 140calls cause the internal state of this function to be indeterminate. 141This internal state is initialized at startup time of the program. 142.El 143.\" ---------------------------------------------------------------------- 144.Sh RETURN VALUES 145The 146.Fn mbrlen 147returns: 148.Bl -tag -width 0123456789 149.It "0" 150.Fa s 151points to a null byte 152.Pq Sq \e0 . 153.It "positive" 154The value returned is 155a number of bytes for the valid multibyte character pointed to by 156.Fa s . 157There are no cases that this value is greater than 158.Fa n 159or the value of the 160.Dv MB_CUR_MAX 161macro. 162.It "(size_t)-2" 163.Fa s 164points to the byte sequence which possibly contains part of a valid 165multibyte character, but which is incomplete. 166When 167.Fa n 168is at least 169.Dv MB_CUR_MAX , 170this case can only occur if the array pointed to by 171.Fa s 172contains a redundant shift sequence. 173.It "(size_t)-1" 174.Fa s 175points to an illegal byte sequence which does not form a valid multibyte 176character. 177In this case, 178.Fn mbrtowc 179sets 180.Va errno 181to indicate the error. 182.El 183.\" ---------------------------------------------------------------------- 184.Sh ERRORS 185.Fn mbrlen 186may cause an error in the following case: 187.Bl -tag -width Er 188.It Bq Er EILSEQ 189.Fa s 190points to an invalid multibyte character. 191.It Bq Er EINVAL 192.Fa ps 193points to an invalid or uninitialized mbstate_t object. 194.El 195.\" ---------------------------------------------------------------------- 196.Sh SEE ALSO 197.Xr mblen 3 , 198.Xr mbrtowc 3 , 199.Xr setlocale 3 200.\" ---------------------------------------------------------------------- 201.Sh STANDARDS 202The 203.Fn mbrlen 204function conforms to 205.St -isoC-amd1 . 206The restrict qualifier is added at 207.St -isoC-99 . 208