.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "ICONV_OPEN" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" iconv_open 
.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 \- codeset conversion allocation function
.SH SYNOPSIS
.LP
\fB#include <iconv.h>
.br
.sp
iconv_t iconv_open(const char *\fP\fItocode\fP\fB, const char *\fP\fIfromcode\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIiconv_open\fP() function shall return a conversion descriptor
that describes a conversion from the codeset specified by
the string pointed to by the \fIfromcode\fP argument to the codeset
specified by the string pointed to by the \fItocode\fP
argument. For state-dependent encodings, the conversion descriptor
shall be in a codeset-dependent initial shift state, ready for
immediate use with \fIiconv\fP().
.LP
Settings of \fIfromcode\fP and \fItocode\fP and their permitted combinations
are implementation-defined.
.LP
A conversion descriptor shall remain valid until it is closed by \fIiconv_close\fP()
or an implicit close.
.LP
If a file descriptor is used to implement conversion descriptors,
the FD_CLOEXEC flag shall be set; see \fI<fcntl.h>\fP.
.SH RETURN VALUE
.LP
Upon successful completion, \fIiconv_open\fP() shall return a conversion
descriptor for use on subsequent calls to \fIiconv\fP(). Otherwise,
\fIiconv_open\fP() shall return (\fBiconv_t\fP)-1 and set \fIerrno\fP
to indicate the error.
.SH ERRORS
.LP
The \fIiconv_open\fP() function may fail if:
.TP 7
.B EMFILE
{OPEN_MAX} file descriptors are currently open in the calling process.
.TP 7
.B ENFILE
Too many files are currently open in the system.
.TP 7
.B ENOMEM
Insufficient storage space is available.
.TP 7
.B EINVAL
The conversion specified by \fIfromcode\fP and \fItocode\fP is not
supported by the implementation.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Some implementations of \fIiconv_open\fP() use \fImalloc\fP() to allocate
space for
internal buffer areas. The \fIiconv_open\fP() function may fail if
there is insufficient storage space to accommodate these
buffers.
.LP
Conforming applications must assume that conversion descriptors are
not valid after a call to one of the \fIexec\fP functions.
.LP
Application developers should consult the system documentation to
determine the supported codesets and their naming schemes.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIiconv\fP(), \fIiconv_close\fP(), the Base Definitions volume
of
IEEE\ Std\ 1003.1-2001, \fI<fcntl.h>\fP, \fI<iconv.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .