Debian Codegraph @

upstream/debian-unstable/man1/iconv.1

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .TH iconv 1 2025-09-21 "Linux man-pages 6.18"
6 .SH NAME
7 iconv \- convert text from one character encoding to another
8 .SH SYNOPSIS
9 .SY iconv
10 .RI [ options ]
11 .RI [\f[B]\-f\f[]\~ from-encoding ]
12 .RI [\f[B]\-t\f[]\~ to-encoding ]
13 .RI [ inputfile \~.\|.\|.]
14 .YS
15 .SH DESCRIPTION
16 The
17 .B iconv
18 program reads in text in one encoding and outputs the text in another
19 encoding.
20 If no input files are given, or if it is given as a dash (\-),
21 .B iconv
22 reads from standard input.
23 If no output file is given,
24 .B iconv
25 writes to standard output.
26 .P
27 If no
28 .I from-encoding
29 is given, the default is derived
30 from the current locale's character encoding.
31 If no
32 .I to-encoding
33 is given, the default is derived
34 from the current locale's character
35 encoding.
36 .SH OPTIONS
37 .TP
38 .BI \-\-from\-code= from-encoding
39 .TQ
40 .BI \-f\~ from-encoding
41 Use
42 .I from-encoding
43 for input characters.
44 .TP
45 .BI \-\-to\-code= to-encoding
46 .TQ
47 .BI \-t\~ to-encoding
48 Use
49 .I to-encoding
50 for output characters.
51 .IP
52 If the string
53 .B //IGNORE
54 is appended to
55 .IR to-encoding ,
56 characters that cannot be converted are discarded and an error is
57 printed after conversion.
58 (Characters that cannot be decoded are treated as an error
59 with or without this flag.)
60 .IP
61 If the string
62 .B //TRANSLIT
63 is appended to
64 .IR to-encoding ,
65 characters being converted are transliterated when needed and possible.
66 This means that when a character cannot be represented in the target
67 character set, it can be approximated through one or several similar
68 looking characters.
69 Characters that are outside of the target character set and cannot be
70 transliterated are replaced with a question mark (?) in the output.
71 .TP
72 .B \-\-list
73 .TQ
74 .B \-l
75 List all known character set encodings.
76 .TP
77 .B \-c
78 Discard characters that cannot be converted instead of
79 terminating when encountering such characters.
80 .\" glibc commit 6cbf845fcdc76131d0e674cee454fe738b69c69d
81 POSIX requires that this option does not change
82 the exit status of the program.
83 .TP
84 .BI \-\-output= outputfile
85 .TQ
86 .BI \-o\~ outputfile
87 Use
88 .I outputfile
89 for output.
90 .TP
91 .B \-\-silent
92 .TQ
93 .B \-s
94 This option is ignored;
95 it is provided only for compatibility.
96 .TP
97 .B \-\-verbose
98 Print progress information on standard error when processing
99 multiple files.
100 .TP
101 .B \-\-help
102 .TQ
103 .B \-?
104 Print a usage summary and exit.
105 .TP
106 .B \-\-usage
107 Print a short usage summary and exit.
108 .TP
109 .B \-\-version
110 .TQ
111 .B \-V
112 Print the version number, license, and disclaimer of warranty for
113 .BR iconv .
114 .SH EXIT STATUS
115 Zero on success, nonzero 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 \[bu] 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 \[bu]
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 .B 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 .P
180 Depending on the architecture,
181 the above files may instead be located at directories with the path prefix
182 .IR /usr/lib64 .
183 .SH STANDARDS
184 POSIX.1-2008.
185 .SH HISTORY
186 POSIX.1-2001.
187 .SH EXAMPLES
188 Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8:
189 .P
190 .in +4n
191 .EX
192 .RB $ " iconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt" ;
193 .EE
194 .in
195 .P
196 The next example converts from UTF-8 to ASCII, transliterating when
197 possible:
198 .P
199 .in +4n
200 .EX
201 .RB $ " echo abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT" ;
202 abc ss ? EUR abc
203 .EE
204 .in
205 .SH SEE ALSO
206 .BR locale (1),
207 .BR uconv (1),
208 .BR iconv (3),
209 .BR nl_langinfo (3),
210 .BR charsets (7),
211 .BR iconvconfig (8)