usr/src/man/man1/iconv.1

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH ICONV 1 "Nov 14, 2003"
  13 .SH NAME
  14 iconv \- code set conversion utility
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 \fBiconv\fR [\fB-cs\fR] \fB-f\fR \fIfrommap\fR \fB-t\fR \fItomap\fR [\fIfile\fR]...
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBiconv\fR \fB-f\fR \fIfromcode\fR [\fB-cs\fR] [\fB-t\fR \fItocode\fR] [\fIfile\fR]...
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBiconv\fR \fB-t\fR \fItocode\fR [\fB-cs\fR] [\fB-f\fR \fIfromcode\fR] [\fIfile\fR]...
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBiconv\fR \fB-l\fR
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 The \fBiconv\fR utility converts the characters or sequences of characters in
  40 \fIfile\fR from one code set to another and writes the results to standard
  41 output. If no conversion exists for a particular character, an
  42 implementation-defined conversion is performed on this character.
  43 .sp
  44 .LP
  45 The list of supported conversions and the locations of the associated
  46 conversion tables are provided in the \fBiconv\fR(5) manual page.
  47 .SH OPTIONS
  48 .sp
  49 .LP
  50 The following options are supported:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fB-c\fR\fR
  55 .ad
  56 .RS 18n
  57 Omits any characters that are invalid in the codeset of the input file from the
  58 output. When \fB-c\fR is not used, the results of encountering invalid
  59 characters in the input stream depend on the specified codesets for the
  60 conversion. Invalid characters can be either those that are not valid
  61 characters in the codeset of the input file or those that have no corresponding
  62 character in the codeset of the output file. The presence or absence of
  63 \fB-c\fR does not affect the exit status of \fBiconv\fR. When \fIfromcode\fR is
  64 specified for the \fIfromcodeset\fR of the \fB-f\fR option or \fItocode\fR is
  65 specified for the \fItocodeset\fR of the \fB-t\fR option, the specification of
  66 \fB-c\fR may be ignored.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fB-f\fR \fIfromcodeset\fR\fR
  73 .ad
  74 .RS 18n
  75 Identifies the code set of the input file. The following two forms of the
  76 \fIfromcodeset\fR option-argument are recognized:
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIfromcode\fR\fR
  81 .ad
  82 .RS 12n
  83 The \fIfromcode\fR option-argument must not contain a slash (\fB/\fR)
  84 character. It is interpreted as the name of one of the codeset descriptions.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIfrommap\fR\fR
  91 .ad
  92 .RS 12n
  93 The \fIfrommap\fR option-argument must contain a slash character. It is
  94 interpreted as the pathname of a charmap file as defined in \fBcharmap\fR(5).
  95 If the pathname does not represent a valid, readable charmap file, the results
  96 are undefined.
  97 .RE
  98
  99 If this option is omitted, the codeset of the current locale is used.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB-l\fR\fR
 106 .ad
 107 .RS 18n
 108 Writes all supported \fIfromcode\fR and \fItocode\fR values to standard output.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fB-s\fR\fR
 115 .ad
 116 .RS 18n
 117 Suppresses any messages written to standard error concerning invalid
 118 characters. When \fB-s\fR is not used, the results of encountering invalid
 119 characters in the input stream depend on the specified codesets for the
 120 conversion. Invalid characters can be either those that are not valid
 121 characters in the codeset of the input file or those that have no corresponding
 122 character in the codeset of the output file. The presence or absence of
 123 \fB-s\fR does not affect the exit status of \fBiconv\fR. When \fIfromcode\fR is
 124 specified for the \fIfromcodeset\fR of the \fB-f\fR option or \fItocode\fR is
 125 specified for the \fItocodeset\fR of the \fB-t\fR option, the specification of
 126 \fB-s\fR may be ignored.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fB-t\fR \fItocodeset\fR\fR
 133 .ad
 134 .RS 18n
 135 Identifies the code set used for the output file. The following two forms of
 136 the \fItocodeset\fR option-argument are recognized:
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fItocode\fR\fR
 141 .ad
 142 .RS 10n
 143 The \fItocode\fR option-argument must not contain a slash (\fB/\fR) character.
 144 It is interpreted as the name of one of the codeset descriptions.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fItomap\fR\fR
 151 .ad
 152 .RS 10n
 153 The \fItomap\fR option-argument must contain a slash character. It is
 154 interpreted as the pathname of a charmap file as defined in \fBcharmap\fR(5).
 155 If the pathname does not represent a valid, readable charmap file, the results
 156 are undefined.
 157 .RE
 158
 159 If this option is omitted, the codeset of the current locale is used.
 160 .RE
 161
 162 .sp
 163 .LP
 164 If either \fB-f\fR or \fB-t\fR represents a charmap file but the other does
 165 not, or is omitted, or if both \fB-f\fR and \fB-t\fR are omitted, \fBiconv\fR
 166 fails as an error.
 167 .SH OPERANDS
 168 .sp
 169 .LP
 170 The following operands are supported:
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fIfile\fR\fR
 175 .ad
 176 .RS 8n
 177 A path name of an input file. If no file operands are specified, or if a file
 178 operand is '\fB-\fR', the standard input is used.
 179 .RE
 180
 181 .SH EXAMPLES
 182 .LP
 183 \fBExample 1 \fRConverting and storing files
 184 .sp
 185 .LP
 186 The following example converts the contents of file \fBmail1\fR from code set
 187 \fB8859\fR to \fB646fr\fR and stores the results in file \fBmail.local\fR:
 188
 189 .sp
 190 .in +2
 191 .nf
 192 example% \fBiconv -f 8859 -t 646fr mail1 > mail.local\fR
 193 .fi
 194 .in -2
 195 .sp
 196
 197 .SH ENVIRONMENT VARIABLES
 198 .sp
 199 .LP
 200 See \fBenviron\fR(5) for descriptions of the following environment variables
 201 that affect the execution of \fBiconv\fR: \fBLANG\fR, \fBLC_ALL\fR,
 202 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 203 .SH EXIT STATUS
 204 .sp
 205 .LP
 206 The following exit values are returned:
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fB0\fR\fR
 211 .ad
 212 .RS 5n
 213 Successful completion.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fB1\fR\fR
 220 .ad
 221 .RS 5n
 222 An error has occurred.
 223 .RE
 224
 225 .SH FILES
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fB/usr/lib/iconv/iconv_data\fR\fR
 230 .ad
 231 .RS 29n
 232 list of conversions supported by conversion tables
 233 .RE
 234
 235 .SH ATTRIBUTES
 236 .sp
 237 .LP
 238 See \fBattributes\fR(5) for descriptions of the following attributes:
 239 .sp
 240
 241 .sp
 242 .TS
 243 box;
 244 c | c
 245 l | l .
 246 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 247 _
 248 Interface Stability     Standard
 249 .TE
 250
 251 .SH SEE ALSO
 252 .sp
 253 .LP
 254 \fBiconv\fR(3C), \fBiconv_open\fR(3C), \fBattributes\fR(5), \fBcharmap\fR(5),
 255 \fBenviron\fR(5), \fBiconv\fR(5), \fBiconv_unicode\fR(5), \fBstandards\fR(5)
 256 .SH NOTES
 257 .sp
 258 .LP
 259 Make sure that both charmap files use the same symbolic names for characters
 260 the two codesets have in common.
 261 .sp
 262 .LP
 263 The output format of the \fB-l\fR option is unspecified. The \fB-l\fR option is
 264 not intended for shell script usage.
 265 .sp
 266 .LP
 267 When \fIfromcode\fR or \fItocode\fR is specified for the codeset conversion,
 268 \fBiconv\fR uses the \fBiconv_open\fR(3C) function. If \fBiconv_open\fR(3C)
 269 fails to open the specified codeset conversion, \fBiconv\fR searches for an
 270 appropriate conversion table. As for the supported codeset conversion by
 271 \fBiconv_open\fR(3C), please refer to \fBiconv\fR(5) and \fBiconv_locale\fR(5).