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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .ad l
  87 .nh
  88 .TS
  89 allbox;
  90 lbx lb lb
  91 l l l.
  92 Interface       Attribute       Value
  93 T{
  94 .BR wctomb ()
  95 T}      Thread safety   MT-Unsafe race
  96 .TE
  97 .hy
  98 .ad
  99 .sp 1
 100 .SH STANDARDS
 101 POSIX.1-2001, POSIX.1-2008, C99.
 102 .SH NOTES
 103 The behavior of
 104 .BR wctomb ()
 105 depends on the
 106 .B LC_CTYPE
 107 category of the
 108 current locale.
 109 .PP
 110 The function
 111 .BR wcrtomb (3)
 112 provides
 113 a better interface to the same functionality.
 114 .SH SEE ALSO
 115 .BR MB_CUR_MAX (3),
 116 .BR mblen (3),
 117 .BR mbstowcs (3),
 118 .BR mbtowc (3),
 119 .BR wcrtomb (3),
 120 .BR wcstombs (3)