84d9c625bf
- Fix for possible unset uid/gid in toproto
- Fix for default mtree style
- Update libelf
- Importing libexecinfo
- Resynchronize GCC, mpc, gmp, mpfr
- build.sh: Replace params with show-params.
This has been done as the make target has been renamed in the same
way, while a new target named params has been added. This new
target generates a file containing all the parameters, instead of
printing it on the console.
- Update test48 with new etc/services (Fix by Ben Gras <ben@minix3.org)
get getservbyport() out of the inner loop
Change-Id: Ie6ad5226fa2621ff9f0dee8782ea48f9443d2091
277 lines
7.4 KiB
Groff
277 lines
7.4 KiB
Groff
.\" $NetBSD: iconv.3,v 1.21 2013/05/12 10:44:23 wiz Exp $
|
|
.\"
|
|
.\" 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 March 11, 2013
|
|
.Dt ICONV 3
|
|
.Os
|
|
.\" ----------------------------------------------------------------------
|
|
.Sh NAME
|
|
.Nm iconv_open ,
|
|
.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_close "iconv_t cd"
|
|
.Ft size_t
|
|
.Fn iconv "iconv_t cd" "const 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.
|
|
.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 -offset indent
|
|
.It Fa *src
|
|
Pointer to the byte just after the last character fetched.
|
|
.It Fa *srcleft
|
|
Number of remaining bytes in the source buffer.
|
|
.It Fa *dst
|
|
Pointer to the byte just after the last character stored.
|
|
.It Fa *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
|
|
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.
|
|
.Bl -enum -offset indent
|
|
.It
|
|
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.
|
|
.It
|
|
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.
|
|
.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 EINVAL
|
|
There is no converter specified by
|
|
.Fa srcname
|
|
and
|
|
.Fa dstname .
|
|
.It Bq Er ENOMEM
|
|
Memory is exhausted.
|
|
.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 E2BIG
|
|
The output buffer pointed to by
|
|
.Fa *dst
|
|
is too small to store the result string.
|
|
.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 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 .
|
|
.Pp
|
|
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
|
|
.In 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
|
|
.Pq without const ,
|
|
even though the version with const is arguably more correct.
|
|
.Nx
|
|
has always used the const form.
|
|
It was decided to reject the committee's regression and become
|
|
.Pq technically
|
|
incompatible.
|
|
GNU libiconv has taken the
|
|
.Lk http://www.gnu.org/savannah-checkouts/gnu/libiconv/documentation/libiconv-1.14/ "same route".
|
|
Most third party software affected by this issue already handles it
|
|
during configuration.
|
|
.\" ----------------------------------------------------------------------
|
|
.Sh BUGS
|
|
If
|
|
.Fn iconv
|
|
is aborted due to the occurrence of some error,
|
|
the
|
|
.Dq invalid conversion
|
|
count mentioned above is unfortunately lost.
|