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

NAME

6       wcrtomb - convert a wide-character code to a character (restartable)
7

SYNOPSIS

9       #include <stdio.h>
10
11       size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);
12
13

DESCRIPTION

15       If  s  is a null pointer, the wcrtomb() function shall be equivalent to
16       the call:
17
18
19              wcrtomb(buf, L'\0', ps)
20
21       where buf is an internal buffer.
22
23       If s is not a null pointer, the wcrtomb() function shall determine  the
24       number  of  bytes needed to represent the character that corresponds to
25       the wide character given by wc (including  any  shift  sequences),  and
26       store  the  resulting bytes in the array whose first element is pointed
27       to by s. At most {MB_CUR_MAX} bytes are stored. If wc is  a  null  wide
28       character,  a null byte shall be stored, preceded by any shift sequence
29       needed  to  restore  the  initial  shift  state.  The  resulting  state
30       described shall be the initial conversion state.
31
32       If  ps  is  a  null  pointer,  the wcrtomb() function shall use its own
33       internal mbstate_t object, which is initialized at program start-up  to
34       the  initial  conversion state. Otherwise, the mbstate_t object pointed
35       to by ps shall be used to completely describe  the  current  conversion
36       state  of  the  associated character sequence. The implementation shall
37       behave as if no function defined in this volume of IEEE Std 1003.1-2001
38       calls wcrtomb().
39
40       If  the  application  uses  any  of the _POSIX_THREAD_SAFE_FUNCTIONS or
41       _POSIX_THREADS functions, the application shall ensure  that  the  wcr‐
42       tomb() function is called with a non-NULL ps argument.
43
44       The  behavior  of this function shall be affected by the LC_CTYPE cate‐
45       gory of the current locale.
46

RETURN VALUE

48       The wcrtomb() function shall return the number of bytes stored  in  the
49       array  object  (including  any shift sequences). When wc is not a valid
50       wide character, an encoding error shall occur.  In this case, the func‐
51       tion  shall  store  the  value of the macro [EILSEQ] in errno and shall
52       return (size_t)-1; the conversion state shall be undefined.
53

ERRORS

55       The wcrtomb() function may fail if:
56
57       EINVAL ps points to an  object  that  contains  an  invalid  conversion
58              state.
59
60       EILSEQ Invalid wide-character code is detected.
61
62
63       The following sections are informative.
64

EXAMPLES

66       None.
67

APPLICATION USAGE

69       None.
70

RATIONALE

72       None.
73

FUTURE DIRECTIONS

75       None.
76

SEE ALSO

78       mbsinit()  ,  the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
79       <wchar.h>
80

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