man3/wcsnrtombs.3

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