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  2021-03-22 "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 .PP
  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 To bring the state back to the initial state, use
  80 .BR iconv (3)
  81 with NULL as
  82 .I inbuf
  83 argument.
  84 .SH RETURN VALUE
  85 On success,
  86 .BR iconv_open ()
  87 returns a freshly allocated conversion
  88 descriptor.
  89 On failure, it returns
  90 .IR (iconv_t)\ \-1
  91 and sets
  92 .I errno
  93 to indicate the error.
  94 .SH ERRORS
  95 The following error can occur, among others:
  96 .TP
  97 .B EINVAL
  98 The conversion from
  99 .IR fromcode
 100 to
 101 .I tocode
 102 is not supported by the
 103 implementation.
 104 .SH VERSIONS
 105 This function is available in glibc since version 2.1.
 106 .SH ATTRIBUTES
 107 For an explanation of the terms used in this section, see
 108 .BR attributes (7).
 109 .ad l
 110 .nh
 111 .TS
 112 allbox;
 113 lbx lb lb
 114 l l l.
 115 Interface       Attribute       Value
 116 T{
 117 .BR iconv_open ()
 118 T}      Thread safety   MT-Safe locale
 119 .TE
 120 .hy
 121 .ad
 122 .sp 1
 123 .SH CONFORMING TO
 124 POSIX.1-2001, POSIX.1-2008, SUSv2.
 125 .SH SEE ALSO
 126 .BR iconv (1),
 127 .BR iconv (3),
 128 .BR iconv_close (3)