lib/libc/locale/mblen.3

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