1.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. 2.\" Copyright (c) 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Donn Seeley of BSDI. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 33.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp 34.\" $FreeBSD: head/lib/libc/locale/mblen.3 165903 2007-01-09 00:28:16Z imp $ 35.\" 36.Dd December 26, 2013 37.Dt MBLEN 3 38.Os 39.Sh NAME 40.Nm mblen , 41.Nm mblen_l 42.Nd get number of bytes in a character 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft int 48.Fn mblen "const char *mbchar" "size_t nbytes" 49.In xlocale.h 50.Ft int 51.Fn mblen_l "const char *mbchar" "size_t nbytes" "locale_t locale" 52.Sh DESCRIPTION 53The 54.Fn mblen 55and 56.Fn mblen_l 57functions compute the length in bytes 58of a multibyte character 59.Fa mbchar 60according to a conversion state. 61Up to 62.Fa nbytes 63bytes are examined. 64.Pp 65A call with a null 66.Fa mbchar 67pointer returns nonzero if the locale requires shift states, 68zero otherwise; 69if shift states are required, the shift state is reset to the initial state. 70.Pp 71The 72.Fn mblen_l 73function takes an explicit 74.Fa locale 75argument, whereas the 76.Fn mblen 77function uses the current global or per-thread locale. 78.Sh RETURN VALUES 79If 80.Fa mbchar 81is 82.Dv NULL , 83the 84.Fn mblen 85and 86.Fn mblen_l 87functions return nonzero if shift states are supported, 88zero otherwise. 89.Pp 90Otherwise, if 91.Fa mbchar 92is not a null pointer, 93.Fn mblen 94and 95.Fn mblen_l 96either return 0 if 97.Fa mbchar 98represents the null wide character, or return 99the number of bytes processed in 100.Fa mbchar , 101or return \-1 if no multibyte character 102could be recognized or converted. 103In this case, 104.Fn mblen Ns 's 105and 106.Fn mblen_l Ns 's 107internal conversion states are undefined. 108.Sh ERRORS 109The 110.Fn mblen 111and 112.Fn mblen_l 113functions will fail if: 114.Bl -tag -width Er 115.It Bq Er EILSEQ 116An invalid multibyte sequence was detected. 117.It Bq Er EINVAL 118The internal conversion state is not valid. 119.El 120.Sh SEE ALSO 121.Xr mbrlen 3 , 122.Xr mbtowc 3 , 123.Xr multibyte 3 , 124.Xr xlocale 3 125.Sh STANDARDS 126The 127.Fn mblen 128function conforms to 129.St -isoC-99 . 130