diff options
Diffstat (limited to 'man3/wcsnrtombs.3')
| -rw-r--r-- | man3/wcsnrtombs.3 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 new file mode 100644 index 0000000..21ad0fa --- /dev/null +++ b/man3/wcsnrtombs.3 @@ -0,0 +1,190 @@ +'\" t +.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> +.\" +.\" 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 wcsnrtombs 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +wcsnrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <wchar.h> +.PP +.BI "size_t wcsnrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " nwc ", 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 wcsnrtombs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsnrtombs () +function is like the +.BR wcsrtombs (3) +function, +except that the number of wide characters to be converted, +starting at +.IR *src , +is limited to +.IR nwc . +.PP +If +.I dest +is not NULL, +the +.BR wcsnrtombs () +function converts +at most +.I nwc +wide characters from +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] +.I nwc +wide characters have been +converted without encountering a null wide character (L\[aq]\e0\[aq]), +or 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 (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. +.PP +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 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 wcsnrtombs () +function is used instead. +.PP +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsnrtombs () +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 wcsnrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsnrtombs/!ps +T} +.TE +.sp 1 +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR wcsnrtombs () +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 mbsinit (3), +.BR wcsrtombs (3) |