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.1 2005/03/11 23:33:53 joerg 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 errno to indicate the error.
 164 .Pp
 165 Upon successful completion of
 166 .Fn iconv_close ,
 167 it returns 0.
 168 Otherwise,
 169 .Fn iconv_close
 170 returns \-1 and sets errno to indicate the error.
 171 .Pp
 172 Upon successful completion of
 173 .Fn iconv ,
 174 it returns the number of
 175 .Dq invalid
 176 conversions.
 177 Otherwise,
 178 .Fn iconv
 179 returns (size_t)\-1 and sets errno to indicate the error.
 180 .\" ----------------------------------------------------------------------
 181 .Sh ERRORS
 182 The
 183 .Fn iconv_open
 184 function may cause an error in the following cases:
 185 .Bl -tag -width Er
 186 .It Bq Er ENOMEM
 187 Memory is exhausted.
 188 .It Bq Er EINVAL
 189 There is no converter specified by
 190 .Fa srcname
 191 and
 192 .Fa dstname .
 193 .El
 194 .Pp
 195 The
 196 .Fn iconv_close
 197 function may cause an error in the following case:
 198 .Bl -tag -width Er
 199 .It Bq Er EBADF
 200 The conversion descriptor specified by
 201 .Fa cd
 202 is invalid.
 203 .El
 204 .Pp
 205 The
 206 .Fn iconv
 207 function may cause an error in the following cases:
 208 .Bl -tag -width Er
 209 .It Bq Er EBADF
 210 The conversion descriptor specified by
 211 .Fa cd
 212 is invalid.
 213 .It Bq Er EILSEQ
 214 The string pointed to by
 215 .Fa *src
 216 contains a byte sequence which does not describe a valid character of
 217 the source codeset.
 218 .It Bq Er E2BIG
 219 The output buffer pointed to by
 220 .Fa *dst
 221 is too small to store the result string.
 222 .It Bq Er EINVAL
 223 The string pointed to by
 224 .Fa *src
 225 terminates with an incomplete character or shift sequence.
 226 .El
 227 .\" ----------------------------------------------------------------------
 228 .Sh SEE ALSO
 229 .Xr iconv 1
 230 .\" ----------------------------------------------------------------------
 231 .Sh STANDARDS
 232 .Fn iconv_open ,
 233 .Fn iconv_close ,
 234 and
 235 .Fn iconv
 236 conform to
 237 .St -p1003.1-2001 .
 238 .\" ----------------------------------------------------------------------
 239 .Sh BUGS
 240 If
 241 .Fn iconv
 242 is aborted due to the occurrence of some error,
 243 the
 244 .Dq invalid conversion
 245 count mentioned above is unfortunately lost.