.\" 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
.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\" ISO/IEC 9899:1999
.\"
-.TH WCSRTOMBS 3 2011-09-28 "GNU" "Linux Programmer's Manual"
+.TH WCSRTOMBS 3 2014-03-18 "GNU" "Linux Programmer's Manual"
.SH NAME
wcsrtombs \- convert a wide-character string to a multibyte string
.SH SYNOPSIS
.BI " size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-If \fIdest\fP is not a NULL pointer,
+If
+.I dest
+is not NULL,
the
.BR wcsrtombs ()
function converts
-the wide-character string \fI*src\fP to a multibyte string starting at
-\fIdest\fP.
-At most \fIlen\fP bytes are written to \fIdest\fP.
+the wide-character string
+.I *src
+to a multibyte string starting at
+.IR dest .
+At most
+.I len
+bytes are written to
+.IR dest .
The shift state
-\fI*ps\fP is updated.
+.I *ps
+is updated.
The conversion is effectively performed by repeatedly
calling
.IR "wcrtomb(dest, *src, ps)" ,
as long as this call succeeds,
-and then incrementing \fIdest\fP by the
-number of bytes written and \fI*src\fP
+and then incrementing
+.I dest
+by the
+number of bytes written and
+.I *src
by one.
The conversion can stop for three reasons:
.PP
1. A wide character has been encountered that can not be represented as a
multibyte sequence (according to the current locale).
-In this case \fI*src\fP
+In this case,
+.I *src
is left pointing to the invalid wide character,
.I (size_t)\ \-1
is returned,
and
.I errno
-is set to \fBEILSEQ\fP.
+is set to
+.BR EILSEQ .
.PP
2. The length limit forces a stop.
-In this case \fI*src\fP is left pointing
+In this case,
+.I *src
+is left pointing
to the next wide character to be converted,
and the number of bytes written to
-\fIdest\fP is returned.
+.I dest
+is returned.
.PP
3. The wide-character string has been completely converted, including the
terminating null wide character (L\(aq\\0\(aq),
-which has the side effect of bringing back \fI*ps\fP
+which has the side effect of bringing back
+.I *ps
to the initial state.
-In this case \fI*src\fP is set to NULL, and the number
-of bytes written to \fIdest\fP, excluding the terminating null, is returned.
+In this case,
+.I *src
+is set to NULL, and the number
+of bytes written to
+.IR dest ,
+excluding the terminating null byte (\(aq\\0\(aq),
+is returned.
.PP
-If \fIdest\fP is NULL, \fIlen\fP is ignored,
+If
+.IR dest
+is NULL,
+.I len
+is ignored,
and the conversion proceeds as above, except that the converted bytes
are not written out to memory, and that
no length limit exists.
.PP
In both of the above cases,
-if \fIps\fP is a NULL pointer, a static anonymous
-state only known to the wcsrtombs function is used instead.
+if
+.I ps
+is NULL, a static anonymous
+state known only to the
+.BR wcsrtombs ()
+function is used instead.
.PP
-The programmer must ensure that there is room for at least \fIlen\fP bytes
-at \fIdest\fP.
-.SH "RETURN VALUE"
+The programmer must ensure that there is room for at least
+.I len
+bytes
+at
+.IR dest .
+.SH RETURN VALUE
The
.BR wcsrtombs ()
function returns
.I (size_t)\ \-1
is returned, and
.I errno
-set to \fBEILSEQ\fP.
-.SH "CONFORMING TO"
+set to
+.BR EILSEQ .
+.SH CONFORMING TO
C99.
.SH NOTES
The behavior of
category of the
current locale.
.PP
-Passing NULL as \fIps\fP is not multithread safe.
-.SH "SEE ALSO"
+Passing NULL as
+.I ps
+is not multithread safe.
+.SH SEE ALSO
.BR iconv (3),
+.BR mbsinit (3),
+.BR wcrtomb (3),
.BR wcsnrtombs (3),
.BR wcstombs (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
