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 returns 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 will 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-dependent.

A conversion descriptor remains valid in a process until that process closes it.

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

 RETURN VALUE

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

 ERRORS

The iconv_open() function may fail if:

[EMFILE]

{OPEN_MAX} files 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.

 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.

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

 FUTURE DIRECTIONS

None.

 SEE ALSO

iconv(), iconv_close(), <iconv.h>.

DERIVATION

Derived from the HP-UX manual.