iconv_open Subroutine

Purpose

Opens a character code set converter.

Library

iconv Library (libiconv.a)

Syntax

#include <iconv.h>

iconv_t iconv_open ( ToCode, FromCode) const char *ToCode, *FromCode;

Description

The iconv_open subroutine initializes a code set converter. The code set converter is used by the iconv subroutine to convert characters from one code set to another. The iconv_open subroutine finds the converter that performs the character code set conversion specified by the FromCode and ToCode parameters, initializes that converter, and returns a conversion descriptor of type iconv_t to identify the code set converter.

The iconv_open subroutine first searches the LOCPATH environment variable for a converter, using the two user-provided code set names, based on the file name convention that follows:

FromCode: "IBM-850"
ToCode: "ISO8859-1"
conversion file: "IBM-850_ISO8859-1"

The conversion file name is formed by concatenating the ToCode code set name onto the FromCode code set name, with an _ (underscore) between them.

The LOCPATH environment variable contains a list of colon-separated directory names. The system default for the LOCPATH environment variable is:

LOCPATH=/usr/lib/nls/loc

See Locales in AIX® Version 7.1 National Language Support Guide and Reference for more information on the LOCPATH environment variable.

The iconv_open subroutine first attempts to find the specified converter in an iconv subdirectory under any of the directories specified by the LOCPATH environment variable, for example, /usr/lib/nls/loc/iconv. If the iconv_open subroutine cannot find a converter in any of these directories, it looks for a conversion table in an iconvTable subdirectory under any of the directories specified by the LOCPATH environment variable, for example, /usr/lib/nls/loc/iconvTable.

If the iconv_open subroutine cannot find the specified converter in either of these locations, it returns (iconv_t) -1 to the calling process and sets the errno global variable.

The iconvTable directories are expected to contain conversion tables that are the output of the genxlt command. The conversion tables are limited to single-byte stateless code sets.

If the named converter is found, the iconv_open subroutine will perform the load subroutine operation and initialize the converter. A converter descriptor (iconv_t) is returned.

Note: When a process calls the exec subroutine or a fork subroutine, all of the opened converters are discarded.

The iconv_open subroutine links the converter function using the load subroutine, which is similar to the exec subroutine and effectively performs a run-time linking of the converter program. Since the iconv_open subroutine is called as a library function, it must ensure that security is preserved for certain programs. Thus, when the iconv_open subroutine is called from a set root ID program (a program with permission —-s—s—x), it will ignore the LOCPATH environment variable and search for converters only in the /usr/lib/nls/loc/iconv directory.

Parameters

Item	Description
ToCode	Specifies the destination code set.
FromCode	Specifies the originating code set.

Return Values

A conversion descriptor (iconv_t) is returned if successful. Otherwise, the subroutine returns -1, and the errno global variable is set to indicate the error.

Error Codes

Item	Description
EINVAL	The conversion specified by the FromCode and ToCode parameters is not supported by the implementation.
EMFILE	The number of file descriptors specified by the OPEN_MAX configuration variable is currently open in the calling process.
ENFILE	Too many files are currently open in the system.
ENOMEM	Insufficient storage space is available.

Files

Item	Description
/usr/lib/nls/loc/iconv	Contains loadable method converters.
/usr/lib/nls/loc/iconvTable	Contains conversion tables for single-byte stateless code sets.