man3/wcrtomb.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 WCRTOMB 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 wcrtomb \- convert a wide character to a multibyte sequence
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .PP
  23 .BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \
  24 ", mbstate_t *restrict " ps );
  25 .fi
  26 .SH DESCRIPTION
  27 The main case for this function is when
  28 .I s
  29 is
  30 not NULL and
  31 .I wc
  32 is not a null wide character (L\(aq\e0\(aq).
  33 In this case, the
  34 .BR wcrtomb ()
  35 function
  36 converts the wide character
  37 .I wc
  38 to its multibyte representation and stores it
  39 at the beginning of the character
  40 array pointed to by
  41 .IR s .
  42 It updates the shift state
  43 .IR *ps ,
  44 and
  45 returns the length of said multibyte representation,
  46 that is, the number of bytes
  47 written at
  48 .IR s .
  49 .PP
  50 A different case is when
  51 .I s
  52 is not NULL,
  53 but
  54 .I wc
  55 is a null wide character (L\(aq\e0\(aq).
  56 In this case, the
  57 .BR wcrtomb ()
  58 function stores at
  59 the character array pointed to by
  60 .I s
  61 the shift sequence needed to
  62 bring
  63 .I *ps
  64 back to the initial state,
  65 followed by a \(aq\e0\(aq byte.
  66 It updates the shift state
  67 .I *ps
  68 (i.e., brings
  69 it into the initial state),
  70 and returns the length of the shift sequence plus
  71 one, that is, the number of bytes written at
  72 .IR s .
  73 .PP
  74 A third case is when
  75 .I s
  76 is NULL.
  77 In this case,
  78 .I wc
  79 is ignored,
  80 and the function effectively returns
  81 .PP
  82     wcrtomb(buf, L\(aq\e0\(aq, ps)
  83 .PP
  84 where
  85 .I buf
  86 is an internal anonymous buffer.
  87 .PP
  88 In all of the above cases, if
  89 .I ps
  90 is NULL, a static anonymous
  91 state known only to the
  92 .BR wcrtomb ()
  93 function is used instead.
  94 .SH RETURN VALUE
  95 The
  96 .BR wcrtomb ()
  97 function returns the number of
  98 bytes that have been or would
  99 have been written to the byte array at
 100 .IR s .
 101 If
 102 .I wc
 103 can not be
 104 represented as a multibyte sequence (according to the current locale),
 105 .I (size_t)\ \-1
 106 is returned, and
 107 .I errno
 108 set to
 109 .BR EILSEQ .
 110 .SH ATTRIBUTES
 111 For an explanation of the terms used in this section, see
 112 .BR attributes (7).
 113 .ad l
 114 .nh
 115 .TS
 116 allbox;
 117 lbx lb lb
 118 l l l.
 119 Interface       Attribute       Value
 120 T{
 121 .BR wcrtomb ()
 122 T}      Thread safety   MT-Unsafe race:wcrtomb/!ps
 123 .TE
 124 .hy
 125 .ad
 126 .sp 1
 127 .SH CONFORMING TO
 128 POSIX.1-2001, POSIX.1-2008, C99.
 129 .SH NOTES
 130 The behavior of
 131 .BR wcrtomb ()
 132 depends on the
 133 .B LC_CTYPE
 134 category of the
 135 current locale.
 136 .PP
 137 Passing NULL as
 138 .I ps
 139 is not multithread safe.
 140 .SH SEE ALSO
 141 .BR mbsinit (3),
 142 .BR wcsrtombs (3)