*** UNIX MANUAL PAGE BROWSER ***

iconv_open(3) Library Functions Manual iconv_open(3) NAME iconv_open - Opens a character codeset converter LIBRARY The iconv library (libiconv.so, libiconv.a) SYNOPSIS #include <iconv.h> iconv_t iconv_open( const char *tocode, const char *fromcode); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: iconv_open(): XPG4 Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies the destination codeset. Specifies the originating codeset. DESCRIPTION The iconv_open() function initializes a codeset converter. This con- verter is used by the iconv function to convert characters from one codeset to another. The iconv_open() function finds the converter that performs the character conversion specified by the fromcode and tocode parameters, initializes that converter, then returns a conversion de- scriptor of type iconv_t that identifies the converter. The conversion descriptor returned by this function remains valid until the descriptor is closed for the process in which the application is run. The descriptor can be closed by an iconv_close() call in which the descriptor is an argument or by a call to one of the exec() func- tions. Note that standards do not define where codeset converters reside or how vendors implement them. [DIGITAL] The iconv_open() function searches for an algorithmic con- verter. If it does not find an algorithmic converter for the specified codesets, the function then searches for a table converter. The algo- rithmic and table converter file names are formed by concatenating the tocode parameter codeset name onto the fromcode parameter codeset name, with an underscore between the two, for example: fromcode=ct tocode=ISO8859-1 Converter name=ct_ISO8859-1 [DIGITAL] The iconv_open() function searches for an algorithmic con- verter in an iconv subdirectory of the directory specified in the LOC- PATH environment variable. The function searches for a table converter in an iconvTable subdirectory of the directory specified in the LOCPATH environment variable. If LOCPATH is not defined, iconv_open() uses the default value: /usr/lib/nls/loc. [DIGITAL] The LOCPATH variable also overrides the default search path (/usr/lib/nls/loc) that is used to find locales. If this variable is defined, it must therefore specify a search path that application and system software can use to find both locales and converters. The LOCPATH variable is not defined by any standard, so use of the variable should be limited to testing locales or converters under development. RETURN VALUES On successful completion, the iconv_open() function returns a conver- sion descriptor. Otherwise, the function returns -1 cast to iconv_t and sets errno to indicate the error. ERRORS If any of the following conditions occur, the iconv_open() function sets errno to the corresponding value: The number of file descriptors specified by the OPEN_MAX configuration variable is currently open in the calling process. [DIGITAL] Either the OPEN_MAX value or the per-process soft de- scriptor limit is checked. [DIGITAL] The path used to find the codeset converter is longer than PATH_MAX. Too many files are currently open in the system. Insufficient virtual memory is available. The conversion specified by the fromcode and tocode parameters is not supported. On DIGITAL UNIX systems, this condition may also indicate an in- correct LOCPATH setting because support for the specified con- version is determined by finding a converter whose name also specifies that conversion. RELATED INFORMATION Commands: genxlt(1), iconv(1) Functions: iconv(3), iconv_close(3) Others: iconv_intro(5), standards(5) delim off iconv_open(3)