lib/libc/locale/mbrlen.3

   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 .\" $FreeBSD: head/lib/libc/locale/mbrlen.3 131360 2004-06-30 19:32:41Z ru $
  26 .\"
  27 .Dd December 26, 2013
  28 .Dt MBRLEN 3
  29 .Os
  30 .Sh NAME
  31 .Nm mbrlen ,
  32 .Nm mbrlen_l
  33 .Nd "get number of bytes in a character (restartable)"
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In wchar.h
  38 .Ft size_t
  39 .Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
  40 .In xlocale.h
  41 .Ft size_t
  42 .Fn mbrlen_l "const char * restrict s" "size_t n" "mbstate_t * restrict ps" "locale_t locale"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn mbrlen
  46 and
  47 .Fn mbrlen_l
  48 functions inspect at most
  49 .Fa n
  50 bytes pointed to by
  51 .Fa s
  52 to determine the number of bytes needed to complete the next
  53 multibyte character.
  54 .Pp
  55 The
  56 .Vt mbstate_t
  57 argument,
  58 .Fa ps ,
  59 is used to keep track of the shift state.
  60 If it is
  61 .Dv NULL ,
  62 .Fn mbrlen
  63 and
  64 .Fn mbrlen_l
  65 use an internal, static
  66 .Vt mbstate_t
  67 object, which is initialized to the initial conversion state
  68 at program startup.
  69 .Pp
  70 It is equivalent to:
  71 .Pp
  72 .Dl "mbrtowc(NULL, s, n, ps);"
  73 .Pp
  74 Except that when
  75 .Fa ps
  76 is a
  77 .Dv NULL
  78 pointer,
  79 .Fn mbrlen
  80 and
  81 .Fn mbrlen_l
  82 use their own static, internal
  83 .Vt mbstate_t
  84 object to keep track of the shift state.
  85 .Pp
  86 The
  87 .Fn mbrlen_l
  88 function takes an explicit
  89 .Fa locale
  90 argument, whereas the
  91 .Fn mbrlen
  92 function uses the current global or per-thread locale.
  93 .Sh RETURN VALUES
  94 The
  95 .Fn mbrlen
  96 and
  97 .Fn mbrlen_l
  98 functions return:
  99 .Bl -tag -width indent
 100 .It 0
 101 The next
 102 .Fa n
 103 or fewer bytes
 104 represent the null wide character
 105 .Pq Li "L'\e0'" .
 106 .It >0
 107 The next
 108 .Fa n
 109 or fewer bytes
 110 represent a valid character,
 111 .Fn mbrlen
 112 and
 113 .Fn mbrlen_l
 114 return the number of bytes used to complete the multibyte character.
 115 .It Po Vt size_t Pc Ns \-2
 116 The next
 117 .Fa n
 118 contribute to, but do not complete, a valid multibyte character sequence,
 119 and all
 120 .Fa n
 121 bytes have been processed.
 122 .It Po Vt size_t Pc Ns \-1
 123 An encoding error has occurred.
 124 The next
 125 .Fa n
 126 or fewer bytes do not contribute to a valid multibyte character.
 127 .El
 128 .Sh EXAMPLES
 129 A function that calculates the number of characters in a multibyte
 130 character string:
 131 .Bd -literal -offset indent
 132 size_t
 133 nchars(const char *s)
 134 {
 135         size_t charlen, chars;
 136         mbstate_t mbs;
 137
 138         chars = 0;
 139         memset(&mbs, 0, sizeof(mbs));
 140         while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 &&
 141             charlen != (size_t)-1 && charlen != (size_t)-2) {
 142                 s += charlen;
 143                 chars++;
 144         }
 145
 146         return (chars);
 147 }
 148 .Ed
 149 .Sh ERRORS
 150 The
 151 .Fn mbrlen
 152 and
 153 .Fn mbrlen_l
 154 functions will fail if:
 155 .Bl -tag -width Er
 156 .It Bq Er EILSEQ
 157 An invalid multibyte sequence was detected.
 158 .It Bq Er EINVAL
 159 The conversion state is invalid.
 160 .El
 161 .Sh SEE ALSO
 162 .Xr mblen 3 ,
 163 .Xr mbrtowc 3 ,
 164 .Xr multibyte 3 ,
 165 .Xr xlocale 3
 166 .Sh STANDARDS
 167 The
 168 .Fn mbrlen
 169 function conforms to
 170 .St -isoC-99 .