1wcsrtombs(3C)            Standard C Library Functions            wcsrtombs(3C)
2
3
4

NAME

6       wcsrtombs  -  convert  a  wide-character  string  to a character string
7       (restartable)
8

SYNOPSIS

10       #include <wchar.h>
11
12       size_t wcsrtombs(char *restrict dst,
13            const wchar_t **restrict src, size_t len,
14            mbstate_t *restrict ps);
15
16

DESCRIPTION

18       The wcsrtombs() function converts a sequence  of  wide-characters  from
19       the array indirectly pointed to by src into a sequence of corresponding
20       characters, beginning in the conversion state described by  the  object
21       pointed  to  by ps. If dst is not a null pointer, the converted charac‐
22       ters are then stored into the array pointed to by dst. Conversion  con‐
23       tinues up to and including a terminating null  wide-character, which is
24       also stored. Conversion stops earlier in the following cases:
25
26           o      When a code is reached that does not correspond to  a  valid
27                  character.
28
29           o      When  the next character would exceed the limit of len total
30                  bytes to be stored in the array pointed to by dst  (and  dst
31                  is not a null pointer).
32
33
34       Each conversion takes place as if by a call to the wcrtomb() function.
35
36
37       If  dst  is not a null pointer, the pointer object pointed to by src is
38       assigned either a null pointer (if conversion stopped due to reaching a
39       terminating  null  wide-character)  or  the address just  past the last
40       wide-character converted (if any). If conversion stopped due to  reach‐
41       ing a terminating null wide-character, the resulting state described is
42       the initial conversion state.
43
44
45       If ps is a null pointer, the wcsrtombs() function uses its own internal
46       mbstate_t  object,  which is initialized at program startup to the ini‐
47       tial conversion state.  Otherwise, the  mbstate_t object pointed to  by
48       ps  is  used to completely describe the current conversion state of the
49       associated character sequence. Solaris will behave as  if  no  function
50       defined in the Solaris Reference Manual calls wcsrtombs().
51
52
53       The  behavior  of this function is affected by the LC_CTYPE category of
54       the current locale.  See environ(5).
55

RETURN VALUES

57       If conversion stops because a code is reached that does not  correspond
58       to  a  valid  character,  an  encoding error occurs.  In this case, the
59       wcsrtombs() function stores the value of the macro EILSEQ in errno  and
60       returns  (size_t)−1;  the conversion state is undefined.  Otherwise, it
61       returns the number of bytes in the resulting  character  sequence,  not
62       including the terminating null (if any).
63

ERRORS

65       The wcsrtombs() function may fail if:
66
67       EINVAL    The  ps argument points to an object that contains an invalid
68                 conversion state.
69
70
71       EILSEQ    A wide-character code does not correspond to a valid  charac‐
72                 ter.
73
74

USAGE

76       If  ps  is  not  a  null pointer, wcsrtombs() uses the mbstate_t object
77       pointed to by ps and the function can be used safely  in  multithreaded
78       applications,  as  long  as setlocale(3C) is not being called to change
79       the locale. If ps is a null  pointer,  wcsrtombs()  uses  its  internal
80       mbstate_t  object  and the function is Unsafe in multithreaded applica‐
81       tions.
82

ATTRIBUTES

84       See attributes(5) for descriptions of the following attributes:
85
86
87
88
89       ┌─────────────────────────────┬─────────────────────────────┐
90       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
91       ├─────────────────────────────┼─────────────────────────────┤
92       │Interface Stability          │Standard                     │
93       ├─────────────────────────────┼─────────────────────────────┤
94       │MT-Level                     │See NOTES below              │
95       └─────────────────────────────┴─────────────────────────────┘
96

SEE ALSO

98       mbsinit(3C),  setlocale(3C),  wcrtomb(3C),  attributes(5),  environ(5),
99       standards(5)
100
101
102
103SunOS 5.11                        1 Nov 2003                     wcsrtombs(3C)
Impressum