NAME

       iconv_open - codeset conversion allocation function

SYNOPSIS

       #include <iconv.h>

       iconv_t iconv_open(const char *tocode, const char *fromcode);

DESCRIPTION

       The  iconv_open()  function  shall  return  a  conversion descriptor that describes a conversion from the
       codeset specified by the string pointed to by the fromcode argument  to  the  codeset  specified  by  the
       string  pointed to by the tocode argument. For state-dependent encodings, the conversion descriptor shall
       be in a codeset-dependent initial shift state, ready for immediate use with iconv().

       Settings of fromcode and tocode and their permitted combinations are implementation-defined.

       A conversion descriptor shall remain valid until it is closed by iconv_close() or an implicit close.

       If a file descriptor is used to implement conversion descriptors, the FD_CLOEXEC flag shall be  set;  see
       <fcntl.h>.

RETURN VALUE

       Upon successful completion, iconv_open() shall return a conversion descriptor for use on subsequent calls
       to iconv(). Otherwise, iconv_open() shall return (iconv_t)-1 and set errno to indicate the error.

ERRORS

       The iconv_open() function may fail if:

       EMFILE {OPEN_MAX} file descriptors are currently open in the calling process.

       ENFILE Too many files are currently open in the system.

       ENOMEM Insufficient storage space is available.

       EINVAL The conversion specified by fromcode and tocode is not supported by the implementation.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       Some  implementations  of  iconv_open()  use  malloc()  to  allocate space for internal buffer areas. The
       iconv_open() function may fail if there is insufficient storage space to accommodate these buffers.

       Conforming applications must assume that conversion descriptors are not valid after a call to one of  the
       exec functions.

       Application  developers  should  consult the system documentation to determine the supported codesets and
       their naming schemes.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       iconv() , iconv_close() , the Base Definitions volume of IEEE Std 1003.1-2001, <fcntl.h>, <iconv.h>

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 .

IEEE/The Open Group                                   2003                                         ICONV_OPEN(P)