Man Pages

iconv(3p) - phpMan iconv(3p) - phpMan

Command: man perldoc info search(apropos)  


ICONV(3P)                  POSIX Programmer's Manual                 ICONV(3P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

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  ini-
       tial  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 con-
       version 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 from-
       code 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 con-
       version 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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                            ICONV(3P)