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