lib/libc/locale/mbrlen.3

   1 .\" $NetBSD: mbrlen.3,v 1.8 2006/10/14 07:51:01 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 MBRLEN 3
  29 .Os
  30 .\" ----------------------------------------------------------------------
  31 .Sh NAME
  32 .Nm mbrlen
  33 .Nd get number of bytes in a multibyte character (restartable)
  34 .\" ----------------------------------------------------------------------
  35 .Sh LIBRARY
  36 .Lb libc
  37 .\" ----------------------------------------------------------------------
  38 .Sh SYNOPSIS
  39 .In wchar.h
  40 .Ft size_t
  41 .Fn mbrlen "const char * restrict s" "size_t n" "mbstate_t * restrict ps"
  42 .\" ----------------------------------------------------------------------
  43 .Sh DESCRIPTION
  44 The
  45 .Fn mbrlen
  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 .Fn mbrlen
  54 is equivalent to the following call (except
  55 .Fa ps
  56 is evaluated only once):
  57 .Bd -literal -offset indent
  58 mbrtowc(NULL, s, n, (ps != NULL) ? ps : \*[Am]internal);
  59 .Ed
  60 .Pp
  61 Here,
  62 .Fa internal
  63 is an internal state object.
  64 .Pp
  65 In state-dependent encodings,
  66 .Fa s
  67 may point to the special sequence bytes to change the shift-state.
  68 Although such sequence bytes corresponds to no individual
  69 wide-character code, these affect the conversion state object pointed
  70 to by
  71 .Fa ps ,
  72 and the
  73 .Fn mbrlen
  74 treats the special sequence bytes
  75 as if these are a part of the subsequent multibyte character.
  76 .Pp
  77 Unlike
  78 .Xr mblen 3 ,
  79 .Fn mbrlen
  80 may accept the byte sequence when it is not a complete character
  81 but possibly contains part of a valid character.
  82 In this case, this function will accept all such bytes
  83 and save them into the conversion state object pointed to by
  84 .Fa ps .
  85 They will be used on subsequent calls of this function to restart
  86 the conversion suspended.
  87 .Pp
  88 The behaviour of
  89 .Fn mbrlen
  90 is affected by the
  91 .Dv LC_CTYPE
  92 category of the current locale.
  93 .Pp
  94 These are the special cases:
  95 .Bl -tag -width 0123456789
  96 .It "s == NULL"
  97 .Fn mbrlen
  98 sets the conversion state object pointed to by
  99 .Fa ps
 100 to an initial state and always returns 0.
 101 Unlike
 102 .Xr mblen 3 ,
 103 the value returned does not indicate whether the current encoding of
 104 the locale is state-dependent.
 105 .Pp
 106 In this case,
 107 .Fn mbrlen
 108 ignores
 109 .Fa n .
 110 .It "n == 0"
 111 In this case,
 112 the first
 113 .Fa n
 114 bytes of the array pointed to by
 115 .Fa s
 116 never form a complete character.
 117 Thus,
 118 .Fn mbrlen
 119 always returns (size_t)-2.
 120 .It "ps == NULL"
 121 .Fn mbrlen
 122 uses its own internal state object to keep the conversion state,
 123 instead of
 124 .Fa ps
 125 mentioned in this manual page.
 126 .Pp
 127 Calling any other functions in
 128 .Lb libc
 129 never changes the internal
 130 state of
 131 .Fn mbrlen ,
 132 except for calling
 133 .Xr setlocale 3
 134 with a changing
 135 .Dv LC_CTYPE
 136 category of the current locale.
 137 Such
 138 .Xr setlocale 3
 139 calls cause the internal state of this function to be indeterminate.
 140 This internal state is initialized at startup time of the program.
 141 .El
 142 .\" ----------------------------------------------------------------------
 143 .Sh RETURN VALUES
 144 The
 145 .Fn mbrlen
 146 returns:
 147 .Bl -tag -width 0123456789
 148 .It "0"
 149 .Fa s
 150 points to a nul byte
 151 .Pq Sq \e0 .
 152 .It "positive"
 153 The value returned is
 154 a number of bytes for the valid multibyte character pointed to by
 155 .Fa s .
 156 There are no cases that this value is greater than
 157 .Fa n
 158 or the value of the
 159 .Dv MB_CUR_MAX
 160 macro.
 161 .It "(size_t)-2"
 162 .Fa s
 163 points to the byte sequence which possibly contains part of a valid
 164 multibyte character, but which is incomplete.
 165 When
 166 .Fa n
 167 is at least
 168 .Dv MB_CUR_MAX ,
 169 this case can only occur if the array pointed to by
 170 .Fa s
 171 contains a redundant shift sequence.
 172 .It "(size_t)-1"
 173 .Fa s
 174 points to an illegal byte sequence which does not form a valid multibyte
 175 character.
 176 In this case,
 177 .Fn mbrtowc
 178 sets
 179 .Va errno
 180 to indicate the error.
 181 .El
 182 .\" ----------------------------------------------------------------------
 183 .Sh ERRORS
 184 .Fn mbrlen
 185 may cause an error in the following case:
 186 .Bl -tag -width Er
 187 .It Bq Er EILSEQ
 188 .Fa s
 189 points to an invalid multibyte character.
 190 .It Bq Er EINVAL
 191 .Fa ps
 192 points to an invalid or uninitialized mbstate_t object.
 193 .El
 194 .\" ----------------------------------------------------------------------
 195 .Sh SEE ALSO
 196 .Xr mblen 3 ,
 197 .Xr mbrtowc 3 ,
 198 .Xr setlocale 3
 199 .\" ----------------------------------------------------------------------
 200 .Sh STANDARDS
 201 The
 202 .Fn mbrlen
 203 function conforms to
 204 .St -isoC-amd1 .
 205 The restrict qualifier is added at
 206 .St -isoC-99 .