From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man3/wcsrtombs.3 | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 man/man3/wcsrtombs.3 (limited to 'man/man3/wcsrtombs.3') diff --git a/man/man3/wcsrtombs.3 b/man/man3/wcsrtombs.3 new file mode 100644 index 0000000..9235dfb --- /dev/null +++ b/man/man3/wcsrtombs.3 @@ -0,0 +1,164 @@ +'\" 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 +.\" ISO/IEC 9899:1999 +.\" +.TH wcsrtombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcsrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " len ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +the +.BR wcsrtombs () +function converts +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 +.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 +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +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 +.BR EILSEQ . +.IP \[bu] +The length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, +and the number of bytes written to +.I dest +is returned. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (L\[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 bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), +is returned. +.P +If +.I 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. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsrtombs () +function is used instead. +.P +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 +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered +which could not be converted, +.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 wcsrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsrtombs/!ps +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcsrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +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) -- cgit v1.2.3