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

NAME

6       mbtowc - convert a character to a wide-character code
7

SYNOPSIS

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

DESCRIPTION

15       If  s  is  not  a  null pointer, mbtowc() shall determine the number of
16       bytes that constitute the character pointed to  by  s.  It  shall  then
17       determine  the  wide-character  code for the value of type wchar_t that
18       corresponds to that character. (The value of  the  wide-character  code
19       corresponding to the null byte is 0.) If the character is valid and pwc
20       is not a null pointer, mbtowc() shall store the wide-character code  in
21       the object pointed to by pwc.
22
23       The  behavior  of this function is affected by the LC_CTYPE category of
24       the current locale. For a state-dependent encoding,  this  function  is
25       placed into its initial state by a call for which its character pointer
26       argument, s, is a null pointer.  Subsequent calls with s as other  than
27       a  null  pointer  shall  cause the internal state of the function to be
28       altered as necessary. A call with s as a null pointer shall cause  this
29       function to return a non-zero value if encodings have state dependency,
30       and 0 otherwise. If the implementation employs special bytes to  change
31       the  shift state, these bytes shall not produce separate wide-character
32       codes, but shall be grouped with an adjacent  character.  Changing  the
33       LC_CTYPE category causes the shift state of this function to be unspec‐
34       ified. At most n bytes of the array pointed to by s shall be examined.
35
36       The implementation shall behave as if no function defined in this  vol‐
37       ume of IEEE Std 1003.1-2001 calls mbtowc().
38

RETURN VALUE

40       If s is a null pointer, mbtowc() shall return a non-zero or 0 value, if
41       character encodings, respectively, do or do  not  have  state-dependent
42       encodings.  If  s is not a null pointer, mbtowc() shall either return 0
43       (if s points to the null byte), or return the number of bytes that con‐
44       stitute  the  converted  character (if the next n or fewer bytes form a
45       valid character), or return -1    and may set  errno  to  indicate  the
46       error  (if they do not form a valid character).
47
48       In  no  case shall the value returned be greater than n or the value of
49       the {MB_CUR_MAX} macro.
50

ERRORS

52       The mbtowc() function may fail if:
53
54       EILSEQ Invalid character sequence is detected.
55
56
57       The following sections are informative.
58

EXAMPLES

60       None.
61

APPLICATION USAGE

63       None.
64

RATIONALE

66       None.
67

FUTURE DIRECTIONS

69       None.
70

SEE ALSO

72       mblen() , mbstowcs() , wctomb() , wcstombs()  ,  the  Base  Definitions
73       volume of IEEE Std 1003.1-2001, <stdlib.h>
74

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