The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### 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]
>   All file descriptors available to the process are currently open.
> [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

> XBD <fcntl.h>, <iconv.h>

#### CHANGE HISTORY

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

#### Issue 7

> SD5-XBD-ERN-4 is applied, changing the definition of the [EMFILE] error.

> The iconv_open() function is moved from the XSI option to the Base.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]