man3/wcsrtombs.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 .\"   ISO/IEC 9899:1999
  10 .\"
  11 .TH WCSRTOMBS 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  12 .SH NAME
  13 wcsrtombs \- convert a wide-character string to a multibyte string
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <wchar.h>
  20 .PP
  21 .BI "size_t wcsrtombs(char *restrict " dest ", const wchar_t **restrict " src ,
  22 .BI "                 size_t " len ", mbstate_t *restrict " ps );
  23 .fi
  24 .SH DESCRIPTION
  25 If
  26 .I dest
  27 is not NULL,
  28 the
  29 .BR wcsrtombs ()
  30 function converts
  31 the wide-character string
  32 .I *src
  33 to a multibyte string starting at
  34 .IR dest .
  35 At most
  36 .I len
  37 bytes are written to
  38 .IR dest .
  39 The shift state
  40 .I *ps
  41 is updated.
  42 The conversion is effectively performed by repeatedly
  43 calling
  44 .IR "wcrtomb(dest, *src, ps)" ,
  45 as long as this call succeeds,
  46 and then incrementing
  47 .I dest
  48 by the
  49 number of bytes written and
  50 .I *src
  51 by one.
  52 The conversion can stop for three reasons:
  53 .IP 1. 3
  54 A wide character has been encountered that can not be represented as a
  55 multibyte sequence (according to the current locale).
  56 In this case,
  57 .I *src
  58 is left pointing to the invalid wide character,
  59 .I (size_t)\ \-1
  60 is returned,
  61 and
  62 .I errno
  63 is set to
  64 .BR EILSEQ .
  65 .IP 2.
  66 The length limit forces a stop.
  67 In this case,
  68 .I *src
  69 is left pointing
  70 to the next wide character to be converted,
  71 and the number of bytes written to
  72 .I dest
  73 is returned.
  74 .IP 3.
  75 The wide-character string has been completely converted, including the
  76 terminating null wide character (L\(aq\e0\(aq),
  77 which has the side effect of bringing back
  78 .I *ps
  79 to the initial state.
  80 In this case,
  81 .I *src
  82 is set to NULL, and the number
  83 of bytes written to
  84 .IR dest ,
  85 excluding the terminating null byte (\(aq\e0\(aq),
  86 is returned.
  87 .PP
  88 If
  89 .I dest
  90 is NULL,
  91 .I len
  92 is ignored,
  93 and the conversion proceeds as above, except that the converted bytes
  94 are not written out to memory, and that
  95 no length limit exists.
  96 .PP
  97 In both of the above cases,
  98 if
  99 .I ps
 100 is NULL, a static anonymous
 101 state known only to the
 102 .BR wcsrtombs ()
 103 function is used instead.
 104 .PP
 105 The programmer must ensure that there is room for at least
 106 .I len
 107 bytes
 108 at
 109 .IR dest .
 110 .SH RETURN VALUE
 111 The
 112 .BR wcsrtombs ()
 113 function returns
 114 the number of bytes that make up the
 115 converted part of multibyte sequence,
 116 not including the terminating null byte.
 117 If a wide character was encountered
 118 which could not be converted,
 119 .I (size_t)\ \-1
 120 is returned, and
 121 .I errno
 122 set to
 123 .BR EILSEQ .
 124 .SH ATTRIBUTES
 125 For an explanation of the terms used in this section, see
 126 .BR attributes (7).
 127 .ad l
 128 .nh
 129 .TS
 130 allbox;
 131 lb lb lbx
 132 l l l.
 133 Interface       Attribute       Value
 134 T{
 135 .BR wcsrtombs ()
 136 T}      Thread safety   T{
 137 MT-Unsafe race:wcsrtombs/!ps
 138 T}
 139 .TE
 140 .hy
 141 .ad
 142 .sp 1
 143 .SH CONFORMING TO
 144 POSIX.1-2001, POSIX.1-2008, C99.
 145 .SH NOTES
 146 The behavior of
 147 .BR wcsrtombs ()
 148 depends on the
 149 .B LC_CTYPE
 150 category of the
 151 current locale.
 152 .PP
 153 Passing NULL as
 154 .I ps
 155 is not multithread safe.
 156 .SH SEE ALSO
 157 .BR iconv (3),
 158 .BR mbsinit (3),
 159 .BR wcrtomb (3),
 160 .BR wcsnrtombs (3),
 161 .BR wcstombs (3)