From 111cf06c0861e25bccdca709a7526afe0114325f Mon Sep 17 00:00:00 2001 From: Marko Myllynen Date: Wed, 11 Jun 2014 11:09:40 +0300 Subject: [PATCH] iconv.1: New page for the iconv(1) command Signed-off-by: Michael Kerrisk --- man1/iconv.1 | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 man1/iconv.1 diff --git a/man1/iconv.1 b/man1/iconv.1 new file mode 100644 index 000000000..31991c0c2 --- /dev/null +++ b/man1/iconv.1 @@ -0,0 +1,174 @@ +'\" t -*- coding: UTF-8 -*- +.\" +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" %%%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 +.\" . +.\" %%%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)