1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\" References consulted:
6 .\" GNU glibc-2 source code and manual
7 .\" OpenGroup's Single UNIX specification
8 .\" http://www.UNIX-systems.org/online.html
10 .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
11 .\" and //IGNORE extensions for 'tocode'.
13 .TH ICONV_OPEN 3 2021-03-22 "GNU" "Linux Programmer's Manual"
15 iconv_open \- allocate descriptor for character set conversion
18 .RI ( libc ", " \-lc )
23 .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
28 function allocates a conversion descriptor suitable
29 for converting byte sequences from character encoding
35 The values permitted for
40 combinations are system-dependent.
41 For the GNU C library, the permitted
42 values are listed by the
44 command, and all combinations
45 of the listed values are supported.
46 Furthermore the GNU C library and the
47 GNU libiconv library support the following two suffixes:
50 When the string "//TRANSLIT" is appended to
54 This means that when a character cannot be represented in the
55 target character set, it can be approximated through one or several
56 similarly looking characters.
59 When the string "//IGNORE" is appended to
62 cannot be represented in the target character set will be silently discarded.
64 The resulting conversion descriptor can be used with
67 It remains valid until deallocated using
70 A conversion descriptor contains a conversion state.
73 the state is in the initial state.
76 modifies the descriptor's conversion state.
77 To bring the state back to the initial state, use
85 returns a freshly allocated conversion
87 On failure, it returns
91 to indicate the error.
93 The following error can occur, among others:
100 is not supported by the
103 This function is available in glibc since version 2.1.
105 For an explanation of the terms used in this section, see
113 Interface Attribute Value
116 T} Thread safety MT-Safe locale
122 POSIX.1-2001, POSIX.1-2008, SUSv2.