man3/wcrtomb.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH wcrtomb 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 wcrtomb \- convert a wide character to a multibyte sequence
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .PP
  22 .BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \
  23 ", mbstate_t *restrict " ps );
  24 .fi
  25 .SH DESCRIPTION
  26 The main case for this function is when
  27 .I s
  28 is
  29 not NULL and
  30 .I wc
  31 is not a null wide character (L\[aq]\e0\[aq]).
  32 In this case, the
  33 .BR wcrtomb ()
  34 function
  35 converts the wide character
  36 .I wc
  37 to its multibyte representation and stores it
  38 at the beginning of the character
  39 array pointed to by
  40 .IR s .
  41 It updates the shift state
  42 .IR *ps ,
  43 and
  44 returns the length of said multibyte representation,
  45 that is, the number of bytes
  46 written at
  47 .IR s .
  48 .PP
  49 A different case is when
  50 .I s
  51 is not NULL,
  52 but
  53 .I wc
  54 is a null wide character (L\[aq]\e0\[aq]).
  55 In this case, the
  56 .BR wcrtomb ()
  57 function stores at
  58 the character array pointed to by
  59 .I s
  60 the shift sequence needed to
  61 bring
  62 .I *ps
  63 back to the initial state,
  64 followed by a \[aq]\e0\[aq] byte.
  65 It updates the shift state
  66 .I *ps
  67 (i.e., brings
  68 it into the initial state),
  69 and returns the length of the shift sequence plus
  70 one, that is, the number of bytes written at
  71 .IR s .
  72 .PP
  73 A third case is when
  74 .I s
  75 is NULL.
  76 In this case,
  77 .I wc
  78 is ignored,
  79 and the function effectively returns
  80 .PP
  81 .in +4n
  82 .EX
  83 wcrtomb(buf, L\[aq]\e0\[aq], ps)
  84 .EE
  85 .in
  86 .PP
  87 where
  88 .I buf
  89 is an internal anonymous buffer.
  90 .PP
  91 In all of the above cases, if
  92 .I ps
  93 is NULL, a static anonymous
  94 state known only to the
  95 .BR wcrtomb ()
  96 function is used instead.
  97 .SH RETURN VALUE
  98 The
  99 .BR wcrtomb ()
 100 function returns the number of
 101 bytes that have been or would
 102 have been written to the byte array at
 103 .IR s .
 104 If
 105 .I wc
 106 can not be
 107 represented as a multibyte sequence (according to the current locale),
 108 .I (size_t)\ \-1
 109 is returned, and
 110 .I errno
 111 set to
 112 .BR EILSEQ .
 113 .SH ATTRIBUTES
 114 For an explanation of the terms used in this section, see
 115 .BR attributes (7).
 116 .TS
 117 allbox;
 118 lbx lb lb
 119 l l l.
 120 Interface       Attribute       Value
 121 T{
 122 .na
 123 .nh
 124 .BR wcrtomb ()
 125 T}      Thread safety   MT-Unsafe race:wcrtomb/!ps
 126 .TE
 127 .sp 1
 128 .SH STANDARDS
 129 C11, POSIX.1-2008.
 130 .SH HISTORY
 131 POSIX.1-2001, C99.
 132 .SH NOTES
 133 The behavior of
 134 .BR wcrtomb ()
 135 depends on the
 136 .B LC_CTYPE
 137 category of the
 138 current locale.
 139 .PP
 140 Passing NULL as
 141 .I ps
 142 is not multithread safe.
 143 .SH SEE ALSO
 144 .BR mbsinit (3),
 145 .BR wcsrtombs (3)