The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> iconv_open - codeset conversion allocation function

#### SYNOPSIS

> ``[XSI] #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>

#### CHANGE HISTORY

> First released in Issue 4. Derived from the HP-UX Manual.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]