.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
+.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" GNU glibc-2 source code and manual
.\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\" 2000-11-15 aeb, fixed prototype
.\"
-.TH ICONV 3 2008-09-08 "GNU" "Linux Programmer's Manual"
+.TH ICONV 3 2012-05-10 "GNU" "Linux Programmer's Manual"
.SH NAME
iconv \- perform character set conversion
.SH SYNOPSIS
.BI " char **" outbuf ", size_t *" outbytesleft );
.fi
.SH DESCRIPTION
-The argument \fIcd\fP must be a conversion descriptor created using the
-function
-.BR iconv_open (3).
+The
+.BR iconv ()
+function converts a sequence of characters in one character encoding
+to a sequence of characters in another character encoding.
+The
+.I cd
+argument is a conversion descriptor,
+previously created by a call to
+.BR iconv_open (3);
+the conversion descriptor defines the character encodings that
+.BR iconv ()
+uses for the conversion.
+The
+.I inbuf
+argument is the address of a variable that points to
+the first character of the input sequence;
+.I inbytesleft
+indicates the number of bytes in that buffer.
+The
+.I outbuf
+argument is the address of a variable that points to
+the first byte available in the output buffer;
+.I outbytesleft
+indicates the number of bytes available in the output buffer.
.PP
The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL.
In this case, the
to an update to the conversion state without producing any output bytes;
such input is called a \fIshift sequence\fP.
The conversion can stop for four reasons:
-.PP
-1. An invalid multibyte sequence is encountered in the input.
-In this case
+.IP 1. 3
+An invalid multibyte sequence is encountered in the input.
+In this case,
it sets \fIerrno\fP to \fBEILSEQ\fP and returns
.IR (size_t)\ \-1 .
\fI*inbuf\fP
is left pointing to the beginning of the invalid multibyte sequence.
-.PP
-2. The input byte sequence has been entirely converted,
+.IP 2.
+The input byte sequence has been entirely converted,
that is, \fI*inbytesleft\fP has gone down to 0.
-In this case
+In this case,
.BR iconv ()
returns the number of
nonreversible conversions performed during this call.
-.PP
-3. An incomplete multibyte sequence is encountered in the input, and the
+.IP 3.
+An incomplete multibyte sequence is encountered in the input, and the
input byte sequence terminates after it.
-In this case it sets \fIerrno\fP to
+In this case, it sets \fIerrno\fP to
\fBEINVAL\fP and returns
.IR (size_t)\ \-1 .
\fI*inbuf\fP is left pointing to the
beginning of the incomplete multibyte sequence.
-.PP
-4. The output buffer has no more room for the next converted character.
-In this case it sets \fIerrno\fP to \fBE2BIG\fP and returns
+.IP 4.
+The output buffer has no more room for the next converted character.
+In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns
.IR (size_t)\ \-1 .
.PP
A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
In this case, the
.BR iconv ()
function sets \fIcd\fP's conversion state to the initial state.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR iconv ()
function returns the number of characters converted in a
An incomplete multibyte sequence has been encountered in the input.
.SH VERSIONS
This function is available in glibc since version 2.1.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
POSIX.1-2001.
-.SH "SEE ALSO"
+.SH NOTES
+Although
+.I inbuf
+and
+.I outbuf
+are typed as
+.IR "char\ **" ,
+this does not mean that the objects they point can be interpreted
+as C strings or as arrays of characters:
+the interpretation of character byte sequences is
+handled internally by the conversion functions.
+In some encodings, a zero byte may be a valid part of a multibyte character.
+
+The caller of
+.BR iconv ()
+must ensure that the pointers passed to the function are suitable
+for accessing characters in the appropriate character set.
+This includes ensuring correct alignment on platforms that have
+tight restrictions on alignment.
+.SH SEE ALSO
.BR iconv_close (3),
.BR iconv_open (3)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
