man3/wctomb.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 WCTOMB 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 wctomb \- convert a wide character to a multibyte sequence
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdlib.h>
  22 .PP
  23 .BI "int wctomb(char *" s ", wchar_t " wc );
  24 .fi
  25 .SH DESCRIPTION
  26 If
  27 .I s
  28 is not NULL,
  29 the
  30 .BR wctomb ()
  31 function converts the wide character
  32 .I wc
  33 to its multibyte representation and stores it at the beginning of
  34 the character array pointed to by
  35 .IR s .
  36 It updates the shift state, which
  37 is stored in a static anonymous variable
  38 known only to the
  39 .BR wctomb ()
  40 function,
  41 and returns the length of said multibyte representation,
  42 that is, the number of
  43 bytes written at
  44 .IR s .
  45 .PP
  46 The programmer must ensure that there is
  47 room for at least
  48 .B MB_CUR_MAX
  49 bytes at
  50 .IR s .
  51 .PP
  52 If
  53 .I s
  54 is NULL, the
  55 .BR wctomb ()
  56 function
  57 .\" The Dinkumware doc and the Single UNIX specification say this, but
  58 .\" glibc doesn't implement this.
  59 resets the shift state, known only to this function,
  60 to the initial state, and
  61 returns nonzero if the encoding has nontrivial shift state,
  62 or zero if the encoding is stateless.
  63 .SH RETURN VALUE
  64 If
  65 .I s
  66 is not NULL, the
  67 .BR wctomb ()
  68 function
  69 returns the number of bytes
  70 that have been written to the byte array at
  71 .IR s .
  72 If
  73 .I wc
  74 can not be
  75 represented as a multibyte sequence (according
  76 to the current locale), \-1 is returned.
  77 .PP
  78 If
  79 .I s
  80 is NULL, the
  81 .BR wctomb ()
  82 function returns nonzero if the
  83 encoding has nontrivial shift state, or zero if the encoding is stateless.
  84 .SH ATTRIBUTES
  85 For an explanation of the terms used in this section, see
  86 .BR attributes (7).
  87 .ad l
  88 .nh
  89 .TS
  90 allbox;
  91 lbx lb lb
  92 l l l.
  93 Interface       Attribute       Value
  94 T{
  95 .BR wctomb ()
  96 T}      Thread safety   MT-Unsafe race
  97 .TE
  98 .hy
  99 .ad
 100 .sp 1
 101 .SH CONFORMING TO
 102 POSIX.1-2001, POSIX.1-2008, C99.
 103 .SH NOTES
 104 The behavior of
 105 .BR wctomb ()
 106 depends on the
 107 .B LC_CTYPE
 108 category of the
 109 current locale.
 110 .PP
 111 The function
 112 .BR wcrtomb (3)
 113 provides
 114 a better interface to the same functionality.
 115 .SH SEE ALSO
 116 .BR MB_CUR_MAX (3),
 117 .BR mblen (3),
 118 .BR mbstowcs (3),
 119 .BR mbtowc (3),
 120 .BR wcrtomb (3),
 121 .BR wcstombs (3)