From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/mbsnrtowcs.3 | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 man3/mbsnrtowcs.3 (limited to 'man3/mbsnrtowcs.3') diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 new file mode 100644 index 0000000..b9d0029 --- /dev/null +++ b/man3/mbsnrtowcs.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH mbsnrtowcs 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +mbsnrtowcs \- convert a multibyte string to a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src , +.BI " size_t " nms ", size_t " len \ +", mbstate_t *restrict " ps ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR mbsnrtowcs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR mbsnrtowcs () +function is like the +.BR mbsrtowcs (3) +function, except that +the number of bytes to be converted, starting at +.IR *src , +is limited to at most +.I nms +bytes. +.PP +If +.I dest +is not NULL, the +.BR mbsnrtowcs () +function converts at +most +.I nms +bytes from the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I len +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The +conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +The +.I nms +limit forces a stop, +or +.I len +non-L\[aq]\e0\[aq] wide characters +have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the +next multibyte sequence to be converted, and the number of wide characters +written to +.I dest +is returned. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null wide character (\[aq]\e0\[aq]) +(which has the side effect of bringing back +.I *ps +to the +initial state). +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, +is returned. +.PP +According to POSIX.1, +if the input buffer ends with an incomplete character, +it is unspecified whether conversion stops at the end of +the previous character (if any), or at the end of the input buffer. +The glibc implementation adopts the former behavior. +.PP +If +.I dest +is NULL, +.I len +is ignored, and the conversion proceeds as +above, except that the converted wide characters +are not written out to memory, +and that no destination length limit exists. +.PP +In both of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsnrtowcs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +wide +characters at +.IR dest . +.SH RETURN VALUE +The +.BR mbsnrtowcs () +function returns 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 +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsnrtowcs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mbsnrtowcs/!ps +T} +.TE +.sp 1 +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR mbsnrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.PP +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsrtowcs (3) -- cgit v1.2.3