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

NAME

6       wctomb - convert a wide-character code to a character
7

SYNOPSIS

9       #include <stdlib.h>
10
11       int wctomb(char *s, wchar_t wchar);
12
13

DESCRIPTION

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

RETURN VALUE

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

ERRORS

53       No errors are defined.
54
55       The following sections are informative.
56

EXAMPLES

58       None.
59

APPLICATION USAGE

61       None.
62

RATIONALE

64       None.
65

FUTURE DIRECTIONS

67       None.
68

SEE ALSO

70       mblen()  ,  mbtowc()  ,  mbstowcs() , wcstombs() , the Base Definitions
71       volume of IEEE Std 1003.1-2001, <stdlib.h>
72

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