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

NAME

6       mbrtowc - convert a character to a wide-character code (restartable)
7

SYNOPSIS

9       #include <wchar.h>
10
11       size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,
12              size_t n, mbstate_t *restrict ps);
13
14

DESCRIPTION

16       If  s  is a null pointer, the mbrtowc() function shall be equivalent to
17       the call:
18
19
20              mbrtowc(NULL, "", 1, ps)
21
22       In this case, the values of the arguments pwc and n are ignored.
23
24       If s is not a null pointer, the mbrtowc()  function  shall  inspect  at
25       most  n  bytes  beginning  at the byte pointed to by s to determine the
26       number of bytes needed to complete the next  character  (including  any
27       shift sequences). If the function determines that the next character is
28       completed, it shall determine the value of the corresponding wide char‐
29       acter and then, if pwc is not a null pointer, shall store that value in
30       the object pointed to by pwc. If the corresponding  wide  character  is
31       the  null  wide  character,  the resulting state described shall be the
32       initial conversion state.
33
34       If ps is a null pointer, the  mbrtowc()  function  shall  use  its  own
35       internal mbstate_t object, which shall be initialized at program start-
36       up to the initial conversion state.  Otherwise,  the  mbstate_t  object
37       pointed  to by ps shall be used to completely describe the current con‐
38       version state of the associated character sequence. The  implementation
39       shall   behave   as   if   no   function  defined  in  this  volume  of
40       IEEE Std 1003.1-2001 calls mbrtowc().
41
42       The behavior of this function is affected by the LC_CTYPE  category  of
43       the current locale.
44

RETURN VALUE

46       The  mbrtowc()  function  shall  return the first of the following that
47       applies:
48
49       0      If the next n or fewer bytes complete the character that  corre‐
50              sponds to the null wide character (which is the value stored).
51
52       between 1 and n inclusive
53
54              If  the  next n or fewer bytes complete a valid character (which
55              is the value stored); the value returned shall be the number  of
56              bytes that complete the character.
57
58       (size_t)-2
59              If  the next n bytes contribute to an incomplete but potentially
60              valid character, and all n bytes have been processed  (no  value
61              is  stored).  When  n has at least the value of the {MB_CUR_MAX}
62              macro, this case can only occur if s points  at  a  sequence  of
63              redundant shift sequences (for implementations with state-depen‐
64              dent encodings).
65
66       (size_t)-1
67              If an encoding error occurs, in which case the next n  or  fewer
68              bytes  do  not  contribute to a complete and valid character (no
69              value is stored). In this case,  [EILSEQ]  shall  be  stored  in
70              errno and the conversion state is undefined.
71
72

ERRORS

74       The mbrtowc() function may fail if:
75
76       EINVAL ps  points  to  an  object  that  contains an invalid conversion
77              state.
78
79       EILSEQ Invalid character sequence is detected.
80
81
82       The following sections are informative.
83

EXAMPLES

85       None.
86

APPLICATION USAGE

88       None.
89

RATIONALE

91       None.
92

FUTURE DIRECTIONS

94       None.
95

SEE ALSO

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