iconv control flow

An application invokes a code set converter by the following call:

iconv_open(char *to_codeset, char *from_codeset)

The to and from code sets are used in selecting the converter by way of the search path defined by the LOCPATH environment variable. The iconv_open subroutine uses the _lc_load subroutine to load the object module specified by concatenating the from and to code set names to the iconv_open subroutine.

CONVERTER NAME= "from_codeset" + "_" +"to_codeset"

If the from_codeset is IBM-850 and the to_codeset is ISO8859-1, the converter name is IBM-850_ISO8859-1.

After loading the converter, its entry point is invoked by the _lc_load loader subroutine. This is the first call to the converter. The instantiate subroutine then initializes the _LC_core_iconv_t core structure. The iconv_open subroutine then calls the init subroutine associated with the core structure thus returned. The init subroutine allocates the converter-specific descriptor structure and initializes it as needed by the converter. The iconv_open subroutine returns this converter-specific structure. However, the return value is typecast to iconv_t in the user's application. Thus, the application does not see the whole of the converter-specific structure; it sees only the public iconv_t structure. The converter code itself uses the private converter structure. Applications that use iconv converters should not change the converter descriptor; the converter descriptor should be used as an opaque structure.

An entry point is declared in every converter so that when the converter is opened by a call to the iconv_open subroutine, that entry point is automatically invoked. The entry point is the instantiate subroutine that should be provided in all converters. The entry point is specified in the makefile as follows:

LDENTRY=-einstantiate

When the converter is loaded on a call to the iconv_open subroutine, the instantiate subroutine is invoked. This subroutine initializes a static core conversion descriptor structure _LC_core_iconv_t cd.

The core conversion descriptor cd contains pointers to the init, _iconv_exec, and _iconv_close subroutines supplied by the specific converter. The instantiate subroutine returns the core conversion descriptor to be used later. The _LC_core_iconv_t structure is defined in /usr/include/iconv.h.

When the iconv_open subroutine is called, the following actions occur:

1. The converter is found using the LOCPATH environment variable, the converter is loaded, and the instantiate subroutine is invoked. On success, it returns the core conversion descriptor. (_LC_core_iconv_t *cd). The instantiate subroutine provided by the converter is responsible for initializing the header in the core structure.
2. The iconv_open subroutine then invokes the init subroutine specified in the core conversion descriptor. The init subroutine provided by the converter is responsible for allocation of memory needed to hold the converter descriptor needed for this specific converter. For example, the following might be the structure needed by a stateless converter:

   typedef struct _LC_sample_iconv_rec {
                     LC_core_iconv_t        core;
     
               } _LC_sample_iconv_t;
     
   To initialize this, the converter has to do the following in the
   init subroutine:
    
   static _LC_sample_iconv_t*  
   init (_LC_core_iconv_t *core_cd, char* toname,char* fromname)
   {
      _LC_sample_iconv_t     *cd;    /* converter descriptor */
    
       /*
       **        Allocate a converter descriptor
       **/
       if(!(cd = ( _LC_sample_iconv_t *) malloc (
                       sizeof(_LC_sample_iconv_t ))))
               return (NULL);
         
       /*
       ** Copy the core part of converter descriptor which is
       ** passed in
       */
       cd->core = *core_cd;
       /*
       **      Return the converter descriptor
       */
       return cd;
   }

An application invokes the iconv subroutine to do the actual code set conversions. The iconv subroutine invokes the exec subroutine in the core structure.

An application invokes the iconv_close subroutine to free any memory allocated for conversions. The iconv_close subroutine invokes the close subroutine in the core structure.