1.\" $NetBSD: mbrlen.3,v 1.3 2002/10/01 17:02:56 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 MBRLEN 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm mbrlen 33.Nd get number of bytes consisting a multibyte character (restartable) 34.\" ---------------------------------------------------------------------- 35.Sh LIBRARY 36.Lb libc 37.\" ---------------------------------------------------------------------- 38.Sh SYNOPSIS 39.Fd #include \*[Lt]wchar.h\*[Gt] 40.Ft int 41.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps" 42.\" ---------------------------------------------------------------------- 43.Sh DESCRIPTION 44The 45.Fn mbrlen 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 53.Fn mbrlen 54is equivalent to the following call (except 55.Fa ps 56is evaluated only once): 57.Pp 58.Bd -literal 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 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 by 71.Fa ps , 72and the 73.Fn mbrlen 74treats the special sequence bytes 75as if these are a part of the subsequent multibyte character. 76.Pp 77Unlike 78.Xr mblen 3 , 79the 80.Fn mbrlen 81may accept the byte sequence being not complete character 82but possible to consist a part of a valid character. 83In this case, this function will accept the all such bytes 84and save them into the conversion state object pointed by 85.Fa ps . 86They will be used at the subsequent call of this function to restart 87the conversion suspended. 88.Pp 89The behaviour of the 90.Fn mbrlen 91is affected by LC_CTYPE category of the current locale. 92.Pp 93There are the special cases: 94.Bl -tag -width 0123456789 95.It "s == NULL" 96The 97.Fn mbrlen 98sets the conversion state object pointed by 99.Fa ps 100to an initial state and always return 0. 101Unlike 102.Xr mblen 3 , 103the value returned does not indicate whether the current encoding of 104the locale is state-dependent. 105.Pp 106In this case, the 107.Fn mbrlen 108ignores 109.Fa n . 110.It "n == 0" 111In this case, 112the first 113.Fa n 114bytes of the array pointed by 115.Fa s 116never form a complete character. 117Thus, the 118.Fn mbrlen 119always returns (size_t)-2. 120.It "ps == NULL" 121The 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 the 129.Lb libc 130never change the internal 131state of the 132.Fn mbrlen , 133except for calling 134.Xr setlocale 3 135with changing LC_CTYPE category of the current locale. 136Such 137.Xr setlocale 3 138call causes the internal state of this function to be indeterminate. 139This internal state is initialized at startup time of the program. 140.El 141.\" ---------------------------------------------------------------------- 142.Sh RETURN VALUES 143The 144.Fn mbrlen 145returns: 146.Bl -tag -width 0123456789 147.It "0" 148.Fa s 149points a null byte (\'\\0\'). 150.It "positive" 151The value returned is 152a number of bytes for the valid multibyte character pointed by 153.Fa s . 154There is no cases that this value is greater than 155.Fa n 156or the value of MB_CUR_MAX macro. 157.It "(size_t)-2" 158.Fa s 159points the byte sequence which is possible to consist a part of valid 160multibyte character but incomplete. 161When 162.Fa n 163is at least MB_CUR_MAX, 164this case can only occur if the array pointed 165.Fa s 166contains redundant shift sequence. 167.It "(size_t)-1" 168.Fa s 169points a illegal byte sequence which does not form a valid multibyte 170character. 171In this case, the 172.Fn mbrtowc 173sets errno to indicate the error. 174.El 175.\" ---------------------------------------------------------------------- 176.Sh ERRORS 177The 178.Fn mbrlen 179may causes an error in the following case: 180.Bl -tag -width Er 181.It Bq Er EILSEQ 182.Fa s 183points an invalid multibyte character. 184.It Bq Er EINVAL 185.Fa ps 186points an invalid or uninitialized mbstate_t object. 187.El 188.\" ---------------------------------------------------------------------- 189.Sh SEE ALSO 190.Xr mblen 3 , 191.Xr mbrtowc 3 , 192.Xr setlocale 3 193.\" ---------------------------------------------------------------------- 194.Sh STANDARDS 195The 196.Fn mbrlen 197function conforms to 198.St -isoC-amd1 . 199The restrict qualifier is added at 200.St -isoC99 . 201