Debian Codegraph @

upstream/debian-unstable/man3/mblen.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 mblen 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mblen \- 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 <stdlib.h>
16 .P
17 .BR "int mblen(" "size_t n;"
18 .BI " const char " s [ n "], size_t " n );
19 .fi
20 .SH DESCRIPTION
21 If
22 .I s
23 is not NULL, the
24 .BR mblen ()
25 function inspects at most
26 .I n
27 bytes of the multibyte string starting at
28 .I s
29 and extracts the
30 next complete multibyte character.
31 It uses a static anonymous shift state known only to the
32 .BR mblen ()
33 function.
34 If the multibyte character is not the null wide
35 character, it returns the number of bytes that were consumed from
36 .IR s .
37 If the multibyte character is the null wide character, it returns 0.
38 .P
39 If the
40 .I n
41 bytes starting at
42 .I s
43 do not contain a complete multibyte
44 character,
45 .BR mblen ()
46 returns \-1.
47 This can happen even if
48 .I n
49 is greater than or equal to
50 .IR MB_CUR_MAX ,
51 if the multibyte string contains redundant shift sequences.
52 .P
53 If the multibyte string starting at
54 .I s
55 contains an invalid multibyte
56 sequence before the next complete character,
57 .BR mblen ()
58 also returns \-1.
59 .P
60 If
61 .I s
62 is NULL, the
63 .BR mblen ()
64 function
65 .\" The Dinkumware doc and the Single UNIX specification say this, but
66 .\" glibc doesn't implement this.
67 resets the shift state, known to only this function, to the initial state, and
68 returns nonzero if the encoding has nontrivial shift state, or zero if the
69 encoding is stateless.
70 .SH RETURN VALUE
71 The
72 .BR mblen ()
73 function returns the number of
74 bytes parsed from the multibyte
75 sequence starting at
76 .IR s ,
77 if a non-null wide character was recognized.
78 It returns 0, if a null wide character was recognized.
79 It returns \-1, if an
80 invalid multibyte sequence was encountered or if it couldn't parse a complete
81 multibyte character.
82 .SH ATTRIBUTES
83 For an explanation of the terms used in this section, see
84 .BR attributes (7).
85 .TS
86 allbox;
87 lbx lb lb
88 l l l.
89 Interface Attribute Value
90 T{
91 .na
92 .nh
93 .BR mblen ()
94 T} Thread safety MT-Unsafe race
95 .TE
96 .SH VERSIONS
97 The function
98 .BR mbrlen (3)
99 provides a better interface to the same
100 functionality.
101 .SH STANDARDS
102 C11, POSIX.1-2008.
103 .SH HISTORY
104 POSIX.1-2001, C99.
105 .SH NOTES
106 The behavior of
107 .BR mblen ()
108 depends on the
109 .B LC_CTYPE
110 category of the
111 current locale.
112 .SH SEE ALSO
113 .BR mbrlen (3)