man/iconv.1

   1 .\" Copyright (c) Free Software Foundation, Inc.
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 3 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
  10 .\"   POSIX 2001 draft6
  11 .\"
  12 .TH ICONV 1  "April 3, 2023" "GNU"
  13 .SH NAME
  14 iconv \- character set conversion
  15 .SH SYNOPSIS
  16 .nf
  17 iconv [\fIOPTION\fP...] [\fB\-f\fP \fIencoding\fP] [\fB\-t\fP \fIencoding\fP] [\fIinputfile\fP ...]
  18 iconv \fB\-l\fP
  19 .fi
  20 .SH DESCRIPTION
  21 The \fBiconv\fP program converts text from one encoding to another encoding.
  22 More precisely, it converts \fBfrom\fP the encoding given for the \fB\-f\fP
  23 option \fBto\fP the encoding given for the \fB\-t\fP option. Either of these
  24 encodings defaults to the encoding of the current locale. All the
  25 \fIinputfile\fPs are read and converted in turn; if no \fIinputfile\fP is
  26 given, the standard input is used. The converted text is printed to standard
  27 output.
  28 .PP
  29 The encodings permitted are system dependent. For the libiconv implementation,
  30 they are listed in the iconv_open(3) manual page.
  31 .PP
  32 Options controlling the input and output format:
  33 .TP
  34 \fB\-f\fP \fIencoding\fP, \fB\-\-from\-code=\fP\fIencoding\fP
  35 Specifies the encoding of the input.
  36 .TP
  37 \fB\-t\fP \fIencoding\fP, \fB\-\-to\-code=\fP\fIencoding\fP
  38 Specifies the encoding of the output.
  39 .PP
  40 Options controlling conversion problems:
  41 .TP
  42 \fB\-c\fP
  43 When this option is given, characters that cannot be converted are silently
  44 discarded, instead of leading to a conversion error.
  45 .TP
  46 \fB\-\-unicode\-subst=\fP\fIformatstring\fP
  47 When this option is given, Unicode characters that cannot be represented in
  48 the target encoding are replaced with a placeholder string that is constructed
  49 from the given \fIformatstring\fP, applied to the Unicode code point. The
  50 \fIformatstring\fP must be a format string in the same format as for the
  51 .I printf
  52 command or the
  53 .I printf()
  54 function, taking either no argument or exactly one unsigned integer argument.
  55 .TP
  56 \fB\-\-byte\-subst=\fP\fIformatstring\fP
  57 When this option is given, bytes in the input that are not valid in the source
  58 encoding are replaced with a placeholder string that is constructed from the
  59 given \fIformatstring\fP, applied to the byte's value. The \fIformatstring\fP
  60 must be a format string in the same format as for the
  61 .I printf
  62 command or the
  63 .I printf()
  64 function, taking either no argument or exactly one unsigned integer argument.
  65 .TP
  66 \fB\-\-widechar\-subst=\fP\fIformatstring\fP
  67 When this option is given, wide characters in the input that are not valid in
  68 the source encoding are replaced with a placeholder string that is constructed
  69 from the given \fIformatstring\fP, applied to the byte's value. The
  70 \fIformatstring\fP must be a format string in the same format as for the
  71 .I printf
  72 command or the
  73 .I printf()
  74 function, taking either no argument or exactly one unsigned integer argument.
  75 .PP
  76 Options controlling error output:
  77 .TP
  78 \fB\-s\fP, \fB\-\-silent\fP
  79 When this option is given, error messages about invalid or unconvertible
  80 characters are omitted, but the actual converted text is unaffected.
  81 .PP
  82 The \fBiconv \-l\fP or \fBiconv \-\-list\fP command lists the names of the
  83 supported encodings, in a system dependent format. For the libiconv
  84 implementation, the names are printed in upper case, separated by whitespace,
  85 and alias names of an encoding are listed on the same line as the encoding
  86 itself.
  87 .SH ENVIRONMENT
  88 Conversion from/to EBCDIC encodings can be modified in a specific way:
  89 If the environment variable \fBICONV_EBCDIC_ZOS_UNIX\fP is set to a non-empty
  90 value, the EBCDIC newline 0x15 will get mapped to LF instead of NEL.
  91 .SH EXAMPLES
  92 .TP
  93 \fBiconv \-f ISO\-8859\-1 \-t UTF\-8\fP
  94 converts input from the old West-European encoding ISO\-8859\-1 to Unicode.
  95 .PP
  96 .nf
  97 \fBiconv \-f KOI8\-R \-\-byte\-subst="<0x%x>"\fP
  98 \fB                \-\-unicode\-subst="<U+%04X>"\fP
  99 .fi
 100 .RS
 101 converts input from the old Russian encoding KOI8\-R to the locale encoding,
 102 substituting an angle bracket notation with hexadecimal numbers for invalid
 103 bytes and for valid but unconvertible characters.
 104 .RE
 105 .TP
 106 \fBiconv \-\-list\fP
 107 lists the supported encodings.
 108 .SH "CONFORMING TO"
 109 POSIX:2001
 110 .SH "SEE ALSO"
 111 .BR iconv_open (3),
 112 .BR locale (7)