lib/libc/locale/mblen.3

   1 .\" $NetBSD: src/lib/libc/locale/mblen.3,v 1.5 2004/01/24 16:58:54 wiz Exp $
   2 .\" $DragonFly: src/lib/libc/locale/mblen.3,v 1.1 2005/03/12 00:18:01 joerg Exp $
   3 .\"
   4 .\" Copyright (c)2002 Citrus Project,
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd February 3, 2002
  29 .Dt MBLEN 3
  30 .Os
  31 .\" ----------------------------------------------------------------------
  32 .Sh NAME
  33 .Nm mblen
  34 .Nd get number of bytes in a multibyte character
  35 .\" ----------------------------------------------------------------------
  36 .Sh LIBRARY
  37 .Lb libc
  38 .\" ----------------------------------------------------------------------
  39 .Sh SYNOPSIS
  40 .In stdlib.h
  41 .Ft int
  42 .Fn mblen "const char *s" "size_t n"
  43 .\" ----------------------------------------------------------------------
  44 .Sh DESCRIPTION
  45 The
  46 .Fn mblen
  47 function usually determines the number of bytes in
  48 a multibyte character pointed to by
  49 .Fa s
  50 and returns it.
  51 This function shall only examine max n bytes of the array beginning from
  52 .Fa s .
  53 .Pp
  54 In state-dependent encodings,
  55 .Fa s
  56 may point the special sequence bytes to change the shift-state.
  57 Although such sequence bytes corresponds to no individual
  58 wide-character code,
  59 the
  60 .Fn mblen
  61 changes the own state by them and treats them
  62 as if they are a part of the subsequent multibyte character.
  63 .Pp
  64 Unlike
  65 .Xr mbrlen 3 ,
  66 the first
  67 .Fa n
  68 bytes pointed to by
  69 .Fa s
  70 need to form an entire multibyte character.
  71 Otherwise, this function causes an error.
  72 .Pp
  73 .Fn mblen
  74 is equivalent to the following call, except the internal state of the
  75 .Xr mbtowc 3
  76 function is not affected:
  77 .Bd -literal -offset indent
  78 mbtowc(NULL, s, n);
  79 .Ed
  80 .Pp
  81 Calling any other functions in
  82 .Lb libc
  83 never changes the internal
  84 state of
  85 .Fn mblen ,
  86 except for calling
  87 .Xr setlocale 3
  88 with the
  89 .Dv LC_CTYPE
  90 category changed to that of the current locale.
  91 Such
  92 .Xr setlocale 3
  93 calls cause the internal state of this function to be indeterminate.
  94 .Pp
  95 The behaviour of
  96 .Fn mblen
  97 is affected by the
  98 .Dv LC_CTYPE
  99 category of the current locale.
 100 .Pp
 101 These are the special cases:
 102 .Bl -tag -width 0123456789
 103 .It "s == NULL"
 104 .Fn mblen
 105 initializes its own internal state to an initial state, and
 106 determines whether the current encoding is state-dependent.
 107 This function returns 0 if the encoding is state-independent,
 108 otherwise non-zero.
 109 .It "n == 0"
 110 In this case,
 111 the first
 112 .Fa n
 113 bytes of the array pointed to by
 114 .Fa s
 115 never form a complete character.
 116 Thus,
 117 .Fn mblen
 118 always fails.
 119 .El
 120 .\" ----------------------------------------------------------------------
 121 .Sh RETURN VALUES
 122 Normally,
 123 .Fn mblen
 124 returns:
 125 .Bl -tag -width 0123456789
 126 .It "0"
 127 .Fa s
 128 points to a null byte
 129 .Pq Sq \e0 .
 130 .It "positive"
 131 The value returned is
 132 a number of bytes for the valid multibyte character pointed to by
 133 .Fa s .
 134 There are no cases that this value is greater than
 135 .Fa n
 136 or the value of the
 137 .Dv MB_CUR_MAX
 138 macro.
 139 .It "-1"
 140 .Fa s
 141 points to an invalid or incomplete multibyte character.
 142 The
 143 .Fn mblen
 144 also sets
 145 .Va errno
 146 to indicate the error.
 147 .El
 148 .Pp
 149 When
 150 .Fa s
 151 is equal to
 152 .Dv NULL ,
 153 the
 154 .Fn mblen
 155 returns:
 156 .Bl -tag -width 0123456789
 157 .It "0"
 158 The current encoding is state-independent.
 159 .It "non-zero"
 160 The current encoding is state-dependent.
 161 .El
 162 .\" ----------------------------------------------------------------------
 163 .Sh ERRORS
 164 .Fn mblen
 165 may cause an error in the following case:
 166 .Bl -tag -width Er
 167 .It Bq Er EILSEQ
 168 .Fa s
 169 points to an invalid or incomplete multibyte character.
 170 .El
 171 .\" ----------------------------------------------------------------------
 172 .Sh SEE ALSO
 173 .Xr mbrlen 3 ,
 174 .Xr mbtowc 3 ,
 175 .Xr setlocale 3
 176 .\" ----------------------------------------------------------------------
 177 .Sh STANDARDS
 178 The
 179 .Fn mblen
 180 function conforms to
 181 .St -ansiC .