lib/libc/iconv/iconv.3

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