lib/libc/locale/mbrlen.3

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