1 .\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com>
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
24 .TH ICONV 1 2020-06-09 "GNU" "Linux User Manual"
26 iconv \- convert text from one character encoding to another
30 .RI "[\-f " from-encoding "]"
31 .RI "[\-t " to-encoding "]"
36 program reads in text in one encoding and outputs the text in another
38 If no input files are given, or if it is given as a dash (\-),
40 reads from standard input.
41 If no output file is given,
43 writes to standard output.
47 is given, the default is derived
48 from the current locale's character encoding.
51 is given, the default is derived
52 from the current locale's character
56 .BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding
61 .BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding
64 for output characters.
70 characters that cannot be converted are discarded and an error is
71 printed after conversion.
77 characters being converted are transliterated when needed and possible.
78 This means that when a character cannot be represented in the target
79 character set, it can be approximated through one or several similar
81 Characters that are outside of the target character set and cannot be
82 transliterated are replaced with a question mark (?) in the output.
85 List all known character set encodings.
88 Silently discard characters that cannot be converted instead of
89 terminating when encountering such characters.
91 .BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile
96 .BR \-s ", " \-\-silent
97 This option is ignored; it is provided only for compatibility.
100 Print progress information on standard error when processing
103 .BR \-? ", " \-\-help
104 Print a usage summary and exit.
107 Print a short usage summary and exit.
109 .BR \-V ", " \-\-version
110 Print the version number, license, and disclaimer of warranty for
113 Zero on success, nonzero on errors.
119 function which in turn uses
121 modules (dynamically loaded shared libraries)
122 to convert to and from a character set.
127 program must first allocate a conversion descriptor using
129 The operation of the latter function is influenced by the setting of the
131 environment variable:
137 loads the system gconv module configuration cache file created by
139 and then, based on the configuration,
140 loads the gconv modules needed to perform the conversion.
141 If the system gconv module configuration cache file is not available
142 then the system gconv module configuration file is used.
146 is defined (as a colon-separated list of pathnames),
147 the system gconv module configuration cache is not used.
150 first tries to load the configuration files by searching the directories in
153 followed by the system default gconv module configuration file.
154 If a directory does not contain a gconv module configuration file,
155 any gconv modules that it may contain are ignored.
156 If a directory contains a gconv module configuration file
157 and it is determined that a module needed for this conversion is
158 available in the directory,
159 then the needed module is loaded from that directory,
160 the order being such that the first suitable module found in
163 This allows users to use custom modules and even replace system-provided
164 modules by providing such modules in
170 Usual default gconv module path.
172 .I /usr/lib/gconv/gconv\-modules
173 Usual system default gconv module configuration file.
175 .I /usr/lib/gconv/gconv\-modules.cache
176 Usual system gconv module configuration cache.
180 Convert text from the ISO 8859-15 character encoding to UTF-8:
184 $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
188 The next example converts from UTF-8 to ASCII, transliterating when
193 $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP