1WCSRTOMBS(3P)              POSIX Programmer's Manual             WCSRTOMBS(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       wcsrtombs - convert a  wide-character  string  to  a  character  string
13       (restartable)
14

SYNOPSIS

16       #include <wchar.h>
17
18       size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
19              size_t len, mbstate_t *restrict ps);
20
21

DESCRIPTION

23       The  wcsrtombs()  function  shall convert a sequence of wide characters
24       from the array indirectly pointed to by src into a sequence  of  corre‐
25       sponding characters, beginning in the conversion state described by the
26       object pointed to by ps. If dst is not a null  pointer,  the  converted
27       characters  shall then be stored into the array pointed to by dst. Con‐
28       version continues up to and including a terminating null  wide  charac‐
29       ter,  which  shall also be stored. Conversion shall stop earlier in the
30       following cases:
31
32        * When a code is reached that does not correspond to a valid character
33
34        * When the next character would exceed the limit of len total bytes to
35          be  stored  in  the  array  pointed to by dst (and dst is not a null
36          pointer)
37
38       Each conversion shall take place as if by a call to the wcrtomb() func‐
39       tion.
40
41       If  dst  is  not  a  null pointer, the pointer object pointed to by src
42       shall be assigned either a null pointer (if conversion stopped  due  to
43       reaching  a  terminating  null wide character) or the address just past
44       the last wide character converted (if any). If conversion  stopped  due
45       to  reaching  a  terminating  null  wide character, the resulting state
46       described shall be the initial conversion state.
47
48       If ps is a null pointer, the wcsrtombs() function  shall  use  its  own
49       internal  mbstate_t object, which is initialized at program start-up to
50       the initial conversion state. Otherwise, the mbstate_t  object  pointed
51       to  by  ps  shall be used to completely describe the current conversion
52       state of the associated character sequence.  The  implementation  shall
53       behave as if no function defined in this volume of IEEE Std 1003.1-2001
54       calls wcsrtombs().
55
56       If the application uses  any  of  the  _POSIX_THREAD_SAFE_FUNCTIONS  or
57       _POSIX_THREADS  functions,  the application shall ensure that the wcsr‐
58       tombs() function is called with a non-NULL ps argument.
59
60       The behavior of this function shall be affected by the  LC_CTYPE  cate‐
61       gory of the current locale.
62

RETURN VALUE

64       If  conversion stops because a code is reached that does not correspond
65       to a valid character, an encoding error occurs. In this case, the wcsr‐
66       tombs()  function  shall store the value of the macro [EILSEQ] in errno
67       and return (size_t)-1; the conversion state is undefined. Otherwise, it
68       shall  return  the number of bytes in the resulting character sequence,
69       not including the terminating null (if any).
70

ERRORS

72       The wcsrtombs() function may fail if:
73
74       EINVAL ps points to an  object  that  contains  an  invalid  conversion
75              state.
76
77       EILSEQ A wide-character code does not correspond to a valid character.
78
79
80       The following sections are informative.
81

EXAMPLES

83       None.
84

APPLICATION USAGE

86       None.
87

RATIONALE

89       None.
90

FUTURE DIRECTIONS

92       None.
93

SEE ALSO

95       mbsinit(),     wcrtomb(),    the    Base    Definitions    volume    of
96       IEEE Std 1003.1-2001, <wchar.h>
97
99       Portions of this text are reprinted and reproduced in  electronic  form
100       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
101       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
102       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
103       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
104       event of any discrepancy between this version and the original IEEE and
105       The Open Group Standard, the original IEEE and The Open Group  Standard
106       is  the  referee document. The original Standard can be obtained online
107       at http://www.opengroup.org/unix/online.html .
108
109
110
111IEEE/The Open Group                  2003                        WCSRTOMBS(3P)
Impressum