1 '\" t -*- coding: UTF-8 -*-
3 .\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com>
5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, see
23 .\" <http://www.gnu.org/licenses/>.
26 .TH ICONV 1 2019-03-06 "GNU" "Linux User Manual"
28 iconv \- convert text from one character encoding to another
32 .RI "[\-f " from-encoding "]"
33 .RI "[\-t " to-encoding "]"
38 program reads in text in one encoding and outputs the text in another
40 If no input files are given, or if it is given as a dash (\-),
42 reads from standard input.
43 If no output file is given,
45 writes to standard output.
49 is given, the default is derived
50 from the current locale's character encoding.
53 is given, the default is derived
54 from the current locale's character
58 .BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding
63 .BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding
66 for output characters.
72 characters that cannot be converted are discarded and an error is
73 printed after conversion.
79 characters being converted are transliterated when needed and possible.
80 This means that when a character cannot be represented in the target
81 character set, it can be approximated through one or several similar
83 Characters that are outside of the target character set and cannot be
84 transliterated are replaced with a question mark (?) in the output.
87 List all known character set encodings.
90 Silently discard characters that cannot be converted instead of
91 terminating when encountering such characters.
93 .BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile
98 .BR \-s ", " \-\-silent
99 This option is ignored; it is provided only for compatibility.
102 Print progress information on standard error when processing
105 .BR \-? ", " \-\-help
106 Print a usage summary and exit.
109 Print a short usage summary and exit.
111 .BR \-V ", " \-\-version
112 Print the version number, license, and disclaimer of warranty for
115 Zero on success, nonzero on errors.
121 function which in turn uses
123 modules (dynamically loaded shared libraries)
124 to convert to and from a character set.
129 program must first allocate a conversion descriptor using
131 The operation of the latter function is influenced by the setting of the
133 environment variable:
139 loads the system gconv module configuration cache file created by
141 and then, based on the configuration,
142 loads the gconv modules needed to perform the conversion.
143 If the system gconv module configuration cache file is not available
144 then the system gconv module configuration file is used.
148 is defined (as a colon-separated list of pathnames),
149 the system gconv module configuration cache is not used.
152 first tries to load the configuration files by searching the directories in
155 followed by the system default gconv module configuration file.
156 If a directory does not contain a gconv module configuration file,
157 any gconv modules that it may contain are ignored.
158 If a directory contains a gconv module configuration file
159 and it is determined that a module needed for this conversion is
160 available in the directory,
161 then the needed module is loaded from that directory,
162 the order being such that the first suitable module found in
165 This allows users to use custom modules and even replace system-provided
166 modules by providing such modules in
172 Usual default gconv module path.
174 .I /usr/lib/gconv/gconv\-modules
175 Usual system default gconv module configuration file.
177 .I /usr/lib/gconv/gconv\-modules.cache
178 Usual system gconv module configuration cache.
182 Convert text from the ISO 8859-15 character encoding to UTF-8:
186 $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
190 The next example converts from UTF-8 to ASCII, transliterating when
195 $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP