Debian Codegraph @

upstream/debian-unstable/man3/mbrlen.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH mbrlen 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mbrlen \- determine number of bytes in next multibyte character
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BR "size_t mbrlen(" "size_t n;"
18 .BI " const char " s "[restrict " n "], size_t " n ,
19 .BI " mbstate_t *restrict " ps );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR mbrlen ()
24 function inspects at most
25 .I n
26 bytes of the multibyte
27 string starting at
28 .I s
29 and extracts the next complete multibyte character.
30 It updates the shift state
31 .IR *ps .
32 If the multibyte character is not the
33 null wide character, it returns the number of bytes that were consumed from
34 .IR s .
35 If the multibyte character is the null wide character, it resets the
36 shift state
37 .I *ps
38 to the initial state and returns 0.
39 .P
40 If the
41 .I n
42 bytes starting at
43 .I s
44 do not contain a complete multibyte
45 character,
46 .BR mbrlen ()
47 returns
48 .IR "(size_t)\ \-2" .
49 This can happen even if
50 .I n
51 >=
52 .IR MB_CUR_MAX ,
53 if the multibyte string contains redundant shift
54 sequences.
55 .P
56 If the multibyte string starting at
57 .I s
58 contains an invalid multibyte
59 sequence before the next complete character,
60 .BR mbrlen ()
61 returns
62 .I (size_t)\ \-1
63 and sets
64 .I errno
65 to
66 .BR EILSEQ .
67 In this case,
68 the effects on
69 .I *ps
70 are undefined.
71 .P
72 If
73 .I ps
74 is NULL, a static anonymous state known only to the
75 .BR mbrlen ()
76 function is used instead.
77 .SH RETURN VALUE
78 The
79 .BR mbrlen ()
80 function returns the number of bytes
81 parsed from the multibyte
82 sequence starting at
83 .IR s ,
84 if a non-null wide character was recognized.
85 It returns 0, if a null wide character was recognized.
86 It returns
87 .I "(size_t)\ \-1"
88 and sets
89 .I errno
90 to
91 .BR EILSEQ ,
92 if an invalid multibyte sequence was
93 encountered.
94 It returns
95 .I (size_t)\ \-2
96 if it couldn't parse a complete multibyte
97 character, meaning that
98 .I n
99 should be increased.
100 .SH ATTRIBUTES
101 For an explanation of the terms used in this section, see
102 .BR attributes (7).
103 .TS
104 allbox;
105 lbx lb lb
106 l l l.
107 Interface Attribute Value
108 T{
109 .na
110 .nh
111 .BR mbrlen ()
112 T} Thread safety MT-Unsafe race:mbrlen/!ps
113 .TE
114 .SH STANDARDS
115 C11, POSIX.1-2008.
116 .SH HISTORY
117 POSIX.1-2001, C99.
118 .SH NOTES
119 The behavior of
120 .BR mbrlen ()
121 depends on the
122 .B LC_CTYPE
123 category of the
124 current locale.
125 .SH SEE ALSO
126 .BR mbrtowc (3)