1WCTOMB(3P)                 POSIX Programmer's Manual                WCTOMB(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       wctomb - convert a wide-character code to a character
13

SYNOPSIS

15       #include <stdlib.h>
16
17       int wctomb(char *s, wchar_t wchar);
18
19

DESCRIPTION

21       The wctomb() function shall determine the number  of  bytes  needed  to
22       represent  the character corresponding to the wide-character code whose
23       value is wchar (including any change in  the  shift  state).  It  shall
24       store  the  character  representation  (possibly multiple bytes and any
25       special bytes to change shift state) in the array object pointed to  by
26       s  (if  s  is  not a null pointer). At most {MB_CUR_MAX} bytes shall be
27       stored. If wchar is 0, a null byte shall be  stored,  preceded  by  any
28       shift  sequence needed to restore the initial shift state, and wctomb()
29       shall be left in the initial shift state.
30
31       The behavior of this function is affected by the LC_CTYPE  category  of
32       the current locale. For a state-dependent encoding, this function shall
33       be placed into its initial state by a  call  for  which  its  character
34       pointer  argument,  s,  is  a null pointer.  Subsequent calls with s as
35       other than a null pointer shall cause the internal state of  the  func‐
36       tion  to be altered as necessary. A call with s as a null pointer shall
37       cause this function to return a non-zero value if encodings have  state
38       dependency,  and 0 otherwise. Changing the LC_CTYPE category causes the
39       shift state of this function to be unspecified.
40
41       The wctomb() function need not be reentrant. A  function  that  is  not
42       required to be reentrant is not required to be thread-safe.
43
44       The  implementation shall behave as if no function defined in this vol‐
45       ume of IEEE Std 1003.1-2001 calls wctomb().
46

RETURN VALUE

48       If s is a null pointer, wctomb() shall return a non-zero or 0 value, if
49       character  encodings,  respectively,  do or do not have state-dependent
50       encodings. If s is not a null pointer, wctomb() shall return -1 if  the
51       value  of wchar does not correspond to a valid character, or return the
52       number of bytes that constitute  the  character  corresponding  to  the
53       value of wchar.
54
55       In  no  case  shall the value returned be greater than the value of the
56       {MB_CUR_MAX} macro.
57

ERRORS

59       No errors are defined.
60
61       The following sections are informative.
62

EXAMPLES

64       None.
65

APPLICATION USAGE

67       None.
68

RATIONALE

70       None.
71

FUTURE DIRECTIONS

73       None.
74

SEE ALSO

76       mblen(), mbtowc(), mbstowcs(), wcstombs(), the Base Definitions  volume
77       of IEEE Std 1003.1-2001, <stdlib.h>
78

80       Portions  of  this text are reprinted and reproduced in electronic form
81       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
82       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
83       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
84       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
85       event of any discrepancy between this version and the original IEEE and
86       The  Open Group Standard, the original IEEE and The Open Group Standard
87       is the referee document. The original Standard can be  obtained  online
88       at http://www.opengroup.org/unix/online.html .
89
90
91
92IEEE/The Open Group                  2003                           WCTOMB(3P)
Impressum