Debian Codegraph @

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