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  2017-09-15 "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 *" s ", wchar_t " wc ", mbstate_t *" 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     wcrtomb(buf, L\(aq\e0\(aq, ps)
  82 .PP
  83 where
  84 .I buf
  85 is an internal anonymous buffer.
  86 .PP
  87 In all of the above cases, if
  88 .I ps
  89 is NULL, a static anonymous
  90 state known only to the
  91 .BR wcrtomb ()
  92 function is used instead.
  93 .SH RETURN VALUE
  94 The
  95 .BR wcrtomb ()
  96 function returns the number of
  97 bytes that have been or would
  98 have been written to the byte array at
  99 .IR s .
 100 If
 101 .I wc
 102 can not be
 103 represented as a multibyte sequence (according to the current locale),
 104 .I (size_t)\ \-1
 105 is returned, and
 106 .I errno
 107 set to
 108 .BR EILSEQ .
 109 .SH ATTRIBUTES
 110 For an explanation of the terms used in this section, see
 111 .BR attributes (7).
 112 .TS
 113 allbox;
 114 lb lb lbw26
 115 l l l.
 116 Interface       Attribute       Value
 117 T{
 118 .BR wcrtomb ()
 119 T}      Thread safety   MT-Unsafe race:wcrtomb/!ps
 120 .TE
 121 .sp 1
 122 .SH CONFORMING TO
 123 POSIX.1-2001, POSIX.1-2008, C99.
 124 .SH NOTES
 125 The behavior of
 126 .BR wcrtomb ()
 127 depends on the
 128 .B LC_CTYPE
 129 category of the
 130 current locale.
 131 .PP
 132 Passing NULL as
 133 .I ps
 134 is not multithread safe.
 135 .SH SEE ALSO
 136 .BR mbsinit (3),
 137 .BR wcsrtombs (3)