Debian Codegraph @

upstream/debian-trixie/man3/mblen.3

raw
1 '\" t
2 .\" Copyright (c) Bruno Haible <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .\" References consulted:
7 .\" GNU glibc-2 source code and manual
8 .\" Dinkumware C library reference http://www.dinkumware.com/
9 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
10 .\" ISO/IEC 9899:1999
11 .\"
12 .TH mblen 3 2024-05-02 "Linux man-pages 6.9.1"
13 .SH NAME
14 mblen \- determine number of bytes in next multibyte character
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <stdlib.h>
21 .P
22 .BI "int mblen(const char " s [. n "], size_t " n );
23 .fi
24 .SH DESCRIPTION
25 If
26 .I s
27 is not NULL, the
28 .BR mblen ()
29 function inspects at most
30 .I n
31 bytes of the multibyte string starting at
32 .I s
33 and extracts the
34 next complete multibyte character.
35 It uses a static anonymous shift state known only to the
36 .BR mblen ()
37 function.
38 If the multibyte character is not the null wide
39 character, it returns the number of bytes that were consumed from
40 .IR s .
41 If the multibyte character is the null wide character, it returns 0.
42 .P
43 If the
44 .I n
45 bytes starting at
46 .I s
47 do not contain a complete multibyte
48 character,
49 .BR mblen ()
50 returns \-1.
51 This can happen even if
52 .I n
53 is greater than or equal to
54 .IR MB_CUR_MAX ,
55 if the multibyte string contains redundant shift sequences.
56 .P
57 If the multibyte string starting at
58 .I s
59 contains an invalid multibyte
60 sequence before the next complete character,
61 .BR mblen ()
62 also returns \-1.
63 .P
64 If
65 .I s
66 is NULL, the
67 .BR mblen ()
68 function
69 .\" The Dinkumware doc and the Single UNIX specification say this, but
70 .\" glibc doesn't implement this.
71 resets the shift state, known to only this function, to the initial state, and
72 returns nonzero if the encoding has nontrivial shift state, or zero if the
73 encoding is stateless.
74 .SH RETURN VALUE
75 The
76 .BR mblen ()
77 function returns the number of
78 bytes parsed from the multibyte
79 sequence starting at
80 .IR s ,
81 if a non-null wide character was recognized.
82 It returns 0, if a null wide character was recognized.
83 It returns \-1, if an
84 invalid multibyte sequence was encountered or if it couldn't parse a complete
85 multibyte character.
86 .SH ATTRIBUTES
87 For an explanation of the terms used in this section, see
88 .BR attributes (7).
89 .TS
90 allbox;
91 lbx lb lb
92 l l l.
93 Interface Attribute Value
94 T{
95 .na
96 .nh
97 .BR mblen ()
98 T} Thread safety MT-Unsafe race
99 .TE
100 .SH VERSIONS
101 The function
102 .BR mbrlen (3)
103 provides a better interface to the same
104 functionality.
105 .SH STANDARDS
106 C11, POSIX.1-2008.
107 .SH HISTORY
108 POSIX.1-2001, C99.
109 .SH NOTES
110 The behavior of
111 .BR mblen ()
112 depends on the
113 .B LC_CTYPE
114 category of the
115 current locale.
116 .SH SEE ALSO
117 .BR mbrlen (3)