iconv_t
iconv_open(
const char *dstname
, const char *srcname
)
int
iconv_close(
iconv_t cd
)
size_t
iconv(
iconv_t cd
, const char ** restrict src
, size_t * restrict srcleft
, char ** restrict dst
, size_t * restrict dstleft
)
)
function opens a converter from the codeset
srcname
to the codeset
dstname
and returns its descriptor.
The
iconv_close()
function closes the specified converter
cd
.
The
iconv()
function converts the string in the buffer
*src
of length
*srcleft
bytes and stores the converted string in the buffer
*dst
of size
*dstleft
bytes.
After calling
iconv(),
the values pointed to by
src
,
srcleft
,
dst
,
and
dstleft
are updated as follows:
If the string pointed to by
*src
contains a byte sequence which is not a valid character in the source
codeset, the conversion stops just after the last successful conversion.
If the output buffer is too small to store the converted
character, the conversion also stops in the same way.
In these cases, the values pointed to by
src
,
srcleft
,
dst
,
and
dstleft
are updated to the state just after the last successful conversion.
If the string pointed to by
*src
contains a character which is valid under the source codeset but
can not be converted to the destination codeset,
the character is replaced by an
``invalid character''
which depends on the destination codeset, e.g.,
`?',
and the conversion is continued.
iconv()
returns the number of such
``invalid conversions''.
There are two special cases of
iconv():
)
places these into their initial state.
If both
dst
and
*dst
are
non-NULL
,
iconv()
stores the shift sequence for the destination switching to the initial state
in the buffer pointed to by
*dst
.
The buffer size is specified by the value pointed to by
dstleft
as above.
iconv()
will fail if the buffer is too small to store the shift sequence.
On the other hand,
dst
or
*dst
may be
NULL
.
In this case, the shift sequence for the destination switching
to the initial state is discarded.
),
it returns a conversion descriptor.
Otherwise,
iconv_open(
)
returns (iconv_t)-1 and sets errno to indicate the error.
Upon successful completion of
iconv_close(),
it returns 0.
Otherwise,
iconv_close(
)
returns -1 and sets errno to indicate the error.
Upon successful completion of
iconv(),
it returns the number of
``invalid''
conversions.
Otherwise,
iconv(
)
returns (size_t)-1 and sets errno to indicate the error.
)
function may cause an error in the following cases:
ENOMEM
]
EINVAL
]
srcname
and
dstname
.
The
iconv_close()
function may cause an error in the following case:
EBADF
]
cd
is invalid.
The
iconv()
function may cause an error in the following cases:
EBADF
]
cd
is invalid.
EILSEQ
]
*src
contains a byte sequence which does not describe a valid character of
the source codeset.
E2BIG
]
*dst
is too small to store the result string.
EINVAL
]
*src
terminates with an incomplete character or shift sequence.
),
iconv_close(
),
and
iconv(
)
conform to
IEEE Std 1003.1-2001 (``POSIX.1'') .
)
is aborted due to the occurrence of some error,
the
``invalid conversion''
count mentioned above is unfortunately lost.