Changes.old: Add missing entry in 5.13 changelog
[man-pages.git] / man3 / mbrlen.3
blob6a83be70087ec999d82a083feddc0f3eba49fa77
1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
8 .\" %%%LICENSE_END
9 .\"
10 .\" References consulted:
11 .\"   GNU glibc-2 source code and manual
12 .\"   Dinkumware C library reference http://www.dinkumware.com/
13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
14 .\"   ISO/IEC 9899:1999
15 .\"
16 .TH MBRLEN 3  2021-03-22 "GNU" "Linux Programmer's Manual"
17 .SH NAME
18 mbrlen \- determine number of bytes in next multibyte character
19 .SH SYNOPSIS
20 .nf
21 .B #include <wchar.h>
22 .PP
23 .BI "size_t mbrlen(const char *restrict " s ", size_t " n ,
24 .BI "              mbstate_t *restrict " ps );
25 .fi
26 .SH DESCRIPTION
27 The
28 .BR mbrlen ()
29 function inspects at most
30 .I n
31 bytes of the multibyte
32 string starting at
33 .I s
34 and extracts the next complete multibyte character.
35 It updates the shift state
36 .IR *ps .
37 If the multibyte character is not the
38 null wide character, it returns the number of bytes that were consumed from
39 .IR s .
40 If the multibyte character is the null wide character, it resets the
41 shift state
42 .I *ps
43 to the initial state and returns 0.
44 .PP
45 If the
46 .IR n
47 bytes starting at
48 .I s
49 do not contain a complete multibyte
50 character,
51 .BR mbrlen ()
52 returns
53 .IR "(size_t)\ \-2" .
54 This can happen even if
55 .I n
57 .IR MB_CUR_MAX ,
58 if the multibyte string contains redundant shift
59 sequences.
60 .PP
61 If the multibyte string starting at
62 .I s
63 contains an invalid multibyte
64 sequence before the next complete character,
65 .BR mbrlen ()
66 returns
67 .IR "(size_t)\ \-1"
68 and sets
69 .I errno
71 .BR EILSEQ .
72 In this case,
73 the effects on
74 .I *ps
75 are undefined.
76 .PP
78 .I ps
79 is NULL, a static anonymous state known only to the
80 .BR mbrlen ()
81 function is used instead.
82 .SH RETURN VALUE
83 The
84 .BR mbrlen ()
85 function returns the number of bytes
86 parsed from the multibyte
87 sequence starting at
88 .IR s ,
89 if a non-null wide character was recognized.
90 It returns 0, if a null wide character was recognized.
91 It returns
92 .I "(size_t)\ \-1"
93 and sets
94 .I errno
96 .BR EILSEQ ,
97 if an invalid multibyte sequence was
98 encountered.
99 It returns
100 .IR "(size_t)\ \-2"
101 if it couldn't parse a complete multibyte
102 character, meaning that
103 .I n
104 should be increased.
105 .SH ATTRIBUTES
106 For an explanation of the terms used in this section, see
107 .BR attributes (7).
108 .ad l
111 allbox;
112 lbx lb lb
113 l l l.
114 Interface       Attribute       Value
116 .BR mbrlen ()
117 T}      Thread safety   MT-Unsafe race:mbrlen/!ps
121 .sp 1
122 .SH CONFORMING TO
123 POSIX.1-2001, POSIX.1-2008, C99.
124 .SH NOTES
125 The behavior of
126 .BR mbrlen ()
127 depends on the
128 .B LC_CTYPE
129 category of the
130 current locale.
131 .SH SEE ALSO
132 .BR mbrtowc (3)