1MBSTOWCS(P)                POSIX Programmer's Manual               MBSTOWCS(P)
2
3
4

NAME

6       mbstowcs - convert a character string to a wide-character string
7

SYNOPSIS

9       #include <stdlib.h>
10
11       size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s,
12              size_t n);
13
14

DESCRIPTION

16       The  mbstowcs()  function  shall  convert a sequence of characters that
17       begins in the initial shift state from the array pointed to by s into a
18       sequence of corresponding wide-character codes and shall store not more
19       than n wide-character codes into the array pointed to by pwcs. No char‐
20       acters  that follow a null byte (which is converted into a wide-charac‐
21       ter code with value 0) shall be examined or converted.  Each  character
22       shall  be  converted as if by a call to mbtowc(), except that the shift
23       state of mbtowc() is not affected.
24
25       No more than n elements shall be modified in the array  pointed  to  by
26       pwcs. If copying takes place between objects that overlap, the behavior
27       is undefined.
28
29       The behavior of this function shall be affected by the  LC_CTYPE  cate‐
30       gory  of  the  current locale.    If pwcs is a null pointer, mbstowcs()
31       shall return the length required to convert the entire array regardless
32       of the value of n, but no values are stored.
33

RETURN VALUE

35       If  an  invalid  character  is  encountered,  mbstowcs()  shall  return
36       (size_t)-1    and may set errno to indicate the error.
37
38       Otherwise, mbstowcs() shall return the number  of  the  array  elements
39       modified    (or required if pwcs is null),  not including a terminating
40       0 code, if any. The array shall not be  zero-terminated  if  the  value
41       returned is n.
42

ERRORS

44       The mbstowcs() function may fail if:
45
46       EILSEQ Invalid byte sequence is detected.
47
48
49       The following sections are informative.
50

EXAMPLES

52       None.
53

APPLICATION USAGE

55       None.
56

RATIONALE

58       None.
59

FUTURE DIRECTIONS

61       None.
62

SEE ALSO

64       mblen()  , mbtowc() , wctomb() , wcstombs() , the Base Definitions vol‐
65       ume of IEEE Std 1003.1-2001, <stdlib.h>
66

68       Portions of this text are reprinted and reproduced in  electronic  form
69       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
70       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
71       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
72       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
73       event of any discrepancy between this version and the original IEEE and
74       The Open Group Standard, the original IEEE and The Open Group  Standard
75       is  the  referee document. The original Standard can be obtained online
76       at http://www.opengroup.org/unix/online.html .
77
78
79
80IEEE/The Open Group                  2003                          MBSTOWCS(P)
Impressum