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 <stdio.h>
16
17       size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);
18
19

DESCRIPTION

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

RETURN VALUE

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

ERRORS

61       The wcrtomb() function may fail if:
62
63       EINVAL ps  points  to  an  object  that  contains an invalid conversion
64              state.
65
66       EILSEQ Invalid wide-character code is detected.
67
68
69       The following sections are informative.
70

EXAMPLES

72       None.
73

APPLICATION USAGE

75       None.
76

RATIONALE

78       None.
79

FUTURE DIRECTIONS

81       None.
82

SEE ALSO

84       mbsinit(),  the  Base  Definitions  volume   of   IEEE Std 1003.1-2001,
85       <wchar.h>
86

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