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  2014-03-18 "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 .sp
  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 .SS Multithreading (see pthreads(7))
  86 The
  87 .BR wctomb ()
  88 function is not thread-safe.
  89 .SH CONFORMING TO
  90 C99.
  91 .SH NOTES
  92 The behavior of
  93 .BR wctomb ()
  94 depends on the
  95 .B LC_CTYPE
  96 category of the
  97 current locale.
  98 .PP
  99 The function
 100 .BR wcrtomb (3)
 101 provides
 102 a better interface to the same functionality.
 103 .SH SEE ALSO
 104 .BR MB_CUR_MAX (3),
 105 .BR mblen (3),
 106 .BR mbstowcs (3),
 107 .BR mbtowc (3),
 108 .BR wcrtomb (3),
 109 .BR wcstombs (3)