ICONV(1) Linux User Manual ICONV(1)
iconv - convert text from one character encoding to another
iconv [options] [-f from-encoding] [-t to-encoding] [inputfile]...
The iconv program reads in text in one encoding and outputs the text in
another encoding. If no input files are given, or if it is given as a
dash (-), iconv reads from standard input. If no output file is given,
iconv writes to standard output.
If no from-encoding is given, the default is derived from the current
locale's character encoding. If no to-encoding is given, the default
is derived from the current locale's character encoding.
-f from-encoding, --from-code=from-encoding
Use from-encoding for input characters.
-t to-encoding, --to-code=to-encoding
Use to-encoding for output characters.
If the string //IGNORE is appended to to-encoding, characters
that cannot be converted are discarded and an error is printed
If the string //TRANSLIT is appended to to-encoding, characters
being converted are transliterated when needed and possible.
This means that when a character cannot be represented in the
target character set, it can be approximated through one or sev-
eral similar looking characters. Characters that are outside of
the target character set and cannot be transliterated are
replaced with a question mark (?) in the output.
List all known character set encodings.
-c Silently discard characters that cannot be converted instead of
terminating when encountering such characters.
-o outputfile, --output=outputfile
Use outputfile for output.
This option is ignored; it is provided only for compatibility.
Print progress information on standard error when processing
Print a usage summary and exit.
Print a short usage summary and exit.
Print the version number, license, and disclaimer of warranty
Zero on success, non-zero on errors.
Internally, the iconv program uses the iconv(3) function which in turn
uses gconv modules (dynamically loaded shared libraries) to convert to
and from a character set. Before calling iconv(3), the iconv program
must first allocate a conversion descriptor using iconv_open(3). The
operation of the latter function is influenced by the setting of the
GCONV_PATH environment variable:
* If GCONV_PATH is not set, iconv_open(3) loads the system gconv mod-
ule configuration cache file created by iconvconfig(8) and then,
based on the configuration, loads the gconv modules needed to per-
form the conversion. If the system gconv module configuration cache
file is not available then the system gconv module configuration
file is used.
* If GCONV_PATH is defined (as a colon-separated list of pathnames),
the system gconv module configuration cache is not used. Instead,
iconv_open(3) first tries to load the configuration files by search-
ing the directories in GCONV_PATH in order, followed by the system
default gconv module configuration file. If a directory does not
contain a gconv module configuration file, any gconv modules that it
may contain are ignored. If a directory contains a gconv module
configuration file and it is determined that a module needed for
this conversion is available in the directory, then the needed mod-
ule is loaded from that directory, the order being such that the
first suitable module found in GCONV_PATH is used. This allows
users to use custom modules and even replace system-provided modules
by providing such modules in GCONV_PATH directories.
Usual default gconv module path.
Usual system default gconv module configuration file.
Usual system gconv module configuration cache.
Convert text from the ISO 8859-15 character encoding to UTF-8:
$ iconv -f ISO-8859-15 -t UTF-8 < input.txt > output.txt
The next example converts from UTF-8 to ASCII, transliterating when
$ echo abc B a EUR ac | iconv -f UTF-8 -t ASCII//TRANSLIT
abc ss ? EUR abc
locale(1), iconv(3), nl_langinfo(3), charsets(7), iconvconfig(8)
This page is part of release 4.14 of the Linux man-pages project. A
description of the project, information about reporting bugs, and the
latest version of this page, can be found at
GNU 2017-09-15 ICONV(1)