1ICONV(P) POSIX Programmer's Manual ICONV(P)
2
6 iconv - codeset conversion
7
9 iconv [-cs] -f frommap -t tomap [file ...]
10 iconv -f fromcode [-cs] [-t tocode [file ...]
12 iconv -t tocode [-cs] [-f fromcode] [file ...]
14 iconv -l
16
19 The iconv utility shall convert the encoding of characters in file from
20 one codeset to another and write the results to standard output.
21 When the options indicate that charmap files are used to specify the
23 codesets (see OPTIONS), the codeset conversion shall be accomplished by
24 performing a logical join on the symbolic character names in the two
25 charmaps. The implementation need not support the use of charmap files
26 for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on
27 the system.
28
30 The iconv utility shall conform to the Base Definitions volume of
31 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
32 The following options shall be supported:
34 -c Omit any characters that are invalid in the codeset of the input
36 file from the output. When -c is not used, the results of
37 encountering invalid characters in the input stream (either
38 those that are not characters in the codeset of the input file
39 or that have no corresponding character in the codeset of the
40 output file) shall be specified in the system documentation. The
41 presence or absence of -c shall not affect the exit status of
42 iconv.
43 -f fromcodeset
45 Identify the codeset of the input file. The implementation shall
47 recognize the following two forms of the fromcodeset option-
48 argument:
49 fromcode
51 The fromcode option-argument must not contain a slash character.
52 It shall be interpreted as the name of one of the codeset
53 descriptions provided by the implementation in an unspecified
54 format. Valid values of fromcode are implementation-defined.
55 frommap
57 The frommap option-argument must contain a slash character. It
58 shall be interpreted as the pathname of a charmap file as
59 defined in the Base Definitions volume of IEEE Std 1003.1-2001,
60 Section 6.4, Character Set Description File. If the pathname
61 does not represent a valid, readable charmap file, the results
62 are undefined.
63 If this option is omitted, the codeset of the current locale shall be
66 used.
67 -l Write all supported fromcode and tocode values to standard out‐
69 put in an unspecified format.
70 -s Suppress any messages written to standard error concerning
72 invalid characters. When -s is not used, the results of encoun‐
73 tering invalid characters in the input stream (either those that
74 are not valid characters in the codeset of the input file or
75 that have no corresponding character in the codeset of the out‐
76 put file) shall be specified in the system documentation. The
77 presence or absence of -s shall not affect the exit status of
78 iconv.
79 -t tocodeset
81 Identify the codeset to be used for the output file. The imple‐
82 mentation shall recognize the following two forms of the tocode‐
83 set option-argument:
84 tocode
86 The semantics shall be equivalent to the -f fromcode option.
87 tomap
89 The semantics shall be equivalent to the tomap option.
90 If this option is omitted, the codeset of the current locale shall be
93 used.
94 If either -f or -t represents a charmap file, but the other does not
97 (or is omitted), or both -f and -t are omitted, the results are unde‐
98 fined.
99
101 The following operand shall be supported:
102 file A pathname of an input file. If no file operands are specified,
104 or if a file operand is '-' , the standard input shall be used.
105
108 The standard input shall be used only if no file operands are speci‐
109 fied, or if a file operand is '-' .
110
112 The input file shall be a text file.
113
115 The following environment variables shall affect the execution of
116 iconv:
117 LANG Provide a default value for the internationalization variables
119 that are unset or null. (See the Base Definitions volume of
120 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
121 ables for the precedence of internationalization variables used
122 to determine the values of locale categories.)
123 LC_ALL If set to a non-empty string value, override the values of all
125 the other internationalization variables.
126 LC_CTYPE
128 Determine the locale for the interpretation of sequences of
129 bytes of text data as characters (for example, single-byte as
130 opposed to multi-byte characters in arguments). During transla‐
131 tion of the file, this variable is superseded by the use of the
132 fromcode option-argument.
133 LC_MESSAGES
135 Determine the locale that should be used to affect the format
136 and contents of diagnostic messages written to standard error.
137 NLSPATH
139 Determine the location of message catalogs for the processing of
140 LC_MESSAGES .
141
144 Default.
145
147 When the -l option is used, the standard output shall contain all sup‐
148 ported fromcode and tocode values, written in an unspecified format.
149 When the -l option is not used, the standard output shall contain the
151 sequence of characters read from the input files, translated to the
152 specified codeset. Nothing else shall be written to the standard out‐
153 put.
154
156 The standard error shall be used only for diagnostic messages.
157
159 None.
160
162 None.
163
165 The following exit values shall be returned:
166 0 Successful completion.
168 >0 An error occurred.
170
173 Default.
174 The following sections are informative.
176
178 The user must ensure that both charmap files use the same symbolic
179 names for characters the two codesets have in common.
180
182 The following example converts the contents of file mail.x400 from the
183 ISO/IEC 6937:1994 standard codeset to the ISO/IEC 8859-1:1998 standard
184 codeset, and stores the results in file mail.local:
185 iconv -f IS6937 -t IS8859 mail.x400 > mail.local
188
190 The iconv utility can be used portably only when the user provides two
191 charmap files as option-arguments. This is because a single charmap
192 provided by the user cannot reliably be joined with the names in a sys‐
193 tem-provided character set description. The valid values for fromcode
194 and tocode are implementation-defined and do not have to have any rela‐
195 tion to the charmap mechanisms. As an aid to interactive users, the -l
196 option was adopted from the Plan 9 operating system. It writes informa‐
197 tion concerning these implementation-defined values. The format is
198 unspecified because there are many possible useful formats that could
199 be chosen, such as a matrix of valid combinations of fromcode and
200 tocode. The -l option is not intended for shell script usage; conform‐
201 ing applications will have to use charmaps.
202
204 None.
205
207 gencat
208
210 Portions of this text are reprinted and reproduced in electronic form
211 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
212 -- Portable Operating System Interface (POSIX), The Open Group Base
213 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
214 Electrical and Electronics Engineers, Inc and The Open Group. In the
215 event of any discrepancy between this version and the original IEEE and
216 The Open Group Standard, the original IEEE and The Open Group Standard
217 is the referee document. The original Standard can be obtained online
218 at http://www.opengroup.org/unix/online.html .
219IEEE/The Open Group 2003 ICONV(P)