1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
.TH LIBUTF8_DECODE 3 LIBUTF8
.SH NAME
libutf8_decode - Decode one UTF-8 sequence from a string
.SH SYNOPSIS
.nf
#include <libutf8.h>
size_t \fBlibutf8_decode\fP(const char *\fItext\fP, uint_least32_t *\fIcodepoint_out\fP, unsigned \fIflags\fP);
.fi
.PP
Link with
.IR -lutf8 .
.SH DESCRIPTION
The
.BR libutf8_decode ()
function decodes the first UTF-8 sequence in
.IR text .
Unless the
.BR libutf8_decode ()
function returns 0, and unless
.I codepoint_out
is
.IR NULL ,
the decoded codepoint is stored in
.IR *codepoint_out .
.PP
.I flags
is a bitwise OR of zero or more of the following values:
.TP
.B LIBUTF8_REPLACE_INVALID
Replace decoded invalid codepoints up to
.B LIBUTF8_ULTIMATE_CODEPOINT
with the Unicode REPLACEMENT CHARACTER (U+FFFD).
This does not affect illegal byte sequences.
.TP
.B LIBUTF8_RETURN_INVALID
Return decoded invalid codepoints up to
.B LIBUTF8_ULTIMATE_CODEPOINT
unchanged.
.TP
.B LIBUTF8_ALLOW_31_BITS
Accept codepoints greater than
.BR LIBUTF8_ULTIMATE_CODEPOINT ,
up to representable with 31 bits, unsigned.
.TP
.B LIBUTF8_ALLOW_2BYTE_NULL
Accept the two-byte overlong encoding of U+0000.
.TP
.B LIBUTF8_ALLOW_LONG_ENCODING
Accept overlong encodings up to six bytes.
This includes the encoding accepted by
.BR LIBUTF8_ALLOW_2BYTE_NULL .
.PP
It is unspecified which flag dominates if both
.B LIBUTF8_REPLACE_INVALID
and
.B LIBUTF8_RETURN_INVALID
are set.
.SH RETURN VALUE
The
.BR libutf8_decode ()
function returns the number of decoded bytes,
or zero if the input is invalid.
.SH ERRORS
The function cannot fail per se, and never sets
.IR errno .
.B EILSEQ
is an appropriate value when it returns zero.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.PP
.TS
allbox;
lb lb lb lb
l l l l.
Interface Thread safety Async-signal safety Async-cancel safety
T{
.BR libutf8_decode ()
T} MT-Safe AS-Safe AC-Safe
.TE
.sp
.SH APPLICATION USAGE
Application that use
.BR LIBUTF8_REPLACE_INVALID (3)
will probably also want to skip the first
undecoded by when 0 is returned and insert
.BR LIBUTF8_REPLACEMENT_CHARACTER_CODEPOINT (3)
in its place, and optionally skip the following
bytes until there is one for which
.BR libutf8_is_continuation (3)
returns zero.
.SH NOTES
The
.BR libutf8_decode ()
function can read up
to six bytes while examining a malformed sequence; use
.BR libutf8_decode_mem (3)
for a length-bounded buffer.
.SH SEE ALSO
.BR libutf8 (7),
.BR libutf8_decode_mem (3),
.BR libutf8_is_continuation (3),
.BR libutf8_is_surrogate (3),
.BR LIBUTF8_REPLACEMENT_CHARACTER_CODEPOINT (3)
|
