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

NAME

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

SYNOPSIS

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

DESCRIPTION

20       The functionality described on this reference page is aligned with  the
21       ISO C  standard.  Any  conflict between the requirements described here
22       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2017
23       defers to the ISO C standard.
24
25       If  s  is a null pointer, the wcrtomb() function shall be equivalent to
26       the call:
27
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‐2017  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‐2017, <wchar.h>
94
96       Portions  of  this text are reprinted and reproduced in electronic form
97       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
98       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
99       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
100       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
101       event of any discrepancy between this version and the original IEEE and
102       The  Open Group Standard, the original IEEE and The Open Group Standard
103       is the referee document. The original Standard can be  obtained  online
104       at http://www.opengroup.org/unix/online.html .
105
106       Any  typographical  or  formatting  errors that appear in this page are
107       most likely to have been introduced during the conversion of the source
108       files  to  man page format. To report such errors, see https://www.ker
109       nel.org/doc/man-pages/reporting_bugs.html .
110
111
112
113IEEE/The Open Group                  2017                          WCRTOMB(3P)
Impressum