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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
//! What a path is made of, and which of its components a directory can hold.
//!
//! Two questions are asked of a path everywhere in this crate, by every family and on both
//! sides of it. **Which components does it have** — a source keying entries by path, a model
//! placing them, a reader resolving one, a walk building one. And **may this component be a
//! name** — a directory entry read out of an image, a component of a host path about to be
//! created.
//!
//! Both are answered here rather than by each layer, and for the same reason: a second answer
//! that drifted would not fail. A splitter that disagreed about an empty component would key
//! two entries apart that the model considers one path, and leave both in the image. A name
//! rule that gained a clause in one place and not another would refuse a name where it is
//! read and accept it where it is written.
//!
//! This module is pure: it inspects byte strings and answers questions about them. It does
//! no I/O and rejects nothing on its own — each caller applies the answer as its own error.
//!
//! # The two name rules, and why there are two
//!
//! `is_hostile_entry` is what no directory entry may carry at all. `is_hostile_component` is
//! that rule and two clauses more, for the case where the name is about to become a component
//! of a path. (Named without links: each is compiled only where something asks it, and this
//! module is compiled always.)
//!
//! The difference is `.` and `..`, and it is a real one rather than a strictness dial. An ext
//! directory genuinely holds both as entries — a resolution walks `..` through the one the
//! directory carries, and a listing that omitted them would not be the directory — so ext
//! reads them with the entry rule and filters them by name where a path is built. A FAT
//! directory's dot entries are identified by their short-name field before a name is
//! resolved at all, so by the time a resolved name exists there is no legitimate `.` left,
//! and the volume's own reader asks the stricter question. A host sink asks it too, of every
//! component it is about to create.
//!
//! Stating them as one rule and one rule-plus-two-clauses is what keeps the shared part
//! shared: a clause added to what no name may carry reaches all three callers, and the
//! asymmetry stays visible as the two functions rather than as a flag.
/// The meaningful components of `path`, in order: what [`canonical_key`] joins, and what a
/// model validates.
///
/// Separators and `.` elements carry no meaning, so they are what this drops. It is the
/// normalization half alone — a caller that must also *reject* a component runs its own rules
/// over what comes back, so there is one answer to "which components are these" and one place
/// each layer states what it will not accept.
///
/// `..` is left in. It resolves through the directory's own entry for it, which is the only
/// thing that knows where the parent is, and a model that cannot represent one refuses it by
/// name rather than by having never seen it.
pub
/// The canonical key for `path`: its meaningful components joined by single separators, with
/// no leading or trailing one.
///
/// `/etc/hostname`, `//etc//hostname`, and `etc/./hostname` are one path and key alike, and
/// the root keys as the empty slice.
///
/// This is the rule a family's own path handling is built on, so that a caller keying entries
/// by path outside a model — composing two sources into one, where a later entry replaces an
/// earlier one at the same path — decides which paths *are* the same the way the model that
/// consumes them will. Two normalizations that disagreed would not fail; they would quietly
/// leave both entries in the list, and the model would reject the duplicate or, worse, accept
/// two names it thought were different. So there is one: a model splits a path through
/// [`canonical_parts`] and validates what comes back.
///
/// It rejects nothing. A `..` element, an over-long component, or one carrying a NUL keys
/// as itself and is refused when a model reads the entry, so there is one rejection site
/// and its error names the path the caller wrote.
pub
/// Whether `name` is one no directory entry could carry: it is empty, or holds a path
/// separator or a NUL.
///
/// A filename holds neither of the last two (POSIX.1-2017, XBD 3.170 "Filename"), and the
/// pinned `e2fsck` faults an ext directory entry holding either (observed), so either marks a
/// crafted or corrupt image; no FAT driver writes them either. A name carrying `/` traverses out of
/// its directory (`../../etc/...`); one carrying a NUL ends early at the C-string boundary a
/// consumer would build a host path against.
///
/// An empty name is not a name, and every family reaches one. An ext directory entry may
/// record a zero-length name beside a non-zero inode; a FAT eleven-byte field of spaces
/// renders to nothing, and a long-name run beginning with a zero code unit decodes to
/// nothing. The path built from any of them is the *directory's own path* with a trailing
/// separator, so two such siblings produce two entries at identical paths — which contradicts
/// what a walk promises — and an archive writer renders one as a member ending in `/`, which
/// every tar reader takes for a directory, so it collides with the real entry of that name
/// and changes its type.
///
/// Compiled wherever a family is, and wherever `is_hostile_component` is: the stricter rule
/// is this one and two clauses, so a build carrying a host sink and no family asks the
/// stricter question and reaches here through it.
pub
/// Whether `name` is one that could not be a component of a path: everything
/// [`is_hostile_entry`] refuses, and `.` or `..` besides.
///
/// Those two name a directory rather than something inside it — `..` would ascend out of the
/// tree a path is being built in, and `.` would name the directory itself — so a component
/// that is either is not a name the path can gain. The test is on the name as a caller
/// receives it, after a FAT long name is decoded and a short one is read under the volume's
/// code page, because that is the byte string a path is built from.
pub
/// Whether `name` is one of the two entries a directory holds for itself and its parent.
///
/// Not hostile on its own — the formats that store the pair store it legitimately — but
/// never a name below the directory either, so every walk that builds paths and every
/// listing that yields names skips both. One home for the pair, because the test is the
/// same wherever a family stores them — and it is a clause of `is_hostile_component`
/// besides, so it is compiled wherever either caller is.
pub
/// Characters reserved in a name on the formats that inherited the DOS filename rules. Each
/// is a path separator, a wildcard, or a redirection a shell or a driver interprets rather
/// than stores.
const RESERVED_NAME_CHARS: & = b"\"*/:<>?\\|";
/// Whether `ch` is one no name a FAT or exFAT volume carries may contain.
///
/// One rule, because it is one rule: FAT's long names and exFAT's names reserve the same nine
/// characters and the same control codes, both formats having taken the restriction from the
/// same place rather than each inventing it. Two copies would agree today and drift the moment
/// either was corrected, and the drift would be silent — a name one family stores and the
/// other refuses, discovered by whoever copies a tree between two images.
///
/// It says nothing about *short* names, which reserve more; that is FAT's alone, because only
/// FAT has them.
pub