lib/libc/iconv/iconv.3

   1 .\" $FreeBSD: head/lib/libc/iconv/iconv.3 233509 2012-03-26 14:56:23Z joel $
   2 .\" $NetBSD: iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
   3 .\"
   4 .\" Copyright (c) 2003 Citrus Project,
   5 .\" Copyright (c) 2009, 2010 Gabor Kovesdan <gabor@FreeBSD.org>,
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .Dd September 19, 2013
  30 .Dt ICONV 3
  31 .Os
  32 .Sh NAME
  33 .Nm iconv_open ,
  34 .Nm iconv_open_into ,
  35 .Nm iconv_close ,
  36 .Nm iconv
  37 .Nd codeset conversion functions
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In iconv.h
  42 .Ft iconv_t
  43 .Fn iconv_open "const char *dstname" "const char *srcname"
  44 .Ft int
  45 .Fn iconv_open_into "const char *dstname" "const char *srcname" "iconv_allocation_t *ptr"
  46 .Ft int
  47 .Fn iconv_close "iconv_t cd"
  48 .Ft size_t
  49 .Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
  50 .Ft size_t
  51 .Fn __iconv "iconv_t cd" "const char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" "uint32_t flags" "size_t invalids"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn iconv_open
  55 function opens a converter from the codeset
  56 .Fa srcname
  57 to the codeset
  58 .Fa dstname
  59 and returns its descriptor.
  60 The arguments
  61 .Fa srcname
  62 and
  63 .Fa dstname
  64 accept "" and "char", which refer to the current locale encoding.
  65 .Pp
  66 The
  67 .Fn iconv_open_into
  68 creates a conversion descriptor on a preallocated space.
  69 The
  70 .Ft iconv_allocation_t
  71 is used as a spaceholder type when allocating such space.
  72 The
  73 .Fa dstname
  74 and
  75 .Fa srcname
  76 arguments are the same as in the case of
  77 .Fn iconv_open .
  78 The
  79 .Fa ptr
  80 argument is a pointer of
  81 .Ft iconv_allocation_t
  82 to the preallocated space.
  83 .Pp
  84 The
  85 .Fn iconv_close
  86 function closes the specified converter
  87 .Fa cd .
  88 .Pp
  89 The
  90 .Fn iconv
  91 function converts the string in the buffer
  92 .Fa *src
  93 of length
  94 .Fa *srcleft
  95 bytes and stores the converted string in the buffer
  96 .Fa *dst
  97 of size
  98 .Fa *dstleft
  99 bytes.
 100 After calling
 101 .Fn iconv ,
 102 the values pointed to by
 103 .Fa src ,
 104 .Fa srcleft ,
 105 .Fa dst ,
 106 and
 107 .Fa dstleft
 108 are updated as follows:
 109 .Bl -tag -width 01234567
 110 .It *src
 111 Pointer to the byte just after the last character fetched.
 112 .It *srcleft
 113 Number of remaining bytes in the source buffer.
 114 .It *dst
 115 Pointer to the byte just after the last character stored.
 116 .It *dstleft
 117 Number of remainder bytes in the destination buffer.
 118 .El
 119 .Pp
 120 If the string pointed to by
 121 .Fa *src
 122 contains a byte sequence which is not a valid character in the source
 123 codeset, the conversion stops just after the last successful conversion.
 124 If the output buffer is too small to store the converted
 125 character, the conversion also stops in the same way.
 126 In these cases, the values pointed to by
 127 .Fa src ,
 128 .Fa srcleft ,
 129 .Fa dst ,
 130 and
 131 .Fa dstleft
 132 are updated to the state just after the last successful conversion.
 133 .Pp
 134 If the string pointed to by
 135 .Fa *src
 136 contains a character which is valid under the source codeset but
 137 can not be converted to the destination codeset,
 138 the character is replaced by an
 139 .Dq invalid character
 140 which depends on the destination codeset, e.g.,
 141 .Sq \&? ,
 142 and the conversion is continued.
 143 .Fn iconv
 144 returns the number of such
 145 .Dq invalid conversions .
 146 .Pp
 147 There are two special cases of
 148 .Fn iconv :
 149 .Bl -tag -width 0123
 150 .It "src == NULL || *src == NULL"
 151 If the source and/or destination codesets are stateful,
 152 .Fn iconv
 153 places these into their initial state.
 154 .Pp
 155 If both
 156 .Fa dst
 157 and
 158 .Fa *dst
 159 are
 160 .No non- Ns Dv NULL ,
 161 .Fn iconv
 162 stores the shift sequence for the destination switching to the initial state
 163 in the buffer pointed to by
 164 .Fa *dst .
 165 The buffer size is specified by the value pointed to by
 166 .Fa dstleft
 167 as above.
 168 .Fn iconv
 169 will fail if the buffer is too small to store the shift sequence.
 170 .Pp
 171 On the other hand,
 172 .Fa dst
 173 or
 174 .Fa *dst
 175 may be
 176 .Dv NULL .
 177 In this case, the shift sequence for the destination switching
 178 to the initial state is discarded.
 179 .Pp
 180 .El
 181 The
 182 .Fn __iconv
 183 function works just like
 184 .Fn iconv
 185 but if
 186 .Fn iconv
 187 fails, the invalid character count is lost there.
 188 This is a not bug rather a limitation of
 189 .St -p1003.1-2008 ,
 190 so
 191 .Fn __iconv
 192 is provided as an alternative but non-standard interface.
 193 It also has a flags argument, where currently the following
 194 flags can be passed:
 195 .Bl -tag -width 0123
 196 .It __ICONV_F_HIDE_INVALID
 197 Skip invalid characters, instead of returning with an error.
 198 .El
 199 .Sh RETURN VALUES
 200 Upon successful completion of
 201 .Fn iconv_open ,
 202 it returns a conversion descriptor.
 203 Otherwise,
 204 .Fn iconv_open
 205 returns (iconv_t)\-1 and sets errno to indicate the error.
 206 .Pp
 207 Upon successful completion of
 208 .Fn iconv_open_into ,
 209 it returns 0.
 210 Otherwise,
 211 .Fn iconv_open_into
 212 returns \-1, and sets errno to indicate the error.
 213 .Pp
 214 Upon successful completion of
 215 .Fn iconv_close ,
 216 it returns 0.
 217 Otherwise,
 218 .Fn iconv_close
 219 returns \-1 and sets errno to indicate the error.
 220 .Pp
 221 Upon successful completion of
 222 .Fn iconv ,
 223 it returns the number of
 224 .Dq invalid
 225 conversions.
 226 Otherwise,
 227 .Fn iconv
 228 returns (size_t)\-1 and sets errno to indicate the error.
 229 .Sh ERRORS
 230 The
 231 .Fn iconv_open
 232 function may cause an error in the following cases:
 233 .Bl -tag -width Er
 234 .It Bq Er ENOMEM
 235 Memory is exhausted.
 236 .It Bq Er EINVAL
 237 There is no converter specified by
 238 .Fa srcname
 239 and
 240 .Fa dstname .
 241 .El
 242 The
 243 .Fn iconv_open_into
 244 function may cause an error in the following cases:
 245 .Bl -tag -width Er
 246 .It Bq Er EINVAL
 247 There is no converter specified by
 248 .Fa srcname
 249 and
 250 .Fa dstname .
 251 .El
 252 .Pp
 253 The
 254 .Fn iconv_close
 255 function may cause an error in the following case:
 256 .Bl -tag -width Er
 257 .It Bq Er EBADF
 258 The conversion descriptor specified by
 259 .Fa cd
 260 is invalid.
 261 .El
 262 .Pp
 263 The
 264 .Fn iconv
 265 function may cause an error in the following cases:
 266 .Bl -tag -width Er
 267 .It Bq Er EBADF
 268 The conversion descriptor specified by
 269 .Fa cd
 270 is invalid.
 271 .It Bq Er EILSEQ
 272 The string pointed to by
 273 .Fa *src
 274 contains a byte sequence which does not describe a valid character of
 275 the source codeset.
 276 .It Bq Er E2BIG
 277 The output buffer pointed to by
 278 .Fa *dst
 279 is too small to store the result string.
 280 .It Bq Er EINVAL
 281 The string pointed to by
 282 .Fa *src
 283 terminates with an incomplete character or shift sequence.
 284 .El
 285 .Sh SEE ALSO
 286 .Xr iconv 1 ,
 287 .Xr mkcsmapper 1 ,
 288 .Xr mkesdb 1
 289 .Sh STANDARDS
 290 The
 291 .Fn iconv_open ,
 292 .Fn iconv_close ,
 293 and
 294 .Fn iconv
 295 functions conform to
 296 .St -p1003.1-2008 .
 297 .Pp
 298 The
 299 .Fn iconv_open_into
 300 function is a GNU-specific extension and it is not part of any standard,
 301 thus its use may break portability.
 302 The
 303 .Fn __iconv
 304 function is an own extension and it is not part of any standard,
 305 thus its use may break portability.