iconv - Convert a string of characters from one codeset to
another codeset
The following syntax is for pre-XSH5.0-compliant interfaces
on Tru64 UNIX V4 and V5 systems: #include <iconv.h>
size_t iconv(
iconv_t cd,
const char **inbuf,
size_t *inbytesleft,
char **outbuf,
size_t *outbytesleft );
The following syntax is for pre-V4 Tru64 UNIX systems and
XSH5.0-compliant interfaces on V5 systems: #include
<iconv.h>
size_t iconv(
iconv_t cd,
char **inbuf,
size_t *inbytesleft,
char **outbuf,
size_t *outbytesleft );
The iconv library (libiconv)
Interfaces documented on this reference page conform to
industry standards as follows:
iconv(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the conversion descriptor that points to the
correct codeset converter Points to a variable that points
to the beginning of a buffer that contains the characters
to be converted Points to an integer that contains the
number of bytes in inbuf still to be converted Points to a
variable that points to the buffer that contains the characters
that have been converted Points to an integer that
contains the number of free bytes in outbuf
The iconv() function converts a string of characters in
inbuf into a different codeset and returns the results in
outbuf. The required converter is identified by cd, which
must be a valid descriptor returned by a previous successful
call to the iconv_open() function.
On calling, the inbytesleft parameter indicates the number
of bytes in inbuf to be converted and outbytesleft indicates
the number of available bytes in outbuf.
For codesets that include shift-state sequences, a call to
iconv() in which inbuf is or points to a null pointer
places the cd conversion descriptor into its initial shift
state. In this case, as long as outbuf is not (or does not
point to) a null pointer, the call places in outbuf the
byte sequence that changes the output buffer to its initial
shift state. If the output buffer is not large
enough to hold the entire reset sequence, the call fails
and sets errno to [E2BIG]. Any subsequent calls in which
inbuf is not (or does not point to) a null pointer cause
the conversion to take place from the current state of the
conversion descriptor. See the RESTRICTIONS section for
information about support of shift-state encoding.
If a sequence of input bytes does not form a character
that is valid in the input codeset, conversion stops after
the previous successfully converted character. If the
input buffer ends with an incomplete character or shift
sequence, conversion stops after the last byte sequence
that was successfully converted to a character. If the
output is not large enough to hold the entire sequence of
converted characters, conversion stops just prior to the
input byte sequence that would cause the output buffer to
overflow.
On return from the call: The inbuf value is updated to
point to the byte following the last byte used successfully
in conversion The inbytesleft value is decremented
to reflect the number of input bytes still not converted
The outbuf value is updated to point to the byte following
the last output byte of successfully converted data The
outbytesleft value is decremented to reflect the number of
bytes still available in the output buffer. For codesets
that include shift-state encoding, the conversion descriptor
is updated to reflect the shift state in effect at the
end of the last successfully converted byte sequence.
It is possible for input data to include a character that
is valid in the input codeset but for which an identical
character does not exist in the output codeset. The output
character for such cases is defined by the converter
that iconv() applies when converting from one particular
codeset to another. In other words, the output character
in this case can vary from one codeset converter to
another.
Currently, the operating system does not include locales
whose codesets use shift-state encoding. Some sections of
this reference page refer to iconv() behavior with respect
to conversion of shift sequences. This information is
included only for your convenience in developing portable
applications that run on multiple platforms, some of which
may supply locales whose codesets do use shift-state
encoding.
The iconv() function updates the variables pointed to by
the call arguments to reflect the extent of the conversion
and returns the number of non-identical conversions performed.
If the function is successful and converts the
entire input string, the value pointed to by inbytesleft
will be 0 (zero).
If an error occurs, the function returns (size_t)-1 and
sets errno to indicate the condition.
If any of the following conditions occur, the iconv()
function sets errno to the corresponding value: The outbuf
buffer is too small to contain all the converted characters.
The character that causes the overflow is not converted
and inbytesleft indicates the bytes left to be converted,
including the character that caused the overflow.
The inbuf parameter points to the first byte of the characters
left to convert. The cd parameter does not specify
a valid converter descriptor. An input character does not
belong to the input codeset. No conversion is attempted on
the invalid character and inbytesleft indicates the bytes
left to be converted, including the first byte of the
invalid character. The inbuf parameter points to the first
byte of the invalid character sequence.
The values of outbuf and outbytesleft are updated
according to the number of characters that were
previously converted. The last character or shift
sequence in the inbuf parameter was not complete.
The inbytesleft parameter indicates the number of
input bytes still not converted.
Functions: iconv_close(3), iconv_open(3)
Commands: iconv(1), genxlt(1)
Others: iconv_intro(5), standards(5)
iconv(3)
[ Back ] | 