iconv_open(3C)

NAME

     iconv_open - code conversion allocation function

SYNOPSIS

     #include <iconv.h>

     iconv_t iconv_open(const char  *tocode,  const  char  *from-
     code);

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 the  iconv(3C) function.

     Settings of fromcode and tocode and their permitted combina-
     tions are implementation-dependent.

     The iconv_open() function supports the alias of the encoding
     name  specified  in tocode and fromcode.  The alias table of
     the   encoding   name   is    described    in    the    file
     /usr/lib/iconv/alias. See alias(4).

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

     For  examples  using   the    iconv_open()   function,   see
     iconv(3C).

RETURN VALUES

     Upon successful completion  iconv_open() returns  a  conver-
     sion  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.

FILES

     /usr/lib/iconv/alias
           alias table file of the encoding name

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     exec(2), iconv(3C), iconv_close(3C),  malloc(3C),  alias(4),
     attributes(5)

NOTES

     The iconv_open() function uses malloc(3C) to allocate  space
     for internal buffer areas. iconv_open() may fail if there is
     insufficient storage space to accommodate these buffers.

     Portable applications must assume that  conversion  descrip-
     tors are not valid after a call to one of the exec functions
     (see exec(2)).