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

NAME

6       mbrlen - get number of bytes in a character (restartable)
7

SYNOPSIS

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

DESCRIPTION

16       If  s  is  not  a  null pointer, mbrlen() shall determine the number of
17       bytes constituting the character pointed to by s. It shall  be  equiva‐
18       lent to:
19
20
21              mbstate_t internal;
22              mbrtowc(NULL, s, n, ps != NULL ? ps : &internal);
23
24       If ps is a null pointer, the mbrlen() function shall use its own inter‐
25       nal mbstate_t object, which is initialized at program start-up  to  the
26       initial conversion state. Otherwise, the mbstate_t object pointed to by
27       ps shall be used to completely describe the current conversion state of
28       the  associated  character sequence. The implementation shall behave as
29       if no function defined in this  volume  of  IEEE Std 1003.1-2001  calls
30       mbrlen().
31
32       The  behavior  of this function is affected by the LC_CTYPE category of
33       the current locale.
34

RETURN VALUE

36       The mbrlen() function shall return the  first  of  the  following  that
37       applies:
38
39       0      If  the next n or fewer bytes complete the character that corre‐
40              sponds to the null wide character.
41
42       positive
43              If the next n or fewer bytes complete  a  valid  character;  the
44              value  returned  shall  be the number of bytes that complete the
45              character.
46
47       (size_t)-2
48              If the next n bytes contribute to an incomplete but  potentially
49              valid character, and all n bytes have been processed. When n has
50              at least the value of the {MB_CUR_MAX} macro, this case can only
51              occur  if  s  points  at a sequence of redundant shift sequences
52              (for implementations with state-dependent encodings).
53
54       (size_t)-1
55              If an encoding error occurs, in which case the next n  or  fewer
56              bytes  do  not  contribute to a complete and valid character. In
57              this case, [EILSEQ] shall be stored in errno and the  conversion
58              state is undefined.
59
60

ERRORS

62       The mbrlen() function may fail if:
63
64       EINVAL ps  points  to  an  object  that  contains an invalid conversion
65              state.
66
67       EILSEQ Invalid character sequence is detected.
68
69
70       The following sections are informative.
71

EXAMPLES

73       None.
74

APPLICATION USAGE

76       None.
77

RATIONALE

79       None.
80

FUTURE DIRECTIONS

82       None.
83

SEE ALSO

85       mbsinit()   ,   mbrtowc()   ,   the   Base   Definitions   volume    of
86       IEEE Std 1003.1-2001, <wchar.h>
87

89       Portions  of  this text are reprinted and reproduced in electronic form
90       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
91       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
92       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
93       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
94       event of any discrepancy between this version and the original IEEE and
95       The  Open Group Standard, the original IEEE and The Open Group Standard
96       is the referee document. The original Standard can be  obtained  online
97       at http://www.opengroup.org/unix/online.html .
98
99
100
101IEEE/The Open Group                  2003                            MBRLEN(P)
Impressum