diff options
Diffstat (limited to 'man/man1/iconv.1')
| -rw-r--r-- | man/man1/iconv.1 | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/man/man1/iconv.1 b/man/man1/iconv.1 new file mode 100644 index 000000000..eaa18c0f9 --- /dev/null +++ b/man/man1/iconv.1 @@ -0,0 +1,204 @@ +.\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH iconv 1 (date) "Linux man-pages (unreleased)" +.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 standard input. +If no output file is given, +.B iconv +writes to standard output. +.P +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 \-\-from\-code= from-encoding +.TQ +.BI \-f\~ from-encoding +Use +.I from-encoding +for input characters. +.TP +.BI \-\-to\-code= to-encoding +.TQ +.BI \-t\~ to-encoding +Use +.I to-encoding +for output characters. +.IP +If the string +.B //IGNORE +is appended to +.IR to-encoding , +characters that cannot be converted are discarded and an error is +printed after conversion. +.IP +If the string +.B //TRANSLIT +is appended to +.IR to-encoding , +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 similar +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 \-\-list +.TQ +.B \-l +List all known character set encodings. +.TP +.B \-c +Silently discard characters that cannot be converted instead of +terminating when encountering such characters. +.TP +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile +Use +.I outputfile +for output. +.TP +.B \-\-silent +.TQ +.B \-s +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 +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH ENVIRONMENT +Internally, the +.B iconv +program uses the +.BR iconv (3) +function which in turn uses +.I gconv +modules (dynamically loaded shared libraries) +to convert to and from a character set. +Before calling +.BR iconv (3), +the +.B iconv +program must first allocate a conversion descriptor using +.BR iconv_open (3). +The operation of the latter function is influenced by the setting of the +.B GCONV_PATH +environment variable: +.IP \[bu] 3 +If +.B GCONV_PATH +is not set, +.BR iconv_open (3) +loads the system gconv module configuration cache file created by +.BR iconvconfig (8) +and then, based on the configuration, +loads the gconv modules needed to perform the conversion. +If the system gconv module configuration cache file is not available +then the system gconv module configuration file is used. +.IP \[bu] +If +.B GCONV_PATH +is defined (as a colon-separated list of pathnames), +the system gconv module configuration cache is not used. +Instead, +.BR iconv_open (3) +first tries to load the configuration files by searching the directories in +.B GCONV_PATH +in order, +followed by the system default gconv module configuration file. +If a directory does not contain a gconv module configuration file, +any gconv modules that it may contain are ignored. +If a directory contains a gconv module configuration file +and it is determined that a module needed for this conversion is +available in the directory, +then the needed module is loaded from that directory, +the order being such that the first suitable module found in +.B GCONV_PATH +is used. +This allows users to use custom modules and even replace system-provided +modules by providing such modules in +.B GCONV_PATH +directories. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.P +Depending on the architecture, +the above files may instead be located at directories with the path prefix +.IR /usr/lib64 . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8: +.P +.in +4n +.EX +$ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP +.EE +.in +.P +The next example converts from UTF-8 to ASCII, transliterating when +possible: +.P +.in +4n +.EX +$ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP +abc ss ? EUR abc +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR uconv (1), +.BR iconv (3), +.BR nl_langinfo (3), +.BR charsets (7), +.BR iconvconfig (8) |