1.\" Copyright (c) 2002-2004 Tim J. Robbins 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd April 7, 2004 26.Dt MBRLEN 3 27.Os 28.Sh NAME 29.Nm mbrlen 30.Nd "get number of bytes in a character (restartable)" 31.Sh LIBRARY 32.Lb libc 33.Sh SYNOPSIS 34.In wchar.h 35.Ft size_t 36.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps" 37.Sh DESCRIPTION 38The 39.Fn mbrlen 40function inspects at most 41.Fa n 42bytes pointed to by 43.Fa s 44to determine the number of bytes needed to complete the next 45multibyte character. 46.Pp 47The 48.Vt mbstate_t 49argument, 50.Fa ps , 51is used to keep track of the shift state. 52If it is 53.Dv NULL , 54.Fn mbrlen 55uses an internal, static 56.Vt mbstate_t 57object, which is initialized to the initial conversion state 58at program startup. 59.Pp 60It is equivalent to: 61.Pp 62.Dl "mbrtowc(NULL, s, n, ps);" 63.Pp 64Except that when 65.Fa ps 66is a 67.Dv NULL 68pointer, 69.Fn mbrlen 70uses its own static, internal 71.Vt mbstate_t 72object to keep track of the shift state. 73.Sh RETURN VALUES 74The 75.Fn mbrlen 76functions returns: 77.Bl -tag -width indent 78.It 0 79The next 80.Fa n 81or fewer bytes 82represent the null wide character 83.Pq Li "L'\e0'" . 84.It >0 85The next 86.Fa n 87or fewer bytes 88represent a valid character, 89.Fn mbrlen 90returns the number of bytes used to complete the multibyte character. 91.It Po Vt size_t Pc Ns \-2 92The next 93.Fa n 94contribute to, but do not complete, a valid multibyte character sequence, 95and all 96.Fa n 97bytes have been processed. 98.It Po Vt size_t Pc Ns \-1 99An encoding error has occurred. 100The next 101.Fa n 102or fewer bytes do not contribute to a valid multibyte character. 103.El 104.Sh EXAMPLES 105A function that calculates the number of characters in a multibyte 106character string: 107.Bd -literal -offset indent 108size_t 109nchars(const char *s) 110{ 111 size_t charlen, chars; 112 mbstate_t mbs; 113 114 chars = 0; 115 memset(&mbs, 0, sizeof(mbs)); 116 while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 && 117 charlen != (size_t)-1 && charlen != (size_t)-2) { 118 s += charlen; 119 chars++; 120 } 121 122 return (chars); 123} 124.Ed 125.Sh ERRORS 126The 127.Fn mbrlen 128function will fail if: 129.Bl -tag -width Er 130.It Bq Er EILSEQ 131An invalid multibyte sequence was detected. 132.It Bq Er EINVAL 133The conversion state is invalid. 134.El 135.Sh SEE ALSO 136.Xr mblen 3 , 137.Xr mbrtowc 3 , 138.Xr multibyte 3 139.Sh STANDARDS 140The 141.Fn mbrlen 142function conforms to 143.St -isoC-99 . 144