manual/LDP_man-pages/original/man3/wctomb.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .TH WCTOMB 3  1999-07-25 "GNU" "Linux Programmer's Manual"
  15 .SH NAME
  16 wctomb \- convert a wide character to a multibyte sequence
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <stdlib.h>
  20 .sp
  21 .BI "int wctomb(char *" s ", wchar_t " wc );
  22 .fi
  23 .SH DESCRIPTION
  24 If \fIs\fP is not NULL,
  25 the
  26 .BR wctomb ()
  27 function converts the wide character
  28 \fIwc\fP to its multibyte representation and stores it at the beginning of
  29 the character array pointed to by \fIs\fP.
  30 It updates the shift state, which
  31 is stored in a static anonymous variable
  32 only known to the wctomb function,
  33 and returns the length of said multibyte representation,
  34 that is, the number of
  35 bytes written at \fIs\fP.
  36 .PP
  37 The programmer must ensure that there is
  38 room for at least \fBMB_CUR_MAX\fP
  39 bytes at \fIs\fP.
  40 .PP
  41 If \fIs\fP is NULL, the
  42 .BR wctomb ()
  43 function
  44 .\" The Dinkumware doc and the Single Unix specification say this, but
  45 .\" glibc doesn't implement this.
  46 resets the shift state, only known to this function,
  47 to the initial state, and
  48 returns nonzero if the encoding has nontrivial shift state,
  49 or zero if the encoding is stateless.
  50 .SH "RETURN VALUE"
  51 If \fIs\fP is not NULL, the
  52 .BR wctomb ()
  53 function
  54 returns the number of bytes
  55 that have been written to the byte array at \fIs\fP.
  56 If \fIwc\fP can not be
  57 represented as a multibyte sequence (according
  58 to the current locale), \-1 is returned.
  59 .PP
  60 If \fIs\fP is NULL, the
  61 .BR wctomb ()
  62 function returns nonzero if the
  63 encoding has nontrivial shift state, or zero if the encoding is stateless.
  64 .SH "CONFORMING TO"
  65 C99.
  66 .SH NOTES
  67 The behavior of
  68 .BR wctomb ()
  69 depends on the
  70 .B LC_CTYPE
  71 category of the
  72 current locale.
  73 .PP
  74 This function is not multithread safe.
  75 The function
  76 .BR wcrtomb (3)
  77 provides
  78 a better interface to the same functionality.
  79 .SH "SEE ALSO"
  80 .BR MB_CUR_MAX (3),
  81 .BR wcrtomb (3),
  82 .BR wcstombs (3)