iconv.1: New page for the iconv(1) command

[thirdparty/man-pages.git] / man1 / iconv.1

'\" t -*- coding: UTF-8 -*-
.\"
.\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
.TH ICONV 1 2014-06-06 "GNU" "Linux User Manual"
.SH NAME
iconv \- convert text from one character encoding to another
.SH SYNOPSIS
.B iconv
.RI [ options ]
.RI "[-f " from-encoding "]"
.RI "[-t " to-encoding "]"
.RI [ inputfile ]...
.SH DESCRIPTION
The
.B iconv
program reads in text in one encoding and outputs the text in another
encoding.
If no input files are given, or if it is given as a dash (\-),
.B iconv
reads from the standard input.
If no output file is given,
.B iconv
writes to the standard output.
.PP
If no
.I from-encoding
is given, the default is derived
from the current locale's character encoding.
If no
.I to-encoding
is given, the default is derived
from the current locale's character
encoding.
.SH OPTIONS
.TP
.BI \-f " from-encoding" ", \-\-from-code=" from-encoding
Use
.I from-encoding
for input characters.
.TP
.BI \-t " to-encoding" ", \-\-to-code=" to-encoding
Use
.I to-encoding
for output characters.

If
.I to-encoding
is appended with
.BR //IGNORE ,
characters that cannot be converted are discarded and an error is
printed after conversion.

If
.I to-encoding
is appended with
.BR //TRANSLIT ,
characters being converted are transliterated when needed and possible.
This means that when a character cannot be represented in the target 
character set, it can be approximated through one or several similarly 
looking characters.
Characters that are outside of the target character set and cannot be
transliterated are replaced with a question mark (?) in the output.
.TP
.B "\-l, \-\-list"
List all known character set encodings.
.TP
.B "\-c"
Silently discard characters that cannot be converted instead of
terminating when encountering such a character.
.TP
.BI \-o " outputfile" ", \-\-output=" outputfile
Use
.I outputfile
for output.
.TP
.B "\-s, \-\-silent"
This option is ignored, it is provided only for compatibility.
.TP
.B "\-\-verbose"
Print progress information on standard error when processing
multiple files.
.TP
.B "\-\-help"
Print a usage summary and exit.
.TP
.B "\-\-usage"
Print a short usage summary and exit.
.TP
.B "\-V, \-\-version"
Print the version number, license, and disclaimer of warranty for
.BR iconv .
.SH EXIT STATUS
Zero on success, non-zero on errors.
.SH ENVIRONMENT
Internally, the
.B iconv
program uses the
.BR iconv (3)
function which in turn uses
.I gconv
modules to convert to and from a character set.
.B iconv
supports any character set for which a
corresponding gconv configuration and module are provided for.
By default, the system provided gconv configuration and modules
are used, but
.B GCONV_PATH
can be defined as a list of pathnames, separated by colons (\(aq:\(aq),
for gconv configuration and module search path,
to be searched prior to the system provided configuration and modules.
If
.B GCONV_PATH
is set, the system gconv module configuration cache (created by
.BR iconvconfig (8))
will not be used.
Only directories containing the
.I gconv-modules
configuration files will be searched for the specified gconv modules.
.SH FILES
.TP
.I /usr/lib/gconv
Usual default gconv module path.
.TP
.I /usr/lib/gconv/gconv-modules
Usual default gconv module configuration.
.TP
.I /usr/lib/gconv/gconv-modules.cache
Usual default gconv module configuration cache.
.SH CONFORMING TO
POSIX.1-2001.
.SH EXAMPLE
Convert text from the ISO 8859-15 character encoding to UTF-8
encoding:
.PP
.RS
iconv \-f ISO\-8859\-15 -t UTF\-8 < input.txt > output.txt
.RE
.PP
The next example converts from UTF-8 to ASCII, transliterating when
possible:

.nf
$ \fBecho abc ß α € àḃç | iconv -f UTF-8 -t ASCII//TRANSLIT\fP
abc ss ? EUR abc
$ 
.fi
.SH "SEE ALSO"
.BR locale (1),
.BR iconv (3),
.BR nl_langinfo (3),
.BR charsets (7),
.BR iconvconfig (8)