wcrtomb(3c) - osol9

1wcrtomb(3C)              Standard C Library Functions              wcrtomb(3C)
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 is equivalent to the
16       call:
17
18
19       wcrtomb(buf, L'\0', ps)
20
21
22       where buf is an internal buffer.
23
24
25       If s is not a null pointer, the wcrtomb() function determines the  num‐
26       ber  of bytes needed to represent the character that corresponds to the
27       wide-character given by wc (including any shift sequences), and  stores
28       the  resulting  bytes in the array whose first element is pointed to by
29       s. At most MB_CUR_MAX bytes are stored.  If wc is a  null  wide-charac‐
30       ter,  a  null  byte is stored, preceded by any shift sequence needed to
31       restore the initial shift state. The resulting state described  is  the
32       initial conversion state.
33
34
35       If  ps  is a null pointer, the wcrtomb() function uses its own internal
36       mbstate_t object, which is initialized at program startup to  the  ini‐
37       tial conversion state.   Otherwise, the  mbstate_t object pointed to by
38       ps is used to completely describe the current conversion state  of  the
39       associated  character  sequence.  Solaris will behave as if no function
40       defined in the Solaris Reference Manual calls wcrtomb().
41
42
43       The behavior of this function is affected by the LC_CTYPE  category  of
44       the current locale.  See environ(5).
45

RETURN VALUES

47       The  wcrtomb() function returns the number of bytes stored in the array
48       object (including any shift sequences).  When wc is not a  valid  wide-
49       character, an encoding error occurs.  In this case, the function stores
50       the value of the macros EILSEQ in errno  and  returns  (size_t)−1;  the
51       conversion state is undefined.
52

ERRORS

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

USAGE

64       If ps is not a  null  pointer,  wcrtomb()  uses  the  mbstate_t  object
65       pointed  to  by ps and the function can be used safely in multithreaded
66       applications, as long as setlocale(3C) is not being  called  to  change
67       the  locale.  If  ps  is  a  null  pointer, wcrtomb() uses its internal
68       mbstate_t object and the function is Unsafe in  multithreaded  applica‐
69       tions.
70

ATTRIBUTES

72       See attributes(5) for descriptions of the following attributes:
73
74
75
76
77       ┌─────────────────────────────┬─────────────────────────────┐
78       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
79       ├─────────────────────────────┼─────────────────────────────┤
80       │Interface Stability          │Standard                     │
81       ├─────────────────────────────┼─────────────────────────────┤
82       │MT-Level                     │See NOTES below              │
83       └─────────────────────────────┴─────────────────────────────┘
84