Debian Codegraph @

upstream/debian-unstable/man3/iconv_open.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH iconv_open 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 iconv_open \- allocate descriptor for character set conversion
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <iconv.h>
16 .P
17 .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR iconv_open ()
22 function allocates a conversion descriptor suitable
23 for converting byte sequences from character encoding
24 .I fromcode
25 to
26 character encoding
27 .IR tocode .
28 .P
29 The values permitted for
30 .I fromcode
31 and
32 .I tocode
33 and the supported
34 combinations are system-dependent.
35 For the GNU C library, the permitted
36 values are listed by the
37 .I "iconv \-\-list"
38 command, and all combinations
39 of the listed values are supported.
40 Furthermore the GNU C library and the
41 GNU libiconv library support the following two suffixes:
42 .TP
43 //TRANSLIT
44 When the string "//TRANSLIT" is appended to
45 .IR tocode ,
46 transliteration
47 is activated.
48 This means that when a character cannot be represented in the
49 target character set, it can be approximated through one or several
50 similarly looking characters.
51 .TP
52 //IGNORE
53 When the string "//IGNORE" is appended to
54 .IR tocode ,
55 characters that
56 cannot be represented in the target character set will be silently discarded.
57 .P
58 The resulting conversion descriptor can be used with
59 .BR iconv (3)
60 any number of times.
61 It remains valid until deallocated using
62 .BR iconv_close (3).
63 .P
64 A conversion descriptor contains a conversion state.
65 After creation using
66 .BR iconv_open (),
67 the state is in the initial state.
68 Using
69 .BR iconv (3)
70 modifies the descriptor's conversion state.
71 To bring the state back to the initial state, use
72 .BR iconv (3)
73 with NULL as
74 .I inbuf
75 argument.
76 .SH RETURN VALUE
77 On success,
78 .BR iconv_open ()
79 returns a freshly allocated conversion
80 descriptor.
81 On failure, it returns
82 .I (iconv_t)\ \-1
83 and sets
84 .I errno
85 to indicate the error.
86 .SH ERRORS
87 The following error can occur, among others:
88 .TP
89 .B EINVAL
90 The conversion from
91 .I fromcode
92 to
93 .I tocode
94 is not supported by the
95 implementation.
96 .SH ATTRIBUTES
97 For an explanation of the terms used in this section, see
98 .BR attributes (7).
99 .TS
100 allbox;
101 lbx lb lb
102 l l l.
103 Interface Attribute Value
104 T{
105 .na
106 .nh
107 .BR iconv_open ()
108 T} Thread safety MT-Safe locale
109 .TE
110 .SH STANDARDS
111 POSIX.1-2008.
112 .SH HISTORY
113 glibc 2.1.
114 POSIX.1-2001, SUSv2.
115 .SH SEE ALSO
116 .BR iconv (1),
117 .BR iconv (3),
118 .BR iconv_close (3)