unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

ICONV_OPEN(3)              Linux Programmer's Manual             ICONV_OPEN(3)



NAME
       iconv_open - allocate descriptor for character set conversion

SYNOPSIS
       #include <&lt;iconv.h>&gt;

       iconv_t iconv_open(const char *tocode, const char *fromcode);

DESCRIPTION
       The  iconv_open()  function  allocates a conversion descriptor suitable
       for converting byte sequences from character encoding fromcode to char-
       acter encoding tocode.

       The values permitted for fromcode and tocode and the supported combina-
       tions are system-dependent.  For the GNU C library, the permitted  val-
       ues are listed by the iconv --list command, and all combinations of the
       listed values are supported.  Furthermore the GNU C library and the GNU
       libiconv library support the following two suffixes:

       //TRANSLIT
              When the string "//TRANSLIT" is appended to tocode, translitera-
              tion is activated.  This means that when a character  cannot  be
              represented  in the target character set, it can be approximated
              through one or several similarly looking characters.

       //IGNORE
              When the string "//IGNORE" is  appended  to  tocode,  characters
              that  cannot  be represented in the target character set will be
              silently discarded.

       The resulting conversion descriptor can be used with iconv(3) any  num-
       ber of times.  It remains valid until deallocated using iconv_close(3).

       A  conversion  descriptor  contains a conversion state.  After creation
       using iconv_open(), the state is in the initial state.  Using  iconv(3)
       modifies  the descriptor's conversion state.  (This implies that a con-
       version descriptor can not be used in multiple threads simultaneously.)
       To bring the state back to the initial state, use iconv(3) with NULL as
       inbuf argument.

RETURN VALUE
       The  iconv_open()  function  returns  a  freshly  allocated  conversion
       descriptor.  In case of error, it sets errno and returns (iconv_t) -1.

ERRORS
       The following error can occur, among others:

       EINVAL The  conversion  from fromcode to tocode is not supported by the
              implementation.

CONFORMING TO
       UNIX98, POSIX.1-2001.

SEE ALSO
       iconv(1), iconv(3), iconv_close(3)

COLOPHON
       This page is part of release 3.05 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



GNU                               2007-03-31                     ICONV_OPEN(3)