man1/iconv.1

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