lib/libc/iconv/iconv.3

   1 .\" $NetBSD: src/lib/libc/iconv/iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
   2 .\" $DragonFly: src/lib/libc/iconv/iconv.3,v 1.2 2007/06/30 19:03:52 swildner Exp $
   3 .\"
   4 .\" Copyright (c)2003 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 August 1, 2004
  29 .Dt ICONV 3
  30 .Os
  31 .\" ----------------------------------------------------------------------
  32 .Sh NAME
  33 .Nm iconv_open ,
  34 .Nm iconv_close ,
  35 .Nm iconv
  36 .Nd codeset conversion functions
  37 .\" ----------------------------------------------------------------------
  38 .Sh LIBRARY
  39 .Lb libc
  40 .\" ----------------------------------------------------------------------
  41 .Sh SYNOPSIS
  42 .In iconv.h
  43 .Ft iconv_t
  44 .Fn iconv_open "const char *dstname" "const char *srcname"
  45 .Ft int
  46 .Fn iconv_close "iconv_t cd"
  47 .Ft size_t
  48 .Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
  49 .\" ----------------------------------------------------------------------
  50 .Sh DESCRIPTION
  51 The
  52 .Fn iconv_open
  53 function opens a converter from the codeset
  54 .Fa srcname
  55 to the codeset
  56 .Fa dstname
  57 and returns its descriptor.
  58 .Pp
  59 The
  60 .Fn iconv_close
  61 function closes the specified converter
  62 .Fa cd .
  63 .Pp
  64 The
  65 .Fn iconv
  66 function converts the string in the buffer
  67 .Fa *src
  68 of length
  69 .Fa *srcleft
  70 bytes and stores the converted string in the buffer
  71 .Fa *dst
  72 of size
  73 .Fa *dstleft
  74 bytes.
  75 After calling
  76 .Fn iconv ,
  77 the values pointed to by
  78 .Fa src ,
  79 .Fa srcleft ,
  80 .Fa dst ,
  81 and
  82 .Fa dstleft
  83 are updated as follows:
  84 .Bl -tag -width 01234567
  85 .It *src
  86 Pointer to the byte just after the last character fetched.
  87 .It *srcleft
  88 Number of remaining bytes in the source buffer.
  89 .It *dst
  90 Pointer to the byte just after the last character stored.
  91 .It *dstleft
  92 Number of remainder bytes in the destination buffer.
  93 .El
  94 .Pp
  95 If the string pointed to by
  96 .Fa *src
  97 contains a byte sequence which is not a valid character in the source
  98 codeset, the conversion stops just after the last successful conversion.
  99 If the output buffer is too small to store the converted
 100 character, the conversion also stops in the same way.
 101 In these cases, the values pointed to by
 102 .Fa src ,
 103 .Fa srcleft ,
 104 .Fa dst ,
 105 and
 106 .Fa dstleft
 107 are updated to the state just after the last successful conversion.
 108 .Pp
 109 If the string pointed to by
 110 .Fa *src
 111 contains a character which is valid under the source codeset but
 112 can not be converted to the destination codeset,
 113 the character is replaced by an
 114 .Dq invalid character
 115 which depends on the destination codeset, e.g.,
 116 .Sq \&? ,
 117 and the conversion is continued.
 118 .Fn iconv
 119 returns the number of such
 120 .Dq invalid conversions .
 121 .Pp
 122 There are two special cases of
 123 .Fn iconv :
 124 .Bl -tag -width 0123
 125 .It "src == NULL || *src == NULL"
 126 .\"
 127 If the source and/or destination codesets are stateful,
 128 .Fn iconv
 129 places these into their initial state.
 130 .Pp
 131 If both
 132 .Fa dst
 133 and
 134 .Fa *dst
 135 are
 136 .No non- Ns Dv NULL ,
 137 .Fn iconv
 138 stores the shift sequence for the destination switching to the initial state
 139 in the buffer pointed to by
 140 .Fa *dst .
 141 The buffer size is specified by the value pointed to by
 142 .Fa dstleft
 143 as above.
 144 .Fn iconv
 145 will fail if the buffer is too small to store the shift sequence.
 146 .Pp
 147 On the other hand,
 148 .Fa dst
 149 or
 150 .Fa *dst
 151 may be
 152 .Dv NULL .
 153 In this case, the shift sequence for the destination switching
 154 to the initial state is discarded.
 155 .El
 156 .\" ----------------------------------------------------------------------
 157 .Sh RETURN VALUES
 158 Upon successful completion of
 159 .Fn iconv_open ,
 160 it returns a conversion descriptor.
 161 Otherwise,
 162 .Fn iconv_open
 163 returns (iconv_t)\-1 and sets
 164 .Va errno
 165 to indicate the error.
 166 .Pp
 167 Upon successful completion of
 168 .Fn iconv_close ,
 169 it returns 0.
 170 Otherwise,
 171 .Fn iconv_close
 172 returns \-1 and sets
 173 .Va errno
 174 to indicate the error.
 175 .Pp
 176 Upon successful completion of
 177 .Fn iconv ,
 178 it returns the number of
 179 .Dq invalid
 180 conversions.
 181 Otherwise,
 182 .Fn iconv
 183 returns (size_t)\-1 and sets
 184 .Va errno
 185 to indicate the error.
 186 .\" ----------------------------------------------------------------------
 187 .Sh ERRORS
 188 The
 189 .Fn iconv_open
 190 function may cause an error in the following cases:
 191 .Bl -tag -width Er
 192 .It Bq Er ENOMEM
 193 Memory is exhausted.
 194 .It Bq Er EINVAL
 195 There is no converter specified by
 196 .Fa srcname
 197 and
 198 .Fa dstname .
 199 .El
 200 .Pp
 201 The
 202 .Fn iconv_close
 203 function may cause an error in the following case:
 204 .Bl -tag -width Er
 205 .It Bq Er EBADF
 206 The conversion descriptor specified by
 207 .Fa cd
 208 is invalid.
 209 .El
 210 .Pp
 211 The
 212 .Fn iconv
 213 function may cause an error in the following cases:
 214 .Bl -tag -width Er
 215 .It Bq Er EBADF
 216 The conversion descriptor specified by
 217 .Fa cd
 218 is invalid.
 219 .It Bq Er EILSEQ
 220 The string pointed to by
 221 .Fa *src
 222 contains a byte sequence which does not describe a valid character of
 223 the source codeset.
 224 .It Bq Er E2BIG
 225 The output buffer pointed to by
 226 .Fa *dst
 227 is too small to store the result string.
 228 .It Bq Er EINVAL
 229 The string pointed to by
 230 .Fa *src
 231 terminates with an incomplete character or shift sequence.
 232 .El
 233 .\" ----------------------------------------------------------------------
 234 .Sh SEE ALSO
 235 .Xr iconv 1
 236 .\" ----------------------------------------------------------------------
 237 .Sh STANDARDS
 238 .Fn iconv_open ,
 239 .Fn iconv_close ,
 240 and
 241 .Fn iconv
 242 conform to
 243 .St -p1003.1-2001 .
 244 .\" ----------------------------------------------------------------------
 245 .Sh BUGS
 246 If
 247 .Fn iconv
 248 is aborted due to the occurrence of some error,
 249 the
 250 .Dq invalid conversion
 251 count mentioned above is unfortunately lost.