Originální popis anglicky:
iconv - codeset conversion function
Návod, kniha: POSIX Programmer's Manual
#include <iconv.h>
size_t iconv(iconv_t
cd, char **restrict
inbuf ,
size_t *restrict
inbytesleft , char **restrict
outbuf ,
size_t *restrict
outbytesleft );
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.
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.
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.
None.
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.
None.
None.
iconv_open() ,
iconv_close() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<iconv.h>
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
.
