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