2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
244 lines
6.4 KiB
Groff
244 lines
6.4 KiB
Groff
.\" $NetBSD: iconv.3,v 1.14 2010/05/05 22:07:58 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 May 5, 2010
|
|
.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 the source and/or destination codesets are stateful,
|
|
.Fn iconv
|
|
places these into their initial state.
|
|
There are two special cases of
|
|
.Fn iconv :
|
|
.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 .
|
|
.\" ----------------------------------------------------------------------
|
|
.Sh BUGS
|
|
If
|
|
.Fn iconv
|
|
is aborted due to the occurrence of some error,
|
|
the
|
|
.Dq invalid conversion
|
|
count mentioned above is unfortunately lost.
|