[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 1
Converts a string of characters
in one character code set to another character code set.
The iconv Library
(libiconv.a)
#include <iconv.h>
size_t iconv (CD, InBuf, InBytesLeft, OutBuf, OutBytesLeft)
iconv_t CD;
char **OutBuf, **InBuf;
size_t *OutBytesLeft, *InBytesLeft;
The iconv subroutine
converts the string specified by the InBuf parameter into a
different code set and returns the results in the OutBuf
parameter. The required conversion method is identified by the
CD parameter, which must be valid conversion descriptor returned by
a previous, successful call to the iconv_open subroutine.
On calling, the
InBytesLeft parameter indicates the number of bytes in the
InBuf buffer to be converted, and the OutBytesLeft
parameter indicates the number of available bytes in the OutBuf
buffer. These values are updated upon return so they indicate the new
state of their associated buffers.
For state-dependent encodings,
calling the iconv subroutine with the InBuf buffer set
to null will reset the conversion descriptor in the CD parameter to
its initial state. Subsequent calls with the InBuf buffer,
specifying other than a null pointer, may cause the internal state of the
subroutine to be altered a necessary.
| CD
| Specifies the conversion descriptor that points to the correct code set
converter.
|
| InBuf
| Points to a buffer that contains the number of bytes in the
InBytesLeft parameter to be converted.
|
| InBytesLeft
| Points to an integer that contains the number of bytes in the
InBuf parameter.
|
| OutBuf
| Points to a buffer that contains the number of bytes in the
OutBytesLeft parameter that has been converted.
|
| OutBytesLeft
| Points to an integer that contains the number of bytes in the
OutBuf parameter.
|
Upon successful conversion of all
the characters in the InBuf buffer and after placing the converted
characters in the OutBuf buffer, the iconv subroutine
returns 0, updates the InBytesLeft and OutBytesLeft
parameters, and increments the InBuf and OutBuf
pointers. Otherwise, it updates the varibles pointed to by the
parameters to indicate the extent to the conversion, returns the number of
bytes still left to be converted in the input buffer, and sets the
errno global variable to indicate the error.
If the iconv
subroutine is unsuccessful, it updates the variables to reflect the extent of
the conversion before it stopped and sets the errno global variable
to one of the following values:
| EILSEQ
| Indicates an unusable character. If an input character does not
belong to the input code set, no conversion is attempted on the unusable on
the character. In InBytesLeft parameters indicates the bytes
left to be converted, including the first byte of the unusable
character. InBuf parameter points to the first byte of the
unusable character sequence.
The values of OutBuf and OutBytesLeft are updated
according to the number of bytes that were previously converted.
|
| E2BIG
| Indicates an output buffer overflow. If the OutBuf
buffer is too small to contain all the converted characters, the character
that causes the overflow is not converted. The InBytesLeft
parameter 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.
|
| EINVAL
| Indicates the input buffer was truncated. If the original value of
InBytesLeft is exhausted in the middle of a character conversion or
shift/lock block, the InBytesLeft parameter indicates the number of
bytes undefined in the character being converted.
If an input character of shift sequence is truncated by the
InBuf buffer, no conversion is attempted on the truncated data, and
the InBytesLeft parameter indicates the bytes left to be
converted. The InBuf parameter points to the first bytes if
the truncated sequence. The OutBuf and
OutBytesLeft values are updated according to the number of
characters that were previously0 converted. Because some encoding may
have ambiguous data, the EINVAL return value has a special meaning
at the end of stream conversion. As such, if a user detects an EOF
character on a stream that is being converted and the last return code from
the iconv subroutine was EINVAL, the iconv
subroutine should be called again, with the same InBytesLeft
parameter and the same character string pointed to by the InBuf
parameter as when the EINVAL return occurred. As a result,
the converter will either convert the string as is or declare it an unusable
sequence (EILSEQ).
|
The iconv subroutine
is part of Base Operating System (BOS) Runtime.
| /usr/lib/nls/loc/iconv/*
| Contains code set converter methods.
|
The iconv command, genxlt command.
The iconv_close (iconv_close Subroutine) subroutine, iconv_open (iconv_open Subroutine) subroutine.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]