usr/src/man/man3c/iconv.3c

   1 '\" te
   2 .\" Portions Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved .
   4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   7 .\"  This notice shall appear on any product containing this material.
   8 .\" 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.
   9 .\" 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.
  10 .\" 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]
  11 .TH ICONV 3C "Oct 6, 2004"
  12 .SH NAME
  13 iconv \- code conversion function
  14 .SH SYNOPSIS
  15 .SS "Default"
  16 .LP
  17 .nf
  18 #include <iconv.h>
  19
  20 \fBextern size_t\fR \fBiconv\fR(\fBiconv_t\fR \fIcd\fR, \fBconst char **restrict\fR \fIinbuf\fR,
  21      \fBsize_t *restrict\fR \fIinbytesleft\fR, \fBchar **restrict\fR \fIoutbuf\fR,
  22      \fBsize_t *restrict\fR \fIoutbytesleft\fR);
  23 .fi
  24
  25 .SS "SUSv3"
  26 .LP
  27 .nf
  28 #include <iconv.h>
  29
  30 \fBsize_t\fR \fBiconv\fR(\fBiconv_t\fR \fIcd\fR, \fBchar **restrict\fR \fIinbuf\fR,
  31      \fBsize_t *restrict\fR \fIinbytesleft\fR, \fBchar **restrict\fR \fIoutbuf\fR,
  32      \fBsize_t *restrict\fR \fIoutbytesleft\fR);
  33 .fi
  34
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 The \fBiconv()\fR function converts the sequence of characters from one code
  39 set,  in the array specified by \fIinbuf\fR, into a sequence of corresponding
  40 characters in another code set, in the array specified by \fIoutbuf\fR. The
  41 code sets are those specified in the \fIiconv_open\fR(\|) call that returned
  42 the conversion descriptor, \fIcd\fR. The \fIinbuf\fR argument points to a
  43 variable that points to the first character in the input buffer and
  44 \fIinbytesleft\fR indicates the number of bytes to the end of the buffer to be
  45 converted. The \fIoutbuf\fR argument points to a variable that points to the
  46 first available byte in the output buffer and \fIoutbytesleft\fR indicates the
  47 number of the available bytes to the end of the buffer.
  48 .sp
  49 .LP
  50 For state-dependent encodings, the conversion descriptor \fIcd\fR is placed
  51 into its initial shift state by a call for which \fIinbuf\fR is a null pointer,
  52 or for which \fIinbuf\fR points to a null pointer. When \fBiconv()\fR is called
  53 in this way, and if  \fIoutbuf\fR is not a null pointer or a pointer to a null
  54 pointer, and \fIoutbytesleft\fR points to a positive value, \fBiconv()\fR will
  55 place, into the output buffer,  the byte sequence to change the output buffer
  56 to its initial shift state.  If the output buffer is not large enough to hold
  57 the entire reset sequence, \fBiconv()\fR will fail and set  \fIerrno\fR to
  58 \fBE2BIG\fR. Subsequent calls with \fIinbuf\fR as other than a null pointer or
  59 a pointer to a null pointer cause the  conversion to take place from the
  60 current state of the conversion descriptor.
  61 .sp
  62 .LP
  63 If a sequence of input bytes does not form a valid character in the specified
  64 code set, conversion stops  after the previous successfully converted
  65 character. If the input buffer ends with an incomplete character or shift
  66 sequence, conversion stops after the previous successfully converted bytes. If
  67 the output buffer is not large enough to hold the entire converted input,
  68 conversion stops just prior to the input bytes that would cause the output
  69 buffer to overflow. The variable pointed to by \fIinbuf\fR is updated to point
  70 to the byte following the last byte successfully used in the conversion.  The
  71 value pointed to by \fIinbytesleft\fR is decremented to reflect the number of
  72 bytes still not converted in the input buffer. The variable pointed to by
  73 \fIoutbuf\fR is updated to point to the byte following the last byte of
  74 converted output data. The value pointed to by \fIoutbytesleft\fR is
  75 decremented to reflect the number of bytes still available in the output
  76 buffer. For state-dependent encodings, the conversion descriptor is updated to
  77 reflect the shift state in effect at the end of the last  successfully
  78 converted byte sequence.
  79 .sp
  80 .LP
  81 If  \fBiconv()\fR encounters a character in the input buffer that is legal, but
  82 for which an identical character does not exist in the target code set,
  83 \fBiconv()\fR performs an implementation-defined conversion on this character.
  84 .SH RETURN VALUES
  85 .sp
  86 .LP
  87 The  \fBiconv()\fR function updates the variables pointed to by the arguments
  88 to reflect the extent of the conversion and returns the number of non-identical
  89 conversions performed.  If the entire string in the input buffer is converted,
  90 the value pointed to by \fIinbytesleft\fR will be \fB0\fR. If the input
  91 conversion is stopped due to any conditions mentioned above, the value pointed
  92 to by  \fIinbytesleft\fR will be non-zero and  \fBerrno\fR is set to indicate
  93 the condition.  If an error occurs \fBiconv()\fR returns \fB(size_t)\fR
  94 \fB\(mi1\fR and sets \fIerrno\fR to indicate the error.
  95 .SH ERRORS
  96 .sp
  97 .LP
  98 The \fBiconv()\fR function will fail if:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBEILSEQ\fR\fR
 103 .ad
 104 .RS 10n
 105 Input conversion stopped due to an input byte that does not belong to the input
 106 code set.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBE2BIG\fR\fR
 113 .ad
 114 .RS 10n
 115 Input conversion stopped due to lack of space in the output buffer.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBEINVAL\fR\fR
 122 .ad
 123 .RS 10n
 124 Input conversion stopped due to an incomplete  character or shift sequence at
 125 the end of the input buffer.
 126 .RE
 127
 128 .sp
 129 .LP
 130 The \fBiconv()\fR function may fail if:
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBEBADF\fR\fR
 135 .ad
 136 .RS 9n
 137 The \fIcd\fR argument is not a valid open conversion descriptor.
 138 .RE
 139
 140 .SH EXAMPLES
 141 .LP
 142 \fBExample 1 \fRUsing the \fBiconv()\fR Functions
 143 .sp
 144 .LP
 145 The following example uses the \fBiconv()\fR functions:
 146
 147 .sp
 148 .in +2
 149 .nf
 150 #include <stdio.h>
 151 #include <errno.h>
 152 #include <string.h>
 153 #include <iconv.h>
 154 #include <stdlib.h>
 155
 156 /*
 157  * For state-dependent encodings, changes the state of the
 158  * conversion descriptor to initial shift state.  Also, outputs
 159  * the byte sequence to change the state to initial state.
 160  * This code is assuming the iconv call for initializing the
 161  * state will not fail due to lack of space in the output buffer.
 162  */
 163 #define INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft) \e
 164     { \e
 165         fptr = NULL; \e
 166         ileft = 0; \e
 167         tptr = to; \e
 168         oleft = BUFSIZ; \e
 169         (void) iconv(cd, &fptr, &ileft, &tptr, &oleft); \e
 170         (void) fwrite(to, 1, BUFSIZ - oleft, stdout); \e
 171     }
 172
 173 int
 174 main(int argc, char **argv)
 175 {
 176     iconv_t cd;
 177     char    from[BUFSIZ], to[BUFSIZ];
 178     char    *from_code, *to_code;
 179     char    *tptr;
 180     const char  *fptr;
 181     size_t  ileft, oleft, num, ret;
 182
 183
 184     if (argc != 3) {
 185         (void) fprintf(stderr,
 186             "Usage: %s from_codeset to_codeset\e\en", argv[0]);
 187         return (1);
 188     }
 189
 190     from_code = argv[1];
 191     to_code = argv[2];
 192
 193     cd = iconv_open((const char *)to_code, (const char *)from_code);
 194     if (cd == (iconv_t)-1) {
 195         /*
 196          * iconv_open failed
 197          */
 198         (void) fprintf(stderr,
 199             "iconv_open(%s, %s) failed\e\en", to_code, from_code);
 200         return (1);
 201     }
 202
 203     ileft = 0;
 204     while ((ileft +=
 205         (num = fread(from + ileft, 1, BUFSIZ - ileft, stdin))) > 0) {
 206         if (num == 0) {
 207             /*
 208              * Input buffer still contains incomplete character
 209              * or sequence.  However, no more input character.
 210              */
 211
 212             /*
 213              * Initializes the conversion descriptor and outputs
 214              * the sequence to change the state to initial state.
 215              */
 216             INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
 217             (void) iconv_close(cd);
 218
 219             (void) fprintf(stderr, "Conversion error\e\en");
 220             return (1);
 221         }
 222
 223         fptr = from;
 224         for (;;) {
 225             tptr = to;
 226             oleft = BUFSIZ;
 227
 228             ret = iconv(cd, &fptr, &ileft, &tptr, &oleft);
 229             if (ret != (size_t)-1) {
 230                 /*
 231                  * iconv succeeded
 232                  */
 233
 234                 /*
 235                  * Outputs converted characters
 236                  */
 237                 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
 238                 break;
 239             }
 240
 241             /*
 242              * iconv failed
 243              */
 244             if (errno == EINVAL) {
 245                 /*
 246                * Incomplete character or shift sequence
 247                  */
 248
 249                 /*
 250                  * Outputs converted characters
 251                  */
 252                 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
 253                 /*
 254                  * Copies remaining characters in input buffer
 255                  * to the top of the input buffer.
 256                  */
 257                 (void) memmove(from, fptr, ileft);
 258                 /*
 259                  * Tries to fill input buffer from stdin
 260                  */
 261                 break;
 262             } else if (errno == E2BIG) {
 263                 /*
 264                  * Lack of space in output buffer
 265                  */
 266
 267                 /*
 268                  * Outputs converted characters
 269                  */
 270                 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
 271                 /*
 272                  * Tries to convert remaining characters in
 273                  * input buffer with emptied output buffer
 274                  */
 275                 continue;
 276             } else if (errno == EILSEQ) {
 277                 /*
 278                  * Illegal character or shift sequence
 279                  */
 280
 281                 /*
 282                  * Outputs converted characters
 283                  */
 284                 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
 285                 /*
 286                  * Initializes the conversion descriptor and
 287                  * outputs the sequence to change the state to
 288                  * initial state.
 289                  */
 290                 INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
 291                 (void) iconv_close(cd);
 292
 293                 (void) fprintf(stderr,
 294                  "Illegal character or sequence\e\en");
 295                 return (1);
 296             } else if (errno == EBADF) {
 297                 /*
 298                  * Invalid conversion descriptor.
 299                  * Actually, this shouldn't happen here.
 300                  */
 301                 (void) fprintf(stderr, "Conversion error\e\en");
 302                 return (1);
 303             } else {
 304                 /*
 305                  * This errno is not defined
 306                  */
 307                 (void) fprintf(stderr, "iconv error\e\en");
 308                 return (1);
 309             }
 310         }
 311     }
 312
 313     /*
 314      * Initializes the conversion descriptor and outputs
 315      * the sequence to change the state to initial state.
 316      */
 317     INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
 318
 319     (void) iconv_close(cd);
 320     return (0);
 321 }
 322 .fi
 323 .in -2
 324
 325 .SH FILES
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fB/usr/lib/iconv/*.so\fR\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 conversion modules for 32-bit
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fB/usr/lib/iconv/sparcv9/*.so\fR\fR
 340 .ad
 341 .sp .6
 342 .RS 4n
 343 conversion modules for 64-bit sparc
 344 .RE
 345
 346 .sp
 347 .ne 2
 348 .na
 349 \fB\fB/usr/lib/iconv/amd64/*.so\fR\fR
 350 .ad
 351 .sp .6
 352 .RS 4n
 353 conversion modules for 64-bit amd64
 354 .RE
 355
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fB/usr/lib/iconv/geniconvtbl/binarytables/*.bt\fR\fR
 360 .ad
 361 .sp .6
 362 .RS 4n
 363 conversion binary tables
 364 .RE
 365
 366 .SH ATTRIBUTES
 367 .sp
 368 .LP
 369 See \fBattributes\fR(5) for descriptions of the following attributes:
 370 .sp
 371
 372 .sp
 373 .TS
 374 box;
 375 c | c
 376 l | l .
 377 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 378 _
 379 Interface Stability     Standard
 380 _
 381 MT-Level        MT-Safe
 382 .TE
 383
 384 .SH SEE ALSO
 385 .sp
 386 .LP
 387 \fBgeniconvtbl\fR(1), \fBiconv\fR(1), \fBiconv_close\fR(3C),
 388 \fBiconv_open\fR(3C), \fBgeniconvtbl\fR(4), \fBattributes\fR(5),
 389 \fBiconv\fR(5), \fBiconv_unicode\fR(5), \fBstandards\fR(5)