1WCRTOMB(3P)                POSIX Programmer's Manual               WCRTOMB(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
11

NAME

13       wcrtomb — convert a wide-character code to a character (restartable)
14

SYNOPSIS

16       #include <wchar.h>
17
18       size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);
19

DESCRIPTION

21       The functionality described on this reference page is aligned with  the
22       ISO C  standard.  Any  conflict between the requirements described here
23       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2008
24       defers to the ISO C standard.
25
26       If  s  is a null pointer, the wcrtomb() function shall be equivalent to
27       the call:
28
29           wcrtomb(buf, L'\0', ps)
30
31       where buf is an internal buffer.
32
33       If s is not a null pointer, the wcrtomb() function shall determine  the
34       number  of  bytes needed to represent the character that corresponds to
35       the wide character given by wc (including  any  shift  sequences),  and
36       store  the  resulting bytes in the array whose first element is pointed
37       to by s.  At most {MB_CUR_MAX} bytes are stored. If wc is a  null  wide
38       character,  a null byte shall be stored, preceded by any shift sequence
39       needed  to  restore  the  initial  shift  state.  The  resulting  state
40       described shall be the initial conversion state.
41
42       If  ps  is  a  null  pointer,  the wcrtomb() function shall use its own
43       internal mbstate_t object, which is initialized at program start-up  to
44       the  initial  conversion state. Otherwise, the mbstate_t object pointed
45       to by ps shall be used to completely describe  the  current  conversion
46       state  of  the  associated character sequence. The implementation shall
47       behave as if no function defined in this volume of  POSIX.1‐2008  calls
48       wcrtomb().
49
50       The wcrtomb() function need not be thread-safe if called with a NULL ps
51       argument.
52
53       The behavior of this function shall be affected by the  LC_CTYPE  cate‐
54       gory of the current locale.
55
56       The  wcrtomb()  function  shall not change the setting of errno if suc‐
57       cessful.
58

RETURN VALUE

60       The wcrtomb() function shall return the number of bytes stored  in  the
61       array  object  (including  any shift sequences). When wc is not a valid
62       wide character, an encoding error shall occur. In this case, the  func‐
63       tion  shall  store  the  value of the macro [EILSEQ] in errno and shall
64       return (size_t)−1; the conversion state shall be undefined.
65

ERRORS

67       The wcrtomb() function shall fail if:
68
69       EILSEQ An invalid wide-character code is detected.
70
71       The wcrtomb() function may fail if:
72
73       EINVAL ps points to an  object  that  contains  an  invalid  conversion
74              state.
75
76       The following sections are informative.
77

EXAMPLES

79       None.
80

APPLICATION USAGE

82       None.
83

RATIONALE

85       None.
86

FUTURE DIRECTIONS

88       None.
89

SEE ALSO

91       mbsinit(), wcsrtombs()
92
93       The Base Definitions volume of POSIX.1‐2008, <wchar.h>
94
96       Portions  of  this text are reprinted and reproduced in electronic form
97       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
98       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
99       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
100       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
101       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
102       event of any discrepancy between this version and the original IEEE and
103       The Open Group Standard, the original IEEE and The Open Group  Standard
104       is  the  referee document. The original Standard can be obtained online
105       at http://www.unix.org/online.html .
106
107       Any typographical or formatting errors that appear  in  this  page  are
108       most likely to have been introduced during the conversion of the source
109       files to man page format. To report such errors,  see  https://www.ker
110       nel.org/doc/man-pages/reporting_bugs.html .
111
112
113
114IEEE/The Open Group                  2013                          WCRTOMB(3P)
Impressum