Debian Codegraph @

upstream/debian-trixie/man1/iconv.1

raw
1 .\" Copyright (C) 2014 Marko Myllynen <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .TH iconv 1 2024-05-02 "Linux man-pages 6.9.1"
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 .P
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 \-\-from\-code= from-encoding
38 .TQ
39 .BI \-f\~ from-encoding
40 Use
41 .I from-encoding
42 for input characters.
43 .TP
44 .BI \-\-to\-code= to-encoding
45 .TQ
46 .BI \-t\~ to-encoding
47 Use
48 .I to-encoding
49 for output characters.
50 .IP
51 If the string
52 .B //IGNORE
53 is appended to
54 .IR to-encoding ,
55 characters that cannot be converted are discarded and an error is
56 printed after conversion.
57 .IP
58 If the string
59 .B //TRANSLIT
60 is appended to
61 .IR to-encoding ,
62 characters being converted are transliterated when needed and possible.
63 This means that when a character cannot be represented in the target
64 character set, it can be approximated through one or several similar
65 looking characters.
66 Characters that are outside of the target character set and cannot be
67 transliterated are replaced with a question mark (?) in the output.
68 .TP
69 .B \-\-list
70 .TQ
71 .B \-l
72 List all known character set encodings.
73 .TP
74 .B \-c
75 Silently discard characters that cannot be converted instead of
76 terminating when encountering such characters.
77 .TP
78 .BI \-\-output= outputfile
79 .TQ
80 .BI \-o\~ outputfile
81 Use
82 .I outputfile
83 for output.
84 .TP
85 .B \-\-silent
86 .TQ
87 .B \-s
88 This option is ignored; it is provided only for compatibility.
89 .TP
90 .B \-\-verbose
91 Print progress information on standard error when processing
92 multiple files.
93 .TP
94 .B \-\-help
95 .TQ
96 .B \-?
97 Print a usage summary and exit.
98 .TP
99 .B \-\-usage
100 Print a short usage summary and exit.
101 .TP
102 .B \-\-version
103 .TQ
104 .B \-V
105 Print the version number, license, and disclaimer of warranty for
106 .BR iconv .
107 .SH EXIT STATUS
108 Zero on success, nonzero on errors.
109 .SH ENVIRONMENT
110 Internally, the
111 .B iconv
112 program uses the
113 .BR iconv (3)
114 function which in turn uses
115 .I gconv
116 modules (dynamically loaded shared libraries)
117 to convert to and from a character set.
118 Before calling
119 .BR iconv (3),
120 the
121 .B iconv
122 program must first allocate a conversion descriptor using
123 .BR iconv_open (3).
124 The operation of the latter function is influenced by the setting of the
125 .B GCONV_PATH
126 environment variable:
127 .IP \[bu] 3
128 If
129 .B GCONV_PATH
130 is not set,
131 .BR iconv_open (3)
132 loads the system gconv module configuration cache file created by
133 .BR iconvconfig (8)
134 and then, based on the configuration,
135 loads the gconv modules needed to perform the conversion.
136 If the system gconv module configuration cache file is not available
137 then the system gconv module configuration file is used.
138 .IP \[bu]
139 If
140 .B GCONV_PATH
141 is defined (as a colon-separated list of pathnames),
142 the system gconv module configuration cache is not used.
143 Instead,
144 .BR iconv_open (3)
145 first tries to load the configuration files by searching the directories in
146 .B GCONV_PATH
147 in order,
148 followed by the system default gconv module configuration file.
149 If a directory does not contain a gconv module configuration file,
150 any gconv modules that it may contain are ignored.
151 If a directory contains a gconv module configuration file
152 and it is determined that a module needed for this conversion is
153 available in the directory,
154 then the needed module is loaded from that directory,
155 the order being such that the first suitable module found in
156 .B GCONV_PATH
157 is used.
158 This allows users to use custom modules and even replace system-provided
159 modules by providing such modules in
160 .B GCONV_PATH
161 directories.
162 .SH FILES
163 .TP
164 .I /usr/lib/gconv
165 Usual default gconv module path.
166 .TP
167 .I /usr/lib/gconv/gconv\-modules
168 Usual system default gconv module configuration file.
169 .TP
170 .I /usr/lib/gconv/gconv\-modules.cache
171 Usual system gconv module configuration cache.
172 .P
173 Depending on the architecture,
174 the above files may instead be located at directories with the path prefix
175 .IR /usr/lib64 .
176 .SH STANDARDS
177 POSIX.1-2008.
178 .SH HISTORY
179 POSIX.1-2001.
180 .SH EXAMPLES
181 Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8:
182 .P
183 .in +4n
184 .EX
185 $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
186 .EE
187 .in
188 .P
189 The next example converts from UTF-8 to ASCII, transliterating when
190 possible:
191 .P
192 .in +4n
193 .EX
194 $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP
195 abc ss ? EUR abc
196 .EE
197 .in
198 .SH SEE ALSO
199 .BR locale (1),
200 .BR uconv (1),
201 .BR iconv (3),
202 .BR nl_langinfo (3),
203 .BR charsets (7),
204 .BR iconvconfig (8)