Return to iconv.1 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man

libiconv

    1: .\" Copyright (c) Bruno Haible <bruno@clisp.org>
    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  "March 31, 2007" "GNU" "Linux Programmer's Manual"
   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 EXAMPLES
   88: .TP
   89: \fBiconv \-f ISO\-8859\-1 \-t UTF\-8\fP
   90: converts input from the old West-European encoding ISO\-8859\-1 to Unicode.
   91: .PP
   92: .nf
   93: \fBiconv \-f KOI8\-R \-\-byte\-subst="<0x%x>"\fP
   94: \fB                \-\-unicode\-subst="<U+%04X>"\fP
   95: .fi
   96: .RS
   97: converts input from the old Russian encoding KOI8\-R to the locale encoding,
   98: substituting an angle bracket notation with hexadecimal numbers for invalid
   99: bytes and for valid but unconvertible characters.
  100: .RE
  101: .TP
  102: \fBiconv \-\-list\fP
  103: lists the supported encodings.
  104: .SH "CONFORMING TO"
  105: POSIX:2001
  106: .SH "SEE ALSO"
  107: .BR iconv_open (3),
  108: .BR locale (7)