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