18b810927STim J. Robbins.\" Copyright (c) 2002-2004 Tim J. Robbins 2e92a3d83STim J. Robbins.\" All rights reserved. 3e92a3d83STim J. Robbins.\" 4e92a3d83STim J. Robbins.\" Redistribution and use in source and binary forms, with or without 5e92a3d83STim J. Robbins.\" modification, are permitted provided that the following conditions 6e92a3d83STim J. Robbins.\" are met: 7e92a3d83STim J. Robbins.\" 1. Redistributions of source code must retain the above copyright 8e92a3d83STim J. Robbins.\" notice, this list of conditions and the following disclaimer. 9e92a3d83STim J. Robbins.\" 2. Redistributions in binary form must reproduce the above copyright 10e92a3d83STim J. Robbins.\" notice, this list of conditions and the following disclaimer in the 11e92a3d83STim J. Robbins.\" documentation and/or other materials provided with the distribution. 12e92a3d83STim J. Robbins.\" 13e92a3d83STim J. Robbins.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14e92a3d83STim J. Robbins.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15e92a3d83STim J. Robbins.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16e92a3d83STim J. Robbins.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17e92a3d83STim J. Robbins.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18e92a3d83STim J. Robbins.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19e92a3d83STim J. Robbins.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20e92a3d83STim J. Robbins.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21e92a3d83STim J. Robbins.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22e92a3d83STim J. Robbins.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23e92a3d83STim J. Robbins.\" SUCH DAMAGE. 24e92a3d83STim J. Robbins.\" 258b810927STim J. Robbins.Dd April 7, 2004 26e92a3d83STim J. Robbins.Dt MBRLEN 3 27e92a3d83STim J. Robbins.Os 28e92a3d83STim J. Robbins.Sh NAME 29e92a3d83STim J. Robbins.Nm mbrlen 30e92a3d83STim J. Robbins.Nd "get number of bytes in a character (restartable)" 31e92a3d83STim J. Robbins.Sh LIBRARY 32e92a3d83STim J. Robbins.Lb libc 33e92a3d83STim J. Robbins.Sh SYNOPSIS 34e92a3d83STim J. Robbins.In wchar.h 35e92a3d83STim J. Robbins.Ft size_t 36e92a3d83STim J. Robbins.Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps" 37e92a3d83STim J. Robbins.Sh DESCRIPTION 38e92a3d83STim J. RobbinsThe 39e92a3d83STim J. Robbins.Fn mbrlen 408b810927STim J. Robbinsfunction inspects at most 417183f43dSTim J. Robbins.Fa n 428b810927STim J. Robbinsbytes pointed to by 438b810927STim J. Robbins.Fa s 448b810927STim J. Robbinsto determine the number of bytes needed to complete the next 458b810927STim J. Robbinsmultibyte character. 467183f43dSTim J. Robbins.Pp 477183f43dSTim J. RobbinsThe 48279062faSRuslan Ermilov.Vt mbstate_t 497183f43dSTim J. Robbinsargument, 507183f43dSTim J. Robbins.Fa ps , 517183f43dSTim J. Robbinsis used to keep track of the shift state. 527183f43dSTim J. RobbinsIf it is 537183f43dSTim J. Robbins.Dv NULL , 547183f43dSTim J. Robbins.Fn mbrlen 557183f43dSTim J. Robbinsuses an internal, static 56279062faSRuslan Ermilov.Vt mbstate_t 578b810927STim J. Robbinsobject, which is initialized to the initial conversion state 588b810927STim J. Robbinsat program startup. 59e92a3d83STim J. Robbins.Pp 60e92a3d83STim J. RobbinsIt is equivalent to: 61e92a3d83STim J. Robbins.Pp 62e92a3d83STim J. Robbins.Dl "mbrtowc(NULL, s, n, ps);" 63e92a3d83STim J. Robbins.Pp 64e92a3d83STim J. RobbinsExcept that when 65e92a3d83STim J. Robbins.Fa ps 66279062faSRuslan Ermilovis a 67279062faSRuslan Ermilov.Dv NULL 68279062faSRuslan Ermilovpointer, 69e92a3d83STim J. Robbins.Fn mbrlen 70e92a3d83STim J. Robbinsuses its own static, internal 71279062faSRuslan Ermilov.Vt mbstate_t 72279062faSRuslan Ermilovobject to keep track of the shift state. 73e92a3d83STim J. Robbins.Sh RETURN VALUES 74e92a3d83STim J. RobbinsThe 75e92a3d83STim J. Robbins.Fn mbrlen 76e92a3d83STim J. Robbinsfunctions returns: 77e92a3d83STim J. Robbins.Bl -tag -width indent 78e92a3d83STim J. Robbins.It 0 798b810927STim J. RobbinsThe next 80e92a3d83STim J. Robbins.Fa n 818b810927STim J. Robbinsor fewer bytes 82279062faSRuslan Ermilovrepresent the null wide character 83279062faSRuslan Ermilov.Pq Li "L'\e0'" . 84e92a3d83STim J. Robbins.It >0 858b810927STim J. RobbinsThe next 86e92a3d83STim J. Robbins.Fa n 878b810927STim J. Robbinsor fewer bytes 88e92a3d83STim J. Robbinsrepresent a valid character, 898b810927STim J. Robbins.Fn mbrlen 908b810927STim J. Robbinsreturns the number of bytes used to complete the multibyte character. 91279062faSRuslan Ermilov.It Po Vt size_t Pc Ns \-2 928b810927STim J. RobbinsThe next 93e92a3d83STim J. Robbins.Fa n 948b810927STim J. Robbinscontribute to, but do not complete, a valid multibyte character sequence, 958b810927STim J. Robbinsand all 968b810927STim J. Robbins.Fa n 978b810927STim J. Robbinsbytes have been processed. 98279062faSRuslan Ermilov.It Po Vt size_t Pc Ns \-1 998b810927STim J. RobbinsAn encoding error has occurred. 1008b810927STim J. RobbinsThe next 101bd486f88SRuslan Ermilov.Fa n 1028b810927STim J. Robbinsor fewer bytes do not contribute to a valid multibyte character. 103e92a3d83STim J. Robbins.El 10428ddc413STim J. Robbins.Sh EXAMPLES 1058b810927STim J. RobbinsA function that calculates the number of characters in a multibyte 10628ddc413STim J. Robbinscharacter string: 10728ddc413STim J. Robbins.Bd -literal -offset indent 10828ddc413STim J. Robbinssize_t 10928ddc413STim J. Robbinsnchars(const char *s) 11028ddc413STim J. Robbins{ 11128ddc413STim J. Robbins size_t charlen, chars; 11228ddc413STim J. Robbins mbstate_t mbs; 11328ddc413STim J. Robbins 11428ddc413STim J. Robbins chars = 0; 11528ddc413STim J. Robbins memset(&mbs, 0, sizeof(mbs)); 11628ddc413STim J. Robbins while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 && 11728ddc413STim J. Robbins charlen != (size_t)-1 && charlen != (size_t)-2) { 11828ddc413STim J. Robbins s += charlen; 11928ddc413STim J. Robbins chars++; 12028ddc413STim J. Robbins } 12128ddc413STim J. Robbins 12228ddc413STim J. Robbins return (chars); 12328ddc413STim J. Robbins} 12428ddc413STim J. Robbins.Ed 125e92a3d83STim J. Robbins.Sh ERRORS 126e92a3d83STim J. RobbinsThe 127e92a3d83STim J. Robbins.Fn mbrlen 128e92a3d83STim J. Robbinsfunction will fail if: 129e92a3d83STim J. Robbins.Bl -tag -width Er 130e92a3d83STim J. Robbins.It Bq Er EILSEQ 131e92a3d83STim J. RobbinsAn invalid multibyte sequence was detected. 1328b810927STim J. Robbins.It Bq Er EINVAL 1338b810927STim J. RobbinsThe conversion state is invalid. 134e92a3d83STim J. Robbins.El 135e92a3d83STim J. Robbins.Sh SEE ALSO 136e92a3d83STim J. Robbins.Xr mblen 3 , 1378b810927STim J. Robbins.Xr mbrtowc 3 , 1388b810927STim J. Robbins.Xr multibyte 3 139e92a3d83STim J. Robbins.Sh STANDARDS 140e92a3d83STim J. RobbinsThe 141e92a3d83STim J. Robbins.Fn mbrlen 142e92a3d83STim J. Robbinsfunction conforms to 143e92a3d83STim J. Robbins.St -isoC-99 . 144