1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" References consulted:
9 .\" GNU glibc-2 source code and manual
10 .\" OpenGroup's Single Unix specification
11 .\" http://www.UNIX-systems.org/online.html
13 .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
14 .\" and //IGNORE extensions for 'tocode'.
16 .TH ICONV_OPEN 3 2008-08-11 "GNU" "Linux Programmer's Manual"
18 iconv_open \- allocate descriptor for character set conversion
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 \fIfromcode\fP to
30 character encoding \fItocode\fP.
32 The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
33 combinations are system-dependent.
34 For the GNU C library, the permitted
35 values are listed by the \fBiconv \-\-list\fP command, and all combinations
36 of the listed values are supported.
37 Furthermore the GNU C library and the
38 GNU libiconv library support the following two suffixes:
41 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
43 This means that when a character cannot be represented in the
44 target character set, it can be approximated through one or several
45 similarly looking characters.
48 When the string "//IGNORE" is appended to \fItocode\fP, characters that
49 cannot be represented in the target character set will be silently discarded.
51 The resulting conversion descriptor can be used with
54 It remains valid until deallocated using
57 A conversion descriptor contains a conversion state.
60 the state is in the initial state.
63 modifies the descriptor's conversion state.
64 (This implies that a conversion
65 descriptor can not be used in multiple threads simultaneously.)
66 To bring the state back to the initial state, use
68 with NULL as \fIinbuf\fP argument.
72 function returns a freshly allocated conversion
74 In case of error, it sets \fIerrno\fP and returns
77 The following error can occur, among others:
80 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
83 This function is available in glibc since version 2.1.