home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue2 / SDL.ARC / !unixlib / source / clib / h / iconv < prev    next >
Encoding:
Text File  |  2004-09-11  |  3.2 KB  |  89 lines
  1.  
  2.  
  3. #ifndef __ICONV_H
  4. #define __ICONV_H 1
  5.  
  6. #ifndef __UNIXLIB_FEATURES_H
  7. #include <unixlib/features.h>
  8. #endif
  9.  
  10. #define __need_size_t
  11. #include <stddef.h>
  12.  
  13. __BEGIN_DECLS
  14.  
  15. #ifndef EILSEQ
  16. #define EILSEQ ENOENT
  17. #endif
  18.  
  19. typedef void *iconv_t;
  20.  
  21. /*
  22.  * Allocate a conversion descriptor suitable for converting byte sequences
  23.  * from encoding from code to encoding tocode.
  24.  * The resulting conversion descriptor may be used any number of times and
  25.  * remains valid until deallocated with iconv_close.
  26.  * A conversion descriptor contains a conversion state. After creation,
  27.  * the state is in the initial state. Using iconv modifies the descriptor's
  28.  * conversion state. The state may be reset by calling iconv with NULL
  29.  * as the inbuf argument.
  30.  *
  31.  * Returns the conversion descriptor on success. On error, (iconv_t)(-1) is
  32.  * returned and errno is set. If errno is set to EINVAL, the implementation
  33.  * does not provide support for conversion between fromcode and tocode.
  34.  */
  35. extern iconv_t iconv_open(const char *tocode, const char *fromcode);
  36.  
  37. /* Perform character set conversion
  38.  * cd must be a conversion descriptor as allocated by iconv_open.
  39.  *
  40.  * If inbuf is not NULL and *inbuf is not NULL, the multibyte sequence
  41.  * starting at *inbuf is converted into a multibyte sequence starting at
  42.  * *outbuf. At most *inbytesleft bytes, starting at *inbuf, will be read.
  43.  * At most *outbytesleft bytes, starting at *outbuf, will be written.
  44.  *
  45.  * One multibyte character is converted at a time.  For each conversion,
  46.  * *inbuf is incremented and *inbytesleft is decremented by the number of
  47.  * converted input bytes. Similarly, *outbuf is incremented and
  48.  * *outbytesleft is decremented by the number of converted output bytes.
  49.  *
  50.  * Conversion can stop for four reasons:
  51.  *
  52.  * 1. An invalid multibyte input sequence is encountered. In this case,
  53.  *    errno is set to EILSEQ and (size_t)(-1) is returned. *inbuf points
  54.  *    to the start of the illegal sequence.
  55.  *
  56.  * 2. The input sequence has been entirely converted. In this case, the
  57.  *    number of non-reversible conversions performed is returned.
  58.  *
  59.  * 3. An incomplete multibyte sequence is encountered in the input and
  60.  *    the input terminates after it. In this case, errno is set to EINVAL
  61.  *    and (size_t)(-1) is returned.
  62.  *
  63.  * 4. The output buffer has no room for the next converted character.
  64.  *    In this case, errno is set to E2BIG and (size_t)(-1) is returned.
  65.  *
  66.  * If inbuf is NULL or *inbuf is NULL but outbuf is not NULL and *outbuf is
  67.  * not NULL, the function attempts to set cd's conversion state to the
  68.  * initial state and store a corresponding shift sequence in *outbuf.
  69.  * At most *outbytesleft will be written. If the output buffer is too small
  70.  * for this reset sequence, errno is set to E2BIG and (size_t)(-1) is
  71.  * returned. Otherwise *outbuf is incremented and *outbytesleft is
  72.  * decremented by the number of bytes written.
  73.  *
  74.  * If inbuf or *inbuf and outbuf or *outbuf are NULL, cd is reset to the
  75.  * initial conversion state.
  76.  */
  77. extern size_t iconv(iconv_t cd, char **inbuf, size_t *inbytesleft,
  78.         char **outbuf, size_t *outbytesleft);
  79.  
  80. /* Deallocate a conversion descriptor cd.
  81.  * Returns 0 on success, -1 on error and sets errno
  82.  */
  83. extern int iconv_close(iconv_t cd);
  84.  
  85. __END_DECLS
  86.  
  87. #endif
  88.  
  89.