'\" et

.TH ICONV_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

iconv_open

\(em codeset conversion allocation function

.SH SYNOPSIS

.LP

.nf

#include <iconv.h>

.P

iconv_t iconv_open(const char *\fItocode\fP, const char *\fIfromcode\fP);

.fi

.SH DESCRIPTION

The

\fIiconv_open\fR()

function shall return a conversion descriptor

that describes a conversion from the codeset specified by the string

pointed to by the

.IR fromcode

argument to the codeset specified by the string pointed to by the

.IR tocode

argument. For state-dependent encodings, the conversion descriptor

shall be in a codeset-dependent initial shift state, ready for

immediate use with

\fIiconv\fR().

.P

Settings of

.IR fromcode

and

.IR tocode

and their permitted combinations are implementation-defined.

.P

A conversion descriptor shall remain valid until it is closed by

\fIiconv_close\fR()

or an implicit close.

.P

If a file descriptor is used to implement conversion descriptors, the

FD_CLOEXEC flag shall be set; see

.IR <fcntl.h> .

.SH "RETURN VALUE"

Upon successful completion,

\fIiconv_open\fR()

shall return a conversion descriptor for use on subsequent calls to

\fIiconv\fR().

Otherwise,

\fIiconv_open\fR()

shall return (\fBiconv_t\fP)\(mi1 and set

.IR errno

to indicate the error.

.SH ERRORS

The

\fIiconv_open\fR()

function may fail if:

.TP

.BR EMFILE

All file descriptors available to the process are currently open.

.TP

.BR ENFILE

Too many files are currently open in the system.

.TP

.BR ENOMEM

Insufficient storage space is available.

.TP

.BR EINVAL

The conversion specified by

.IR fromcode

and

.IR tocode

is not supported by the implementation.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

None.

.SH "APPLICATION USAGE"

Some implementations of

\fIiconv_open\fR()

use

\fImalloc\fR()

to allocate space for internal buffer areas. The

\fIiconv_open\fR()

function may fail if there is insufficient storage space to accommodate

these buffers.

.P

Conforming applications must assume that conversion descriptors are not

valid after a call to one of the

.IR exec

functions.

.P

Application developers should consult the system documentation to

determine the supported codesets and their naming schemes.

.SH RATIONALE

None.

.SH "FUTURE DIRECTIONS"

None.

.SH "SEE ALSO"

.IR "\fIiconv\fR\^(\|)",

.IR "\fIiconv_close\fR\^(\|)"

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<fcntl.h>\fP",

.IR "\fB<iconv.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .