1.\" $NetBSD: mbrlen.3,v 1.2 2002/03/18 07:56:28 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. Thus, the 117.Fn mbrlen 118always returns (size_t)-2. 119.It "ps == NULL" 120The 121.Fn mbrlen 122uses its own internal state object to keep the conversion state, 123instead of 124.Fa ps 125mentioned in this manual page. 126.Pp 127Calling any other functions in the 128.Lb libc 129never change the internal 130state of the 131.Fn mbrlen , 132except for calling 133.Xr setlocale 3 134with changing LC_CTYPE category of the current locale. 135Such 136.Xr setlocale 3 137call causes the internal state of this function to be indeterminate. 138This internal state is initialized at startup time of the program. 139.El 140.\" ---------------------------------------------------------------------- 141.Sh RETURN VALUES 142The 143.Fn mbrlen 144returns: 145.Bl -tag -width 0123456789 146.It "0" 147.Fa s 148points a null byte (\'\\0\'). 149.It "positive" 150The value returned is 151a number of bytes for the valid multibyte character pointed by 152.Fa s . 153There is no cases that this value is greater than 154.Fa n 155or the value of MB_CUR_MAX macro. 156.It "(size_t)-2" 157.Fa s 158points the byte sequence which is possible to consist a part of valid 159multibyte character but incomplete. 160When 161.Fa n 162is at least MB_CUR_MAX, 163this case can only occur if the array pointed 164.Fa s 165contains redundant shift sequence. 166.It "(size_t)-1" 167.Fa s 168points a illegal byte sequence which does not form a valid multibyte 169character. 170In this case, the 171.Fn mbrtowc 172sets errno to indicate the error. 173.El 174.\" ---------------------------------------------------------------------- 175.Sh ERRORS 176The 177.Fn mbrlen 178may causes an error in the following case: 179.Bl -tag -width Er 180.It Bq Er EILSEQ 181.Fa s 182points an invalid multibyte character. 183.It Bq Er EINVAL 184.Fa ps 185points an invalid or uninitialized mbstate_t object. 186.El 187.\" ---------------------------------------------------------------------- 188.Sh SEE ALSO 189.Xr mblen 3 , 190.Xr mbrtowc 3 , 191.Xr setlocale 3 192.\" ---------------------------------------------------------------------- 193.Sh STANDARDS 194The 195.Fn mbrlen 196function conforms to 197.St -isoC-amd1 . 198The restrict qualifier is added at 199.St -isoC99 . 200