Copyright (c)2003 Citrus Project,
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd July 1, 2003 .Dt iconv 3 .Os ----------------------------------------------------------------------
.Sh NAME .Nm iconv_open , .Nm iconv_close , .Nm iconv .Nd codeset conversion functions ----------------------------------------------------------------------
.Sh LIBRARY .Lb libc ----------------------------------------------------------------------
.Sh SYNOPSIS n iconv.h .Ft iconv_t .Fn iconv_open "const char * dstname" "const char * srcname" .Ft int .Fn iconv_close "iconv_t cd" .Ft size_t .Fn iconv "iconv_t cd" "const char ** src" "size_t *srcleft" "char ** dst" "size_t dstleft" ----------------------------------------------------------------------
.Sh DESCRIPTION The .Fn iconv_open function opens a converter from the codeset .Fa srcname to the codeset .Fa dstname and returns its descriptor.
p The .Fn iconv_close function closes a converter specified .Fa cd .
p The .Fn iconv function converts a string pointed by .Fa *src up to .Fa *srcleft bytes and stores the converted string to a buffer pointed by .Fa *dst up to .Fa *dstleft bytes. After calling .Fn iconv , the values pointed by .Fa src , .Fa srcleft , .Fa dst and .Fa dstleft are updated as the following: l -tag -width 01234567 t *src Pointer to the byte just after the last character fetched. t *srcleft Number of remainder bytes of the source buffer. t *dst Pointer to the byte just after the last character stored. t *srcleft Number of remainder bytes of the destination buffer. .El
p If the string pointed by .Fa *src contains a byte sequence which is not valid character of the source codeset, the conversion stops just after the last successful conversion. If the output buffer is lacked to store the converted character, the conversion also stops in the same way. In these case, the values pointed by .Fa src , .Fa srcleft , .Fa dst and .Fa dstleft are updated on the state just after the last successful conversion.
p If the string pointed by .Fa *src contains a character which is valid unders the source codeset but can not be converted to the destination codeset, the character is replaced to an "invalid character" which depends on the destination codeset, e.g. `?', and the conversion is continued. .Fn iconv returns the number of such "invalid conversions".
p
There are special cases of
.Fn iconv :
l -tag -width 0123 t "(src == NULL || *src == NULL) && dst != NULL && *dst != NULL" If the destination codeset is stateful,
.Fa iconv
places the destination into its initial state and
stores the shift sequence to back the initial state to the buffer pointed by
.Fa *dst .
t "(src == NULL || *src == NULL) && (dst == NULL || *dst == NULL)" If the source codeset is stateful,
.Fa iconv
places the source into its initial state.
.El
----------------------------------------------------------------------
.Sh RETURN VALUES
Upon successful comletion of
.Fn iconv_open ,
it returns a conversion descriptor. Otherwise,
.Fn iconv_open
returns (iconv_t)-1 and set errno to indicate the error.
p Upon successful comletion of .Fn iconv_close , it returns 0. Otherwise, .Fn iconv_close returns -1 and set errno to indicate the error.
p
Upon successful comletion of
.Fn iconv ,
it returns the number of "invalid" conversion.
Otherwise,
.Fn iconv
returns (size_t)-1 and set errno to indicate the error.
----------------------------------------------------------------------
.Sh ERRORS
The
.Fn iconv_open
function may causes an error in the following case:
l -tag -width Er t Bq Er ENOMEM Memory is exhausted.
t Bq Er EINVAL There is no converter specified by
.Fa srcname
and
.Fa dstname .
.El
p The .Fn iconv_close function may causes an error in the following case: l -tag -width Er t Bq Er EBADF The conversion descriptor specified by .Fa cd is invalid. .El
p
The
.Fn iconv
function may causes an error in the following case:
l -tag -width Er t Bq Er EBADF The conversion descriptor specified by
.Fa cd
is invalid.
t Bq Er EILSEQ The string pointed by
.Fa *src
contains a byte sequence which does not figures a valid character of
the source codeset.
t Bq Er E2BIG The output buffer pointed by
.Fa *dst
is too small to store the result string.
t Bq Er EINVAL The string pointed by
.Fa *src
terminates an incomplete character or shift sequence.
.El
----------------------------------------------------------------------
.Sh BUGS
If
.Fn iconv
is aborted due to the occurrence of some error,
the "invalid conversion" count mentioned above is unfortunately lost.
----------------------------------------------------------------------
.Sh SEE ALSO
.Xr iconv 1
----------------------------------------------------------------------
.Sh STANDARDS
.Fn iconv_open ,
.Fn iconv_close
and
.Fn iconv
conform to
.St -p1003.1-2001 .