summaryrefslogtreecommitdiffstats
path: root/man3/mbsrtowcs.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/mbsrtowcs.346
1 files changed, 26 insertions, 20 deletions
diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3
index e613a14..6844536 100644
--- a/man3/mbsrtowcs.3
+++ b/man3/mbsrtowcs.3
@@ -9,31 +9,31 @@
.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\" ISO/IEC 9899:1999
.\"
-.TH mbsrtowcs 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH mbsrtowcs 3 2024-02-26 "Linux man-pages 6.7"
.SH NAME
-mbsrtowcs \- convert a multibyte string to a wide-character string
+mbsrtowcs \- convert a multibyte string to a wide-character string (restartable)
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
-.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src ,
-.BI " size_t " len ", mbstate_t *restrict " ps );
+.P
+.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." dsize ],
+.BI " const char **restrict " src ,
+.BI " size_t " dsize ", mbstate_t *restrict " ps );
.fi
.SH DESCRIPTION
If
.I dest
-is not NULL, the
-.BR mbsrtowcs ()
-function converts the
+is not NULL,
+convert the
multibyte string
.I *src
to a wide-character string starting at
.IR dest .
At most
-.I len
+.I dsize
wide characters are written to
.IR dest .
The shift state
@@ -63,7 +63,7 @@ and
is set to
.BR EILSEQ .
.IP \[bu]
-.I len
+.I dsize
non-L\[aq]\e0\[aq] wide characters have been stored at
.IR dest .
In this case,
@@ -86,16 +86,16 @@ is set to NULL, and the number of wide
characters written to
.IR dest ,
excluding the terminating null wide character, is returned.
-.PP
+.P
If
.I dest
is NULL,
-.I len
+.I dsize
is ignored,
and the conversion proceeds as above,
except that the converted wide characters are not written out to memory,
and that no length limit exists.
-.PP
+.P
In both of the above cases,
if
.I ps
@@ -103,16 +103,23 @@ is NULL, a static anonymous
state known only to the
.BR mbsrtowcs ()
function is used instead.
-.PP
+.P
+In order to avoid the case 2 above, the programmer should make sure
+.I dsize
+is
+greater than or equal to
+.IR "mbsrtowcs(NULL,src,0,ps)+1" .
+.P
The programmer must ensure that there is room for at least
-.I len
+.I dsize
wide
characters at
.IR dest .
+.P
+This function is a restartable version of
+.BR mbstowcs (3).
.SH RETURN VALUE
-The
-.BR mbsrtowcs ()
-function returns the number of wide characters that make
+The number of wide characters that make
up the converted part of the wide-character string, not including the
terminating null wide character.
If an invalid multibyte sequence was
@@ -140,7 +147,6 @@ T} Thread safety T{
MT-Unsafe race:mbsrtowcs/!ps
T}
.TE
-.sp 1
.SH STANDARDS
C11, POSIX.1-2008.
.SH HISTORY
@@ -152,7 +158,7 @@ depends on the
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.