mbrlen(3c) - osol9

1mbrlen(3C)               Standard C Library Functions               mbrlen(3C)
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, mbstate_t *restrict ps);
12
13

DESCRIPTION

15       If  s  is  not a null pointer,  mbrlen() determines the number of bytes
16       constituting the character pointed to by  s. It is equivalent to:
17
18         mbstate_t internal;
19         mbrtowc(NULL, s, n, ps != NULL ? ps : &internal);
20
21
22
23       If ps is a null pointer, the mbrlen() function uses  its  own  internal
24       mbstate_t  object,  which is initialized at program startup to the ini‐
25       tial conversion state.   Otherwise, the  mbstate_t object pointed to by
26       ps  is  used to completely describe the current conversion state of the
27       associated character sequence. Solaris will behave as  if  no  function
28       defined in the Solaris Reference Manual calls mbrlen().
29
30
31       The  behavior  of this function is affected by the LC_CTYPE category of
32       the current locale.  See environ(5).
33

RETURN VALUES

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

ERRORS

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

ATTRIBUTES

71       See attributes(5) for descriptions of the following attributes:
72
73
74
75
76       ┌─────────────────────────────┬─────────────────────────────┐
77       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
78       ├─────────────────────────────┼─────────────────────────────┤
79       │Interface Stability          │Standard                     │
80       ├─────────────────────────────┼─────────────────────────────┤
81       │MT-Level                     │See NOTES below              │
82       └─────────────────────────────┴─────────────────────────────┘
83

NOTES

89       If ps is not a null pointer, mbrlen() uses the mbstate_t object pointed
90       to by ps and the function can be used safely in multithreaded  applica‐
91       tions,  as  long  as  setlocale(3C)  is  not being called to change the
92       locale. If ps is a null pointer, mbrlen() uses its  internal  mbstate_t
93       object and the function is Unsafe in multithreaded applications.
94
95
96
97SunOS 5.11                        1 Nov 2003                        mbrlen(3C)