[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


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 the "Locale Overview for System Management" in AIX 5L Version 5.1 System Management Concepts: Operating System and Devices 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 environmental 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. See the "List of PC, ISO, and EBCDIC Code Set Converters" in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs for more information.

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


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


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.

Implementation Specifics

This command is part of Base Operating System (BOS) Runtime.

Files


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

Related Information

The iconv (iconv Subroutine) subroutine, iconv_close (iconv_close Subroutine) subroutine.

The genxlt command, iconv command.

Code Set Overview in AIX 5L Version 5.1 Kernel Extensions and Device Support Programming Concepts.

The List of PC, ISO, and EBCDIC Code Set Converters, the National Language Support Overview for Programming, Converters Overview for Programming in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]