Man Linux: Main Page and Category List

NAME

       iconv - codeset conversion function

SYNOPSIS

       #include <iconv.h>

       size_t iconv(iconv_t cd, char **restrict inbuf,
              size_t *restrict inbytesleft, char **restrict outbuf,
              size_t *restrict outbytesleft);

DESCRIPTION

       The  iconv() function shall convert the sequence of characters from one
       codeset,  in  the  array  specified  by  inbuf,  into  a  sequence   of
       corresponding  characters in another codeset, in the array specified by
       outbuf. The codesets are those specified in the iconv_open() call  that
       returned  the conversion descriptor, cd. The inbuf argument points to a
       variable that points to the first character in  the  input  buffer  and
       inbytesleft  indicates  the number of bytes to the end of the buffer to
       be converted. The outbuf argument points to a variable that  points  to
       the  first  available  byte  in  the  output  buffer  and  outbytesleft
       indicates the number of the available bytes to the end of the buffer.

       For state-dependent encodings, the conversion descriptor cd  is  placed
       into  its  initial  shift  state  by  a  call for which inbuf is a null
       pointer, or for which inbuf points to a null pointer. When  iconv()  is
       called in this way, and if outbuf is not a null pointer or a pointer to
       a null pointer, and outbytesleft points to a  positive  value,  iconv()
       shall  place,  into  the output buffer, the byte sequence to change the
       output buffer to its initial shift state. If the output buffer  is  not
       large  enough to hold the entire reset sequence, iconv() shall fail and
       set errno to [E2BIG].  Subsequent calls with inbuf as other than a null
       pointer  or  a  pointer  to a null pointer cause the conversion to take
       place from the current state of the conversion descriptor.

       If a sequence of input bytes does not form a  valid  character  in  the
       specified   codeset,   conversion   shall   stop   after  the  previous
       successfully converted character. If the  input  buffer  ends  with  an
       incomplete character or shift sequence, conversion shall stop after the
       previous successfully converted bytes. If  the  output  buffer  is  not
       large  enough to hold the entire converted input, conversion shall stop
       just prior to the input bytes that would cause  the  output  buffer  to
       overflow. The variable pointed to by inbuf shall be updated to point to
       the byte following the last byte successfully used in  the  conversion.
       The value pointed to by inbytesleft shall be decremented to reflect the
       number of bytes still not converted in the input buffer.  The  variable
       pointed  to  by  outbuf shall be updated to point to the byte following
       the last byte of  converted  output  data.  The  value  pointed  to  by
       outbytesleft  shall be decremented to reflect the number of bytes still
       available in the output  buffer.  For  state-dependent  encodings,  the
       conversion  descriptor  shall  be updated to reflect the shift state in
       effect at the end of the last successfully converted byte sequence.

       If iconv() encounters a character in the input buffer  that  is  valid,
       but  for  which  an  identical  character  does not exist in the target
       codeset, iconv() shall perform an implementation-defined conversion  on
       this character.

RETURN VALUE

       The  iconv()  function  shall  update  the  variables pointed to by the
       arguments to reflect the extent of the conversion and return the number
       of  non-identical  conversions  performed.  If the entire string in the
       input buffer is converted, the value pointed to by inbytesleft shall be
       0.  If  the input conversion is stopped due to any conditions mentioned
       above, the value pointed to by inbytesleft shall be non-zero and  errno
       shall  be  set  to  indicate the condition. If an error occurs, iconv()
       shall return (size_t)-1 and set errno to indicate the error.

ERRORS

       The iconv() function shall fail if:

       EILSEQ Input conversion stopped due to an  input  byte  that  does  not
              belong to the input codeset.

       E2BIG  Input  conversion  stopped  due  to  lack of space in the output
              buffer.

       EINVAL Input conversion stopped due to an incomplete character or shift
              sequence at the end of the input buffer.

       The iconv() function may fail if:

       EBADF  The cd argument is not a valid open conversion descriptor.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  inbuf argument indirectly points to the memory area which contains
       the conversion input data. The outbuf argument indirectly points to the
       memory  area  which  is  to  contain  the result of the conversion. The
       objects indirectly pointed to by inbuf and outbuf are not restricted to
       containing  data  that  is directly representable in the ISO C standard
       language char data type. The type of inbuf and outbuf,  char  **,  does
       not  imply  that  the  objects  pointed  to  are  interpreted  as null-
       terminated C strings or arrays of characters.  Any interpretation of  a
       byte  sequence  that  represents  a  character in a given character set
       encoding scheme is done internally within the codeset  converters.  For
       example,  the  area  pointed  to  indirectly by inbuf and/or outbuf can
       contain all zero octets that are not interpreted as string  terminators
       but  as  coded  character  data  according  to  the  respective codeset
       encoding scheme. The type of the data ( char, short, long, and  so  on)
       read or stored in the objects is not specified, but may be inferred for
       both the input and output data by  the  converters  determined  by  the
       fromcode and tocode arguments of iconv_open().

       Regardless  of the data type inferred by the converter, the size of the
       remaining space in both input and output objects (the intbytesleft  and
       outbytesleft arguments) is always measured in bytes.

       For  implementations  that  support  the  conversion of state-dependent
       encodings, the conversion descriptor must be able to accurately reflect
       the shift-state in effect at the end of the last successful conversion.
       It is not required that the conversion descriptor  itself  be  updated,
       which  would require it to be a pointer type. Thus, implementations are
       free to implement the descriptor as a  handle  (other  than  a  pointer
       type)  by which the conversion information can be accessed and updated.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       iconv_open()  ,  iconv_close()  ,  the  Base  Definitions   volume   of
       IEEE Std 1003.1-2001, <iconv.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .