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 October 24, 2019 .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" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict 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 the specified converter .Fa cd .
p The .Fn iconv function converts the string in the buffer .Fa *src of length .Fa *srcleft bytes and stores the converted string in the buffer .Fa *dst of size .Fa *dstleft bytes. After calling .Fn iconv , the values pointed to by .Fa src , .Fa srcleft , .Fa dst , and .Fa dstleft are updated as follows: l -tag -width 01234567 -offset indent t Fa *src Pointer to the byte just after the last character fetched. t Fa *srcleft Number of remaining bytes in the source buffer. t Fa *dst Pointer to the byte just after the last character stored. t Fa *dstleft Number of remainder bytes in the destination buffer. .El
p If the string pointed to by .Fa *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 .Fa src , .Fa srcleft , .Fa dst , and .Fa dstleft are updated to the state just after the last successful conversion.
p If the string pointed to by .Fa *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 .Dq invalid character which depends on the destination codeset, e.g., .Sq ? , and the conversion is continued. .Fn iconv returns the number of such .Dq invalid conversions .
p
If
.Fa src
or
.Fa *src
is
.Dv NULL
and the source and/or destination codesets are stateful,
.Fn iconv
places these into their initial state.
l -enum -offset indent t If both
.Fa dst
and
.Fa *dst
are
.No non- Ns Dv NULL ,
.Fn iconv
stores the shift sequence for the destination switching to the initial state
in the buffer pointed to by
.Fa *dst .
The buffer size is specified by the value pointed to by
.Fa dstleft
as above.
.Fn iconv
will fail if the buffer is too small to store the shift sequence.
t On the other hand,
.Fa dst
or
.Fa *dst
may be
.Dv NULL .
In this case, the shift sequence for the destination switching
to the initial state is discarded.
.El
----------------------------------------------------------------------
.Sh RETURN VALUES
Upon successful completion of
.Fn iconv_open ,
it returns a conversion descriptor.
Otherwise,
.Fn iconv_open
returns (iconv_t)-1 and sets
.Va errno
to indicate the error.
p Upon successful completion of .Fn iconv_close , it returns 0. Otherwise, .Fn iconv_close returns -1 and sets errno to indicate the error.
p
Upon successful completion of
.Fn iconv ,
it returns the number of
.Dq invalid
conversions.
Otherwise,
.Fn iconv
returns (size_t)-1 and sets errno to indicate the error.
----------------------------------------------------------------------
.Sh ERRORS
The
.Fn iconv_open
function may cause an error in the following cases:
l -tag -width Er t Bq Er EINVAL There is no converter specified by
.Fa srcname
and
.Fa dstname .
t Bq Er ENOMEM Memory is exhausted.
.El
p The .Fn iconv_close function may cause 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 cause an error in the following cases:
l -tag -width Er t Bq Er E2BIG The output buffer pointed to by
.Fa *dst
is too small to store the result string.
t Bq Er EBADF The conversion descriptor specified by
.Fa cd
is invalid.
t Bq Er EILSEQ The string pointed to by
.Fa *src
contains a byte sequence which does not describe a valid character of
the source codeset.
t Bq Er EINVAL The string pointed to by
.Fa *src
terminates with an incomplete character or shift sequence.
.El
----------------------------------------------------------------------
.Sh SEE ALSO
.Xr iconv 1
----------------------------------------------------------------------
.Sh STANDARDS
.Fn iconv_open ,
.Fn iconv_close ,
and
.Fn iconv
conform to
.St -p1003.1-2001 .
p Historically, the definition of .Ft iconv has not been consistent across operating systems. This is due to an unfortunate historical mistake, documented in .Lk https://www5.opengroup.org/sophocles2/show_mail.tpl?&source=L&listname=austin-group-l&id=7404 "this e-mail". The standards page for the header file n iconv.h defined the second argument of .Fn iconv as .Ft char ** , but the standards page for the .Fn iconv implementation defined it as .Ft const char ** . The standards committee later chose to change the function definition to follow the header file definition
q without const , even though the version with const is arguably more correct. .Nx used initially the const form. It was decided to reject the committee's regression and become
q technically incompatible.
p
This decision was changed in
.Nx 10
and the
.Fn iconv
prototype was synchronized with the standard.
----------------------------------------------------------------------
.Sh BUGS
If
.Fn iconv
is aborted due to the occurrence of some error,
the
.Dq invalid conversion
count mentioned above is unfortunately lost.