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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
.TH MPU_STR8ING 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_str8cat, mpu_str8chr, mpu_str8chrnul, mpu_str8cmp, mpu_str8cpy,
mpu_str8cspn, mpu_str8dup, mpu_str8ndup, mpu_str8len, mpu_str8ncat, mpu_str8ncmp,
mpu_str8ncpy, mpu_str8nlen, mpu_str8pbrk, mpu_str8rchr, mpu_str8spn,
mpu_str8pcpy, mpu_str8pncpy, mpu_str8str, mpu_str8rstr, mpu_str8tok, mpu_str8tok_r
\- ordinary 8-bit C string operations
.SH SYNOPSIS
.nf
#include <libmpuio.h>
__mpu_char8_t *mpu_str8cat( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t *mpu_str8chr( const __mpu_char8_t *s, int c );
__mpu_char8_t *mpu_str8chrnul( const __mpu_char8_t *s, int c );
int mpu_str8cmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2 );
__mpu_char8_t *mpu_str8cpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_size_t mpu_str8cspn( const __mpu_char8_t *s, const __mpu_char8_t *reject );
__mpu_char8_t *mpu_str8dup( const __mpu_char8_t *s );
__mpu_char8_t *mpu_str8ndup( const __mpu_char8_t *s, __mpu_size_t n );
__mpu_size_t mpu_str8len( const __mpu_char8_t *s );
__mpu_char8_t *mpu_str8ncat( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
int mpu_str8ncmp( const __mpu_char8_t *s1, const __mpu_char8_t *s2, __mpu_size_t n );
__mpu_char8_t *mpu_str8ncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_size_t mpu_str8nlen( const __mpu_char8_t *s, __mpu_size_t maxlen );
__mpu_char8_t *mpu_str8pbrk( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_char8_t *mpu_str8rchr( const __mpu_char8_t *s, int c );
__mpu_size_t mpu_str8spn( const __mpu_char8_t *s, const __mpu_char8_t *accept );
__mpu_char8_t *mpu_str8pcpy( __mpu_char8_t *dest, const __mpu_char8_t *src );
__mpu_char8_t *mpu_str8pncpy( __mpu_char8_t *dest, const __mpu_char8_t *src, __mpu_size_t n );
__mpu_char8_t *mpu_str8str( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t *mpu_str8rstr( const __mpu_char8_t *haystack, const __mpu_char8_t *needle );
__mpu_char8_t *mpu_str8tok( __mpu_char8_t *s, const __mpu_char8_t *delim );
__mpu_char8_t *mpu_str8tok_r( __mpu_char8_t *s, const __mpu_char8_t *delim, __mpu_char8_t **saveptr );
.fi
.SH DESCRIPTION
These functions operate on ordinary NUL-terminated 8-bit C strings.
Their basic contracts follow the corresponding libc string functions.
They do not interpret the byte sequence as UTF-8; character-oriented UTF-8
operations are provided by the
.B mpu_utf8*
family.
.PP
.BR mpu_str8cat (),
.BR mpu_str8cpy (),
.BR mpu_str8ncat (),
.BR mpu_str8ncpy (),
.BR mpu_str8cmp (),
.BR mpu_str8ncmp (),
.BR mpu_str8chr (),
.BR mpu_str8rchr (),
.BR mpu_str8str (),
.BR mpu_str8pbrk (),
.BR mpu_str8spn (),
.BR mpu_str8cspn (),
.BR mpu_str8len ()
and
.BR mpu_str8nlen ()
follow the usual libc semantics.
.PP
.B mpu_str8chrnul()
returns the matching byte or, if no match exists, a pointer to the terminating
NUL byte.
.PP
.B mpu_str8pcpy()
copies the complete string and returns a pointer to the terminating NUL in
.IR dest .
.PP
.B mpu_str8pncpy()
is the pointer-returning bounded-copy variant used by LIBMPUIO. It copies and
pads exactly as
.BR strncpy (3).
If the source string terminates before
.I n
bytes, the return value points to the first NUL written to
.IR dest .
If no NUL is encountered in the first
.I n
source bytes, the return value is
.IR dest+n .
.PP
.B mpu_str8rstr()
returns the last occurrence of
.I needle
in
.IR haystack .
For an empty
.I needle
it returns a pointer to the terminating NUL of
.IR haystack .
.PP
.B mpu_str8tok()
is the stateful tokenizer analogous to
.BR strtok (3).
The continuation pointer is stored in thread-local storage, so independent
threads do not share tokenizer state. Calls within one thread still share one
continuation state and therefore are not reentrant.
.PP
.B mpu_str8tok_r()
is a reentrant tokenizer analogous to
.BR strtok_r (3).
The caller supplies storage for the continuation pointer through
.IR saveptr .
.PP
.BR mpu_str8dup ()
and
.B mpu_str8ndup()
allocate duplicates with
.BR malloc (3).
.B mpu_str8ndup()
copies at most
.I n
bytes and always appends a terminating NUL. The caller releases either result with
.BR free (3).
Passing NULL sets
.B errno
to
.B EINVAL
and returns NULL.
.SH RETURN VALUE
The pointer-returning and comparison functions follow the corresponding libc
conventions described above. Length and span functions return byte counts.
.BR mpu_str8dup ()
and
.B mpu_str8ndup()
return NULL on failure.
.SH NOTES
The destination object must be large enough for every copying or concatenation
operation, exactly as for the corresponding libc routine.
.PP
Use
.BR mpu_utf8ing (3)
when
.I n
must denote UTF-8 characters instead of bytes.
.SH SEE ALSO
.BR string (3),
.BR mpu_str16ing (3),
.BR mpu_utf8ing (3),
.BR mpu_string_conversion (3)
|
