man1/iconv.1

   1 .\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com>
   2 .\"
   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.
   8 .\"
   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.
  13 .\"
  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.
  18 .\"
  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/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH ICONV 1 2020-06-09 "GNU" "Linux User Manual"
  25 .SH NAME
  26 iconv \- convert text from one character encoding to another
  27 .SH SYNOPSIS
  28 .B iconv
  29 .RI [ options ]
  30 .RI "[\-f " from-encoding "]"
  31 .RI "[\-t " to-encoding "]"
  32 .RI [ inputfile ]...
  33 .SH DESCRIPTION
  34 The
  35 .B iconv
  36 program reads in text in one encoding and outputs the text in another
  37 encoding.
  38 If no input files are given, or if it is given as a dash (\-),
  39 .B iconv
  40 reads from standard input.
  41 If no output file is given,
  42 .B iconv
  43 writes to standard output.
  44 .PP
  45 If no
  46 .I from-encoding
  47 is given, the default is derived
  48 from the current locale's character encoding.
  49 If no
  50 .I to-encoding
  51 is given, the default is derived
  52 from the current locale's character
  53 encoding.
  54 .SH OPTIONS
  55 .TP
  56 .BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding
  57 Use
  58 .I from-encoding
  59 for input characters.
  60 .TP
  61 .BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding
  62 Use
  63 .I to-encoding
  64 for output characters.
  65 .IP
  66 If the string
  67 .B //IGNORE
  68 is appended to
  69 .IR to-encoding ,
  70 characters that cannot be converted are discarded and an error is
  71 printed after conversion.
  72 .IP
  73 If the string
  74 .B //TRANSLIT
  75 is appended to
  76 .IR to-encoding ,
  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
  80 looking characters.
  81 Characters that are outside of the target character set and cannot be
  82 transliterated are replaced with a question mark (?) in the output.
  83 .TP
  84 .BR \-l ", " \-\-list
  85 List all known character set encodings.
  86 .TP
  87 .B "\-c"
  88 Silently discard characters that cannot be converted instead of
  89 terminating when encountering such characters.
  90 .TP
  91 .BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile
  92 Use
  93 .I outputfile
  94 for output.
  95 .TP
  96 .BR \-s ", " \-\-silent
  97 This option is ignored; it is provided only for compatibility.
  98 .TP
  99 .B "\-\-verbose"
 100 Print progress information on standard error when processing
 101 multiple files.
 102 .TP
 103 .BR \-? ", " \-\-help
 104 Print a usage summary and exit.
 105 .TP
 106 .B "\-\-usage"
 107 Print a short usage summary and exit.
 108 .TP
 109 .BR \-V ", " \-\-version
 110 Print the version number, license, and disclaimer of warranty for
 111 .BR iconv .
 112 .SH EXIT STATUS
 113 Zero on success, nonzero on errors.
 114 .SH ENVIRONMENT
 115 Internally, the
 116 .B iconv
 117 program uses the
 118 .BR iconv (3)
 119 function which in turn uses
 120 .I gconv
 121 modules (dynamically loaded shared libraries)
 122 to convert to and from a character set.
 123 Before calling
 124 .BR iconv (3),
 125 the
 126 .B iconv
 127 program must first allocate a conversion descriptor using
 128 .BR iconv_open (3).
 129 The operation of the latter function is influenced by the setting of the
 130 .B GCONV_PATH
 131 environment variable:
 132 .IP * 3
 133 If
 134 .B GCONV_PATH
 135 is not set,
 136 .BR iconv_open (3)
 137 loads the system gconv module configuration cache file created by
 138 .BR iconvconfig (8)
 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.
 143 .IP *
 144 If
 145 .B GCONV_PATH
 146 is defined (as a colon-separated list of pathnames),
 147 the system gconv module configuration cache is not used.
 148 Instead,
 149 .BR iconv_open (3)
 150 first tries to load the configuration files by searching the directories in
 151 .B GCONV_PATH
 152 in order,
 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
 161 .B GCONV_PATH
 162 is used.
 163 This allows users to use custom modules and even replace system-provided
 164 modules by providing such modules in
 165 .B GCONV_PATH
 166 directories.
 167 .SH FILES
 168 .TP
 169 .I /usr/lib/gconv
 170 Usual default gconv module path.
 171 .TP
 172 .I /usr/lib/gconv/gconv\-modules
 173 Usual system default gconv module configuration file.
 174 .TP
 175 .I /usr/lib/gconv/gconv\-modules.cache
 176 Usual system gconv module configuration cache.
 177 .SH CONFORMING TO
 178 POSIX.1-2001.
 179 .SH EXAMPLES
 180 Convert text from the ISO 8859-15 character encoding to UTF-8:
 181 .PP
 182 .in +4n
 183 .EX
 184 $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
 185 .EE
 186 .in
 187 .PP
 188 The next example converts from UTF-8 to ASCII, transliterating when
 189 possible:
 190 .PP
 191 .in +4n
 192 .EX
 193 $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP
 194 abc ss ? EUR abc
 195 .EE
 196 .in
 197 .SH SEE ALSO
 198 .BR locale (1),
 199 .BR uconv (1),
 200 .BR iconv (3),
 201 .BR nl_langinfo (3),
 202 .BR charsets (7),
 203 .BR iconvconfig (8)