1.\" $NetBSD: mbrlen.3,v 1.9 2008/02/28 19:36:51 tnozaki 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 in a multibyte character (restartable) 34.\" ---------------------------------------------------------------------- 35.Sh LIBRARY 36.Lb libc 37.\" ---------------------------------------------------------------------- 38.Sh SYNOPSIS 39.In wchar.h 40.Ft size_t 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 in 47a multibyte character pointed to by 48.Fa s 49and returns 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.Bd -literal -offset indent 58mbrtowc(NULL, s, n, (ps != NULL) ? ps : \*[Am]internal); 59.Ed 60.Pp 61Here, 62.Fa internal 63is an internal state object. 64.Pp 65In state-dependent encodings, 66.Fa s 67may point to the special sequence bytes to change the shift-state. 68Although such sequence bytes corresponds to no individual 69wide-character code, these affect the conversion state object pointed 70to 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 , 79.Fn mbrlen 80may accept the byte sequence when it is not a complete character 81but possibly contains part of a valid character. 82In this case, this function will accept all such bytes 83and save them into the conversion state object pointed to by 84.Fa ps . 85They will be used on subsequent calls of this function to restart 86the conversion suspended. 87.Pp 88The behaviour of 89.Fn mbrlen 90is affected by the 91.Dv LC_CTYPE 92category of the current locale. 93.Pp 94These are the special cases: 95.Bl -tag -width 0123456789 96.It "s == NULL" 97.Fn mbrlen 98sets the conversion state object pointed to by 99.Fa ps 100to an initial state and always returns 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, 107.Fn mbrlen 108ignores 109.Fa n . 110.It "n == 0" 111In this case, 112the first 113.Fa n 114bytes of the array pointed to by 115.Fa s 116never form a complete character. 117Thus, 118.Fn mbrlen 119always returns (size_t)-2. 120.It "ps == NULL" 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 128.Lb libc 129never changes the internal 130state of 131.Fn mbrlen , 132except for calling 133.Xr setlocale 3 134with a changing 135.Dv LC_CTYPE 136category of the current locale. 137Such 138.Xr setlocale 3 139calls cause the internal state of this function to be indeterminate. 140This internal state is initialized at startup time of the program. 141.El 142.\" ---------------------------------------------------------------------- 143.Sh RETURN VALUES 144The 145.Fn mbrlen 146returns: 147.Bl -tag -width 0123456789 148.It "0" 149.Fa s 150points to a nul byte 151.Pq Sq \e0 . 152.It "positive" 153The value returned is 154a number of bytes for the valid multibyte character pointed to by 155.Fa s . 156There are no cases that this value is greater than 157.Fa n 158or the value of the 159.Dv MB_CUR_MAX 160macro. 161.It "(size_t)-2" 162.Fa s 163points to the byte sequence which possibly contains part of a valid 164multibyte character, but which is incomplete. 165When 166.Fa n 167is at least 168.Dv MB_CUR_MAX , 169this case can only occur if the array pointed to by 170.Fa s 171contains a redundant shift sequence. 172.It "(size_t)-1" 173.Fa s 174points to an illegal byte sequence which does not form a valid multibyte 175character. 176In this case, 177.Fn mbrtowc 178sets 179.Va errno 180to indicate the error. 181.El 182.\" ---------------------------------------------------------------------- 183.Sh ERRORS 184.Fn mbrlen 185may cause an error in the following case: 186.Bl -tag -width Er 187.It Bq Er EILSEQ 188.Fa s 189points to an invalid multibyte character. 190.It Bq Er EINVAL 191.Fa ps 192points to an invalid or uninitialized mbstate_t object. 193.El 194.\" ---------------------------------------------------------------------- 195.Sh SEE ALSO 196.Xr mblen 3 , 197.Xr mbrtowc 3 , 198.Xr setlocale 3 199.\" ---------------------------------------------------------------------- 200.Sh STANDARDS 201The 202.Fn mbrlen 203function conforms to 204.St -isoC-amd1 . 205The restrict qualifier is added at 206.St -isoC-99 . 207