1 files changed, 125 insertions, 0 deletions
diff --git a/man/man3/iconv_open.3 b/man/man3/iconv_open.3
new file mode 100644
index 000000000..f58629aee
--- /dev/null
+++ b/man/man3/iconv_open.3
@@ -0,0 +1,125 @@
+'\" t
+.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" References consulted:
+.\"   GNU glibc-2 source code and manual
+.\"   OpenGroup's Single UNIX specification
+.\"     http://www.UNIX-systems.org/online.html
+.\"
+.\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT
+.\" and //IGNORE extensions for 'tocode'.
+.\"
+.TH iconv_open 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+iconv_open \- allocate descriptor for character set conversion
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <iconv.h>
+.P
+.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
+.fi
+.SH DESCRIPTION
+The
+.BR iconv_open ()
+function allocates a conversion descriptor suitable
+for converting byte sequences from character encoding
+.I fromcode
+to
+character encoding
+.IR tocode .
+.P
+The values permitted for
+.I fromcode
+and
+.I tocode
+and the supported
+combinations are system-dependent.
+For the GNU C library, the permitted
+values are listed by the
+.I "iconv \-\-list"
+command, and all combinations
+of the listed values are supported.
+Furthermore the GNU C library and the
+GNU libiconv library support the following two suffixes:
+.TP
+//TRANSLIT
+When the string "//TRANSLIT" is appended to
+.IR tocode ,
+transliteration
+is activated.
+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.
+.TP
+//IGNORE
+When the string "//IGNORE" is appended to
+.IR tocode ,
+characters that
+cannot be represented in the target character set will be silently discarded.
+.P
+The resulting conversion descriptor can be used with
+.BR iconv (3)
+any number of times.
+It remains valid until deallocated using
+.BR iconv_close (3).
+.P
+A conversion descriptor contains a conversion state.
+After creation using
+.BR iconv_open (),
+the state is in the initial state.
+Using
+.BR iconv (3)
+modifies the descriptor's conversion state.
+To bring the state back to the initial state, use
+.BR iconv (3)
+with NULL as
+.I inbuf
+argument.
+.SH RETURN VALUE
+On success,
+.BR iconv_open ()
+returns a freshly allocated conversion
+descriptor.
+On failure, it returns
+.I (iconv_t)\ \-1
+and sets
+.I errno
+to indicate the error.
+.SH ERRORS
+The following error can occur, among others:
+.TP
+.B EINVAL
+The conversion from
+.I fromcode
+to
+.I tocode
+is not supported by the
+implementation.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR iconv_open ()
+T}	Thread safety	MT-Safe locale
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.1.
+POSIX.1-2001, SUSv2.
+.SH SEE ALSO
+.BR iconv (1),
+.BR iconv (3),
+.BR iconv_close (3)