Debian Codegraph @

upstream/debian-trixie/man3/iconv_open.3

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