.\" 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 WCRTOMB 3 2011-09-28 "GNU" "Linux Programmer's Manual"
+.TH WCRTOMB 3 2014-03-18 "GNU" "Linux Programmer's Manual"
.SH NAME
wcrtomb \- convert a wide character to a multibyte sequence
.SH SYNOPSIS
.BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-The main case for this function is when \fIs\fP is
-not NULL and \fIwc\fP is not a null wide character (L\(aq\\0\(aq).
+The main case for this function is when
+.I s
+is
+not NULL and
+.I wc
+is not a null wide character (L\(aq\\0\(aq).
In this case, the
.BR wcrtomb ()
function
-converts the wide character \fIwc\fP
+converts the wide character
+.I wc
to its multibyte representation and stores it
at the beginning of the character
-array pointed to by \fIs\fP.
-It updates the shift state \fI*ps\fP, and
+array pointed to by
+.IR s .
+It updates the shift state
+.IR *ps ,
+and
returns the length of said multibyte representation,
that is, the number of bytes
-written at \fIs\fP.
+written at
+.IR s .
.PP
-A different case is when \fIs\fP is not NULL,
-but \fIwc\fP is a null wide character (L\(aq\\0\(aq).
-In this
-case the
+A different case is when
+.I s
+is not NULL,
+but
+.I wc
+is a null wide character (L\(aq\\0\(aq).
+In this case, the
.BR wcrtomb ()
function stores at
the character array pointed to by
-\fIs\fP the shift sequence needed to
-bring \fI*ps\fP back to the initial state,
+.I s
+the shift sequence needed to
+bring
+.I *ps
+back to the initial state,
followed by a \(aq\\0\(aq byte.
-It updates the shift state \fI*ps\fP (i.e., brings
+It updates the shift state
+.I *ps
+(i.e., brings
it into the initial state),
and returns the length of the shift sequence plus
-one, that is, the number of bytes written at \fIs\fP.
+one, that is, the number of bytes written at
+.IR s .
.PP
-A third case is when \fIs\fP is NULL.
-In this case \fIwc\fP is ignored,
+A third case is when
+.I s
+is NULL.
+In this case,
+.I wc
+is ignored,
and the function effectively returns
wcrtomb(buf, L\(aq\\0\(aq, ps)
.I buf
is an internal anonymous buffer.
.PP
-In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
-state only known to the
+In all of the above cases, if
+.I ps
+is NULL, a static anonymous
+state known only to the
.BR wcrtomb ()
function is used instead.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR wcrtomb ()
function returns the number of
bytes that have been or would
-have been written to the byte array at \fIs\fP.
-If \fIwc\fP can not be
+have been written to the byte array at
+.IR s .
+If
+.I wc
+can not be
represented as a multibyte sequence (according to the current locale),
.I (size_t)\ \-1
-is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
-.SH "CONFORMING TO"
+is returned, and
+.I errno
+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 mbsinit (3),
.BR wcsrtombs (3)
+.SH COLOPHON
+This page is part of release 3.68 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/.