man1/iconv.1

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