Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 204 insertions, 0 deletions

diff --git a/man/man1/iconv.1 b/man/man1/iconv.1
new file mode 100644
index 0000000..15c5471
--- /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 2024-05-02 "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)