c91ab1769b
setting. It can be built by setting the WITH_ICONV knob. While this knob is unset, the library part, the binaries, the header file and the metadata files will not be built or installed so it makes no impact on the system if left turned off. This work is based on the iconv implementation in NetBSD but a great number of improvements and feature additions have been included: - Some utilities have been added. There is a conversion table generator, which can compare conversion tables to reference data generated by GNU libiconv. This helps ensuring conversion compatibility. - UTF-16 surrogate support and some endianness issues have been fixed. - The rather chaotic Makefiles to build metadata have been refactored and cleaned up, now it is easy to read and it is also easier to add support for new encodings. - A bunch of new encodings and encoding aliases have been added. - Support for 1->2, 1->3 and 1->4 mappings, which is needed for transliterating with flying accents as GNU does, like "u. - Lots of warnings have been fixed, the major part of the code is now WARNS=6 clean. - New section 1 and section 5 manual pages have been added. - Some GNU-specific calls have been implemented: iconvlist(), iconvctl(), iconv_canonicalize(), iconv_open_into() - Support for GNU's //IGNORE suffix has been added. - The "-" argument for stdin is now recognized in iconv(1) as per POSIX. - The Big5 conversion module has been fixed. - The iconv.h header files is supposed to be compatible with the GNU version, i.e. sources should build with base iconv.h and GNU libiconv. It also includes a macro magic to deal with the char ** and const char ** incompatibility. - GNU compatibility: "" or "char" means the current local encoding in use - Various cleanups and style(9) fixes. Approved by: delphij (mentor) Obtained from: The NetBSD Project Sponsored by: Google Summer of Code 2009
306 lines
7.5 KiB
Groff
306 lines
7.5 KiB
Groff
.\" $FreeBSD$
|
|
.\" $NetBSD: iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
|
|
.\"
|
|
.\" Copyright (c) 2003 Citrus Project,
|
|
.\" Copyright (c) 2009, 2010 Gabor Kovesdan <gabor@FreeBSD.org>,
|
|
.\" 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 Juny 16, 2010
|
|
.Dt ICONV 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm iconv_open ,
|
|
.Nm iconv_open_into ,
|
|
.Nm iconv_close ,
|
|
.Nm iconv
|
|
.Nd codeset conversion functions
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In iconv.h
|
|
.Ft iconv_t
|
|
.Fn iconv_open "const char *dstname" "const char *srcname"
|
|
.Ft int
|
|
.Fn iconv_open_into "const char *dstname" "const char *srcname" "iconv_allocation_t *ptr"
|
|
.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"
|
|
.Ft size_t
|
|
.Fn __iconv "iconv_t cd" "const char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" "uint32_t flags" "size_t invalids"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn iconv_open
|
|
function opens a converter from the codeset
|
|
.Fa srcname
|
|
to the codeset
|
|
.Fa dstname
|
|
and returns its descriptor.
|
|
The arguments
|
|
.Fa srcname
|
|
and
|
|
.Fa dstname
|
|
accept "" and "char", which refer to the current locale encoding.
|
|
.Pp
|
|
The
|
|
.Fn iconv_open_into
|
|
creates a conversion descriptor on a preallocated space.
|
|
The
|
|
.Ft iconv_allocation_t
|
|
is used as a spaceholder type when allocating such space.
|
|
The
|
|
.Fa dstname
|
|
and
|
|
.Fa srcname
|
|
arguments are the same as in the case of
|
|
.Fn iconv_open .
|
|
The
|
|
.Fa ptr
|
|
argument is a pointer of
|
|
.Ft iconv_allocation_t
|
|
to the preallocated space.
|
|
.Pp
|
|
The
|
|
.Fn iconv_close
|
|
function closes the specified converter
|
|
.Fa cd .
|
|
.Pp
|
|
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:
|
|
.Bl -tag -width 01234567
|
|
.It *src
|
|
Pointer to the byte just after the last character fetched.
|
|
.It *srcleft
|
|
Number of remaining bytes in the source buffer.
|
|
.It *dst
|
|
Pointer to the byte just after the last character stored.
|
|
.It *dstleft
|
|
Number of remainder bytes in the destination buffer.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
There are two special cases of
|
|
.Fn iconv :
|
|
.Bl -tag -width 0123
|
|
.It "src == NULL || *src == NULL"
|
|
If the source and/or destination codesets are stateful,
|
|
.Fn iconv
|
|
places these into their initial state.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.El
|
|
The
|
|
.Fn __iconv
|
|
function works just like
|
|
.Fn iconv
|
|
but if
|
|
.Fn iconv
|
|
fails, the invalid character count is lost there.
|
|
This is a not bug rather a limitation of
|
|
.St -p1003.1-2008 ,
|
|
so
|
|
.Fn __iconv
|
|
is provided as an alternative but non-standard interface.
|
|
It also has a flags argument, where currently the following
|
|
flags can be passed:
|
|
.Bl -tag -width 0123
|
|
.It __ICONV_F_HIDE_INVALID
|
|
Skip invalid characters, instead of returning with an error.
|
|
.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 errno to indicate the error.
|
|
.Pp
|
|
Upon successful completion of
|
|
.Fn iconv_open_into ,
|
|
it returns 0.
|
|
Otherwise,
|
|
.Fn iconv_open_into
|
|
returns \-1, and sets errno to indicate the error.
|
|
.Pp
|
|
Upon successful completion of
|
|
.Fn iconv_close ,
|
|
it returns 0.
|
|
Otherwise,
|
|
.Fn iconv_close
|
|
returns \-1 and sets errno to indicate the error.
|
|
.Pp
|
|
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:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENOMEM
|
|
Memory is exhausted.
|
|
.It Bq Er EINVAL
|
|
There is no converter specified by
|
|
.Fa srcname
|
|
and
|
|
.Fa dstname .
|
|
.El
|
|
The
|
|
.Fn iconv_open_into
|
|
function may cause an error in the following cases:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
There is no converter specified by
|
|
.Fa srcname
|
|
and
|
|
.Fa dstname .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn iconv_close
|
|
function may cause an error in the following case:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The conversion descriptor specified by
|
|
.Fa cd
|
|
is invalid.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn iconv
|
|
function may cause an error in the following cases:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The conversion descriptor specified by
|
|
.Fa cd
|
|
is invalid.
|
|
.It 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.
|
|
.It Bq Er E2BIG
|
|
The output buffer pointed to by
|
|
.Fa *dst
|
|
is too small to store the result string.
|
|
.It 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 ,
|
|
.Xr mkcsmapper 1 ,
|
|
.Xr mkesdb 1
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn iconv_open ,
|
|
.Fn iconv_close ,
|
|
and
|
|
.Fn iconv
|
|
functions conform to
|
|
.St -p1003.1-2008 .
|
|
.Pp
|
|
The
|
|
.Fn iconv_open_into
|
|
function is a GNU-specific extension and it is not part of any standard,
|
|
thus its use may break portability.
|
|
The
|
|
.Fn __iconv
|
|
function is an own extension and it is not part of any standard,
|
|
thus its use may break portability.
|