share/man/man9f/kiconv.9f

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KICONV 9F "Oct 16, 2007"
   7 .SH NAME
   8 kiconv \- buffer-based code conversion function
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/errno.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBsize_t\fR \fBkiconv\fR(\fBkiconv_t\fR \fIcd\fR, \fBchar **\fR\fIinbuf\fR, \fBsize_t *\fR\fIinbytesleft\fR,
  19      \fBchar **\fR\fIoutbuf\fR, \fBsize_t *\fR\fIoutbytesleft\fR, \fBint *\fR\fIerrno\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .LP
  29 The parameters for the \fBkiconv\fR function are as follows:
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIcd\fR\fR
  34 .ad
  35 .RS 16n
  36 Code conversion descriptor indicating the code conversion and conversion state.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIinbuf\fR\fR
  43 .ad
  44 .RS 16n
  45 Points to an address of a buffer containing a sequence of character bytes in
  46 \fBfromcode\fR codeset to be converted. After the conversion, the variable is
  47 updated to point to the byte following the last byte that was successfully used
  48 in the conversion.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIinbytesleft\fR\fR
  55 .ad
  56 .RS 16n
  57 As an input parameter, the number of bytes to be converted in \fIinbuf\fR. As
  58 an output parameter, the number of bytes in \fIinbuf\fR still not converted
  59 after the conversion.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIoutbuf\fR\fR
  66 .ad
  67 .RS 16n
  68 Points to an address of a buffer where converted character bytes in
  69 \fBtocode\fR codeset can be saved. After the conversion, the variable is
  70 updated to point to the byte following the last byte of converted output data.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIoutbytesleft\fR\fR
  77 .ad
  78 .RS 16n
  79 As an input parameter, the number of available bytes at \fIoutbuf\fR where
  80 converted character bytes can be saved. As an output parameter, the number of
  81 bytes still available at \fIoutbuf\fR after the conversion.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIerrno\fR\fR
  88 .ad
  89 .RS 16n
  90 Indicates the error when conversion is not completed or failed. The following
  91 are possible values:
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBEILSEQ\fR\fR
  96 .ad
  97 .RS 13n
  98 The input conversion was stopped due to an input byte that does not belong to
  99 the input codeset.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBE2BIG\fR\fR
 106 .ad
 107 .RS 13n
 108 The input conversion was stopped due to lack of space in the output buffer.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBEINVAL\fR\fR
 115 .ad
 116 .RS 13n
 117 The input conversion was stopped due to an incomplete character or shift
 118 sequence at the end of the input buffer.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEBADF\fR\fR
 125 .ad
 126 .RS 13n
 127 The \fIcd\fR input parameter is not a valid open code conversion descriptor.
 128 .RE
 129
 130 .RE
 131
 132 .SH DESCRIPTION
 133 .sp
 134 .LP
 135 The \fBkiconv()\fR function converts the sequence of characters from one
 136 \fBcodeset\fR, in the array specified by \fIinbuf\fR, into a sequence of
 137 corresponding characters in another \fBcodeset\fR, in the array specified by
 138 \fIoutbuf\fR. The \fBcodesets\fR are those specified in the \fBkiconv_open()\fR
 139 call that returned the code conversion descriptor, \fIcd\fR. The \fIinbuf\fR
 140 parameter points to a variable that points to the first character in the input
 141 buffer and \fIinbytesleft\fR indicates the number of bytes to the end of the
 142 buffer to be converted. The \fIoutbuf\fR parameter points to a variable that
 143 points to the first available byte in the output buffer and \fIoutbytesleft\fR
 144 indicates the number of the available bytes to the end of the buffer.
 145 .sp
 146 .LP
 147 For state-dependent encodings, the conversion descriptor \fIcd\fR is placed
 148 into its initial shift state by a call for which \fIinbuf\fR is a null pointer,
 149 or for which \fIinbuf\fR points to a null pointer. When \fBkiconv()\fR is
 150 called in this way, and if \fIoutbuf\fR is not a null pointer or a pointer to a
 151 null pointer, and \fIoutbytesleft\fR points to a positive value, \fBkiconv()\fR
 152 places, if any, into the output buffer, the byte sequence to change the output
 153 buffer to its initial shift state. If the output buffer is not large enough to
 154 hold the entire reset sequence, \fBkiconv()\fR fails and sets \fIerrno\fR to
 155 \fBE2BIG\fR. Subsequent calls with \fIinbuf\fR as other than a null pointer or
 156 a pointer to a null pointer cause the conversion to take place from the current
 157 state of the conversion descriptor.
 158 .sp
 159 .LP
 160 If a sequence of input bytes does not form a valid character in the specified
 161 \fBcodeset\fR, conversion stops after the previous successfully converted
 162 character. If the input buffer ends with an incomplete character or shift
 163 sequence, conversion stops after the previous successfully converted bytes. If
 164 the output buffer is not large enough to hold the entire converted input,
 165 conversion stops just prior to the input bytes that would cause the output
 166 buffer to overflow. The variable pointed to by \fIinbuf\fR is updated to point
 167 to the byte following the last byte that was successfully used in the
 168 conversion. The value pointed to by \fIinbytesleft\fR is decremented to reflect
 169 the number of bytes still not converted in the input buffer. The variable
 170 pointed to by \fIoutbuf\fR is updated to point to the byte following the last
 171 byte of converted output data. The value pointed to by \fIoutbytesleft\fR is
 172 decremented to reflect the number of bytes still available in the output
 173 buffer. For state-dependent encodings, the conversion descriptor is updated to
 174 reflect the shift state in effect at the end of the last successfully converted
 175 byte sequence.
 176 .sp
 177 .LP
 178 If \fBkiconv()\fR encounters a character in the input buffer that is legal, but
 179 for which an identical character does not exist in the target \fBcodeset\fR,
 180 \fBkiconv()\fR performs an implementation-defined conversion (that is, a
 181 non-identical conversion) on this character.
 182 .SH RETURN VALUES
 183 .sp
 184 .LP
 185 The \fBkiconv()\fR function updates the variables pointed to by the parameters
 186 to reflect the extent of the conversion and returns the number of non-identical
 187 conversions performed. If the entire string in the input buffer is converted,
 188 the value pointed to by \fIinbytesleft\fR is 0. If the input conversion is
 189 stopped due to any conditions mentioned above, the value pointed to by
 190 \fIinbytesleft\fR is non-zero and \fIerrno\fR is set to indicate the condition.
 191 If such and other error occurs, \fBkiconv()\fR returns (\fBsize_t\fR)-1 and
 192 sets \fIerrno\fR to indicate the error.
 193 .SH CONTEXT
 194 .sp
 195 .LP
 196 \fBkiconv()\fR can be called from user or interrupt context.
 197 .SH EXAMPLES
 198 .LP
 199 \fBExample 1 \fRPerforming a Simple Conversion
 200 .sp
 201 .LP
 202 The following example shows how to perform a simple conversion using
 203 \fBkiconv()\fR with a limited size of output buffer:
 204
 205 .sp
 206 .in +2
 207 .nf
 208 #include <sys/types.h>
 209 #include <sys/errno.h>
 210 #include <sys/sunddi.h>
 211
 212 int
 213 doconversion(char *fromcode, char *tocode, char *inbuf, char *outbuf,
 214                 size_t inlen, size_t *outlen)
 215 {
 216         kiconv_t cd;
 217         size_t ileft, ret;
 218         int err;
 219
 220         cd = kiconv_open((const char *)tocode, (const char *)fromcode);
 221         if (cd == (kiconv_t)-1) {
 222                /* Cannot open conversion. */
 223                return (-1);
 224         }
 225
 226         ret = kiconv(cd, &inbuf, &inlen, &outbuf, outlen, &err);
 227         if (ret == (size_t)-1)
 228                 goto doconv_error_return;
 229
 230         /*
 231          * Reset the conversion descriptor. This will also
 232          * make sure to write to output buffer any saved bytes
 233          * in the conversion descriptor state.
 234          */
 235         ileft = 0;
 236         ret = kiconv(cd, NULL, &ileft, &outbuf, outlen, &err);
 237         if (ret == (size_t)-1)
 238                 goto doconv_error_return;
 239
 240         (void) kiconv_close(cd);
 241
 242         return (0);
 243
 244 doconv_error_return:
 245         (void) kiconv_close(cd);
 246
 247         /* Need more output buffer. */
 248         if (err == E2BIG)
 249                 return (-2);
 250
 251         /* Illegal sequence? */
 252         if (err == EILSEQ)
 253                 return (-3);
 254
 255         /* Incomplete character? */
 256         if (err == EINVAL)
 257                 return (-4);
 258
 259         /*
 260          * Bad code conversion descriptor or any other unknown error.
 261          */
 262         return (-5);
 263 }
 264 .fi
 265 .in -2
 266
 267 .SH ATTRIBUTES
 268 .sp
 269 .LP
 270 See \fBattributes\fR(5) for descriptions of the following attributes:
 271 .sp
 272
 273 .sp
 274 .TS
 275 box;
 276 c | c
 277 l | l .
 278 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 279 _
 280 Interface Stability     Committed
 281 .TE
 282
 283 .SH SEE ALSO
 284 .sp
 285 .LP
 286 \fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C),
 287 \fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C),
 288 \fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C),
 289 \fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C),
 290 \fBattributes\fR(5), \fBkiconvstr\fR(9F), \fBkiconv_close\fR(9F),
 291 \fBkiconv_open\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F),
 292 \fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F),
 293 \fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F),
 294 \fBuconv_u8tou32\fR(9F)
 295 .sp
 296 .LP
 297 The Unicode Standard:
 298 .sp
 299 .LP
 300 http://www.unicode.org/standard/standard.html
 301 .SH NOTES
 302 .sp
 303 .LP
 304 The \fBiconv\fR(3C) man page also has a good example code that can be
 305 referenced.