man3/wcsnrtombs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .\" References consulted:
   6 .\"   GNU glibc-2 source code and manual
   7 .\"   Dinkumware C library reference http://www.dinkumware.com/
   8 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
   9 .\"
  10 .TH WCSNRTOMBS 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  11 .SH NAME
  12 wcsnrtombs \- convert a wide-character string to a multibyte string
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <wchar.h>
  19 .PP
  20 .BI "size_t wcsnrtombs(char *restrict " dest ", const wchar_t **restrict " src ,
  21 .BI "                  size_t " nwc ", size_t " len \
  22 ", mbstate_t *restrict " ps );
  23 .fi
  24 .PP
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .PP
  30 .BR wcsnrtombs ():
  31 .nf
  32     Since glibc 2.10:
  33         _POSIX_C_SOURCE >= 200809L
  34     Before glibc 2.10:
  35         _GNU_SOURCE
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR wcsnrtombs ()
  40 function is like the
  41 .BR wcsrtombs (3)
  42 function,
  43 except that the number of wide characters to be converted,
  44 starting at
  45 .IR *src ,
  46 is limited to
  47 .IR nwc .
  48 .PP
  49 If
  50 .I dest
  51 is not NULL,
  52 the
  53 .BR wcsnrtombs ()
  54 function converts
  55 at most
  56 .I nwc
  57 wide characters from
  58 the wide-character string
  59 .I *src
  60 to a multibyte string starting at
  61 .IR dest .
  62 At most
  63 .I len
  64 bytes are written to
  65 .IR dest .
  66 The shift state
  67 .I *ps
  68 is updated.
  69 The conversion is effectively performed by repeatedly
  70 calling
  71 .IR "wcrtomb(dest, *src, ps)" ,
  72 as long as this call succeeds,
  73 and then incrementing
  74 .I dest
  75 by the
  76 number of bytes written and
  77 .I *src
  78 by one.
  79 The conversion can stop for three reasons:
  80 .IP 1. 3
  81 A wide character has been encountered that can not be represented as a
  82 multibyte sequence (according to the current locale).
  83 In this case,
  84 .I *src
  85 is left pointing to the invalid wide character,
  86 .I (size_t)\ \-1
  87 is returned,
  88 and
  89 .I errno
  90 is set to
  91 .BR EILSEQ .
  92 .IP 2.
  93 .I nwc
  94 wide characters have been
  95 converted without encountering a null wide character (L\(aq\e0\(aq),
  96 or the length limit forces a stop.
  97 In this case,
  98 .I *src
  99 is left pointing
 100 to the next wide character to be converted, and the number of bytes written
 101 to
 102 .I dest
 103 is returned.
 104 .IP 3.
 105 The wide-character string has been completely converted, including the
 106 terminating null wide character (which has the side effect of bringing back
 107 .I *ps
 108 to the initial state).
 109 In this case,
 110 .I *src
 111 is set to NULL, and the number
 112 of bytes written to
 113 .IR dest ,
 114 excluding the terminating null byte (\(aq\e0\(aq), is
 115 returned.
 116 .PP
 117 If
 118 .I dest
 119 is NULL,
 120 .I len
 121 is ignored,
 122 and the conversion proceeds as above,
 123 except that the converted bytes are not written out to memory, and that
 124 no destination length limit exists.
 125 .PP
 126 In both of the above cases,
 127 if
 128 .I ps
 129 is NULL, a static anonymous
 130 state known only to the
 131 .BR wcsnrtombs ()
 132 function is used instead.
 133 .PP
 134 The programmer must ensure that there is room for at least
 135 .I len
 136 bytes
 137 at
 138 .IR dest .
 139 .SH RETURN VALUE
 140 The
 141 .BR wcsnrtombs ()
 142 function returns
 143 the number of bytes that make up the
 144 converted part of multibyte sequence,
 145 not including the terminating null byte.
 146 If a wide character was encountered which
 147 could not be converted,
 148 .I (size_t)\ \-1
 149 is returned, and
 150 .I errno
 151 set to
 152 .BR EILSEQ .
 153 .SH ATTRIBUTES
 154 For an explanation of the terms used in this section, see
 155 .BR attributes (7).
 156 .ad l
 157 .nh
 158 .TS
 159 allbox;
 160 lb lb lbx
 161 l l l.
 162 Interface       Attribute       Value
 163 T{
 164 .BR wcsnrtombs ()
 165 T}      Thread safety   T{
 166 MT-Unsafe race:wcsnrtombs/!ps
 167 T}
 168 .TE
 169 .hy
 170 .ad
 171 .sp 1
 172 .SH CONFORMING TO
 173 POSIX.1-2008.
 174 .SH NOTES
 175 The behavior of
 176 .BR wcsnrtombs ()
 177 depends on the
 178 .B LC_CTYPE
 179 category of the
 180 current locale.
 181 .PP
 182 Passing NULL as
 183 .I ps
 184 is not multithread safe.
 185 .SH SEE ALSO
 186 .BR iconv (3),
 187 .BR mbsinit (3),
 188 .BR wcsrtombs (3)