man3/iconv_open.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   OpenGroup's Single UNIX specification
  13 .\"     http://www.UNIX-systems.org/online.html
  14 .\"
  15 .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
  16 .\" and //IGNORE extensions for 'tocode'.
  17 .\"
  18 .TH ICONV_OPEN 3  2008-08-11 "GNU" "Linux Programmer's Manual"
  19 .SH NAME
  20 iconv_open \- allocate descriptor for character set conversion
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <iconv.h>
  24 .sp
  25 .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR iconv_open ()
  30 function allocates a conversion descriptor suitable
  31 for converting byte sequences from character encoding
  32 .I fromcode
  33 to
  34 character encoding
  35 .IR tocode .
  36 .PP
  37 The values permitted for
  38 .IR fromcode
  39 and
  40 .I tocode
  41 and the supported
  42 combinations are system-dependent.
  43 For the GNU C library, the permitted
  44 values are listed by the
  45 .I "iconv \-\-list"
  46 command, and all combinations
  47 of the listed values are supported.
  48 Furthermore the GNU C library and the
  49 GNU libiconv library support the following two suffixes:
  50 .TP
  51 //TRANSLIT
  52 When the string "//TRANSLIT" is appended to
  53 .IR tocode ,
  54 transliteration
  55 is activated.
  56 This means that when a character cannot be represented in the
  57 target character set, it can be approximated through one or several
  58 similarly looking characters.
  59 .TP
  60 //IGNORE
  61 When the string "//IGNORE" is appended to
  62 .IR tocode ,
  63 characters that
  64 cannot be represented in the target character set will be silently discarded.
  65 .PP
  66 The resulting conversion descriptor can be used with
  67 .BR iconv (3)
  68 any number of times.
  69 It remains valid until deallocated using
  70 .BR iconv_close (3).
  71 .PP
  72 A conversion descriptor contains a conversion state.
  73 After creation using
  74 .BR iconv_open (),
  75 the state is in the initial state.
  76 Using
  77 .BR iconv (3)
  78 modifies the descriptor's conversion state.
  79 (This implies that a conversion
  80 descriptor can not be used in multiple threads simultaneously.)
  81 To bring the state back to the initial state, use
  82 .BR iconv (3)
  83 with NULL as
  84 .I inbuf
  85 argument.
  86 .SH RETURN VALUE
  87 The
  88 .BR iconv_open ()
  89 function returns a freshly allocated conversion
  90 descriptor.
  91 In case of error, it sets
  92 .I errno
  93 and returns
  94 .IR (iconv_t)\ \-1 .
  95 .SH ERRORS
  96 The following error can occur, among others:
  97 .TP
  98 .B EINVAL
  99 The conversion from
 100 .IR fromcode
 101 to
 102 .I tocode
 103 is not supported by the
 104 implementation.
 105 .SH VERSIONS
 106 This function is available in glibc since version 2.1.
 107 .SH CONFORMING TO
 108 UNIX98, POSIX.1-2001.
 109 .SH SEE ALSO
 110 .BR iconv (1),
 111 .BR iconv (3),
 112 .BR iconv_close (3)