1 .\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com>
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH ICONV 1 2021-08-27 "Linux man-pages (unreleased)"
7 iconv \- convert text from one character encoding to another
11 .RI "[\-f " from-encoding "]"
12 .RI "[\-t " to-encoding "]"
17 program reads in text in one encoding and outputs the text in another
19 If no input files are given, or if it is given as a dash (\-),
21 reads from standard input.
22 If no output file is given,
24 writes to standard output.
28 is given, the default is derived
29 from the current locale's character encoding.
32 is given, the default is derived
33 from the current locale's character
37 .BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding
42 .BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding
45 for output characters.
51 characters that cannot be converted are discarded and an error is
52 printed after conversion.
58 characters being converted are transliterated when needed and possible.
59 This means that when a character cannot be represented in the target
60 character set, it can be approximated through one or several similar
62 Characters that are outside of the target character set and cannot be
63 transliterated are replaced with a question mark (?) in the output.
66 List all known character set encodings.
69 Silently discard characters that cannot be converted instead of
70 terminating when encountering such characters.
72 .BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile
77 .BR \-s ", " \-\-silent
78 This option is ignored; it is provided only for compatibility.
81 Print progress information on standard error when processing
85 Print a usage summary and exit.
88 Print a short usage summary and exit.
90 .BR \-V ", " \-\-version
91 Print the version number, license, and disclaimer of warranty for
94 Zero on success, nonzero on errors.
100 function which in turn uses
102 modules (dynamically loaded shared libraries)
103 to convert to and from a character set.
108 program must first allocate a conversion descriptor using
110 The operation of the latter function is influenced by the setting of the
112 environment variable:
118 loads the system gconv module configuration cache file created by
120 and then, based on the configuration,
121 loads the gconv modules needed to perform the conversion.
122 If the system gconv module configuration cache file is not available
123 then the system gconv module configuration file is used.
127 is defined (as a colon-separated list of pathnames),
128 the system gconv module configuration cache is not used.
131 first tries to load the configuration files by searching the directories in
134 followed by the system default gconv module configuration file.
135 If a directory does not contain a gconv module configuration file,
136 any gconv modules that it may contain are ignored.
137 If a directory contains a gconv module configuration file
138 and it is determined that a module needed for this conversion is
139 available in the directory,
140 then the needed module is loaded from that directory,
141 the order being such that the first suitable module found in
144 This allows users to use custom modules and even replace system-provided
145 modules by providing such modules in
151 Usual default gconv module path.
153 .I /usr/lib/gconv/gconv\-modules
154 Usual system default gconv module configuration file.
156 .I /usr/lib/gconv/gconv\-modules.cache
157 Usual system gconv module configuration cache.
159 Depending on the architecture,
160 the above files may instead be located at directories with the path prefix
165 Convert text from the ISO 8859-15 character encoding to UTF-8:
169 $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
173 The next example converts from UTF-8 to ASCII, transliterating when
178 $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP