1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ==================== 3 ====================
4 Filesystem Mount API 4 Filesystem Mount API
5 ==================== 5 ====================
6 6
7 .. CONTENTS 7 .. CONTENTS
8 8
9 (1) Overview. 9 (1) Overview.
10 10
11 (2) The filesystem context. 11 (2) The filesystem context.
12 12
13 (3) The filesystem context operations. 13 (3) The filesystem context operations.
14 14
15 (4) Filesystem context security. 15 (4) Filesystem context security.
16 16
17 (5) VFS filesystem context API. 17 (5) VFS filesystem context API.
18 18
19 (6) Superblock creation helpers. 19 (6) Superblock creation helpers.
20 20
21 (7) Parameter description. 21 (7) Parameter description.
22 22
23 (8) Parameter helper functions. 23 (8) Parameter helper functions.
24 24
25 25
26 Overview 26 Overview
27 ======== 27 ========
28 28
29 The creation of new mounts is now to be done i 29 The creation of new mounts is now to be done in a multistep process:
30 30
31 (1) Create a filesystem context. 31 (1) Create a filesystem context.
32 32
33 (2) Parse the parameters and attach them to t 33 (2) Parse the parameters and attach them to the context. Parameters are
34 expected to be passed individually from u 34 expected to be passed individually from userspace, though legacy binary
35 parameters can also be handled. 35 parameters can also be handled.
36 36
37 (3) Validate and pre-process the context. 37 (3) Validate and pre-process the context.
38 38
39 (4) Get or create a superblock and mountable 39 (4) Get or create a superblock and mountable root.
40 40
41 (5) Perform the mount. 41 (5) Perform the mount.
42 42
43 (6) Return an error message attached to the c 43 (6) Return an error message attached to the context.
44 44
45 (7) Destroy the context. 45 (7) Destroy the context.
46 46
47 To support this, the file_system_type struct g 47 To support this, the file_system_type struct gains two new fields::
48 48
49 int (*init_fs_context)(struct fs_conte 49 int (*init_fs_context)(struct fs_context *fc);
50 const struct fs_parameter_description 50 const struct fs_parameter_description *parameters;
51 51
52 The first is invoked to set up the filesystem- 52 The first is invoked to set up the filesystem-specific parts of a filesystem
53 context, including the additional space, and t 53 context, including the additional space, and the second points to the
54 parameter description for validation at regist 54 parameter description for validation at registration time and querying by a
55 future system call. 55 future system call.
56 56
57 Note that security initialisation is done *aft 57 Note that security initialisation is done *after* the filesystem is called so
58 that the namespaces may be adjusted first. 58 that the namespaces may be adjusted first.
59 59
60 60
61 The Filesystem context 61 The Filesystem context
62 ====================== 62 ======================
63 63
64 The creation and reconfiguration of a superblo 64 The creation and reconfiguration of a superblock is governed by a filesystem
65 context. This is represented by the fs_contex 65 context. This is represented by the fs_context structure::
66 66
67 struct fs_context { 67 struct fs_context {
68 const struct fs_context_operat 68 const struct fs_context_operations *ops;
69 struct file_system_type *fs_ty 69 struct file_system_type *fs_type;
70 void *fs_pr 70 void *fs_private;
71 struct dentry *root; 71 struct dentry *root;
72 struct user_namespace *user_ 72 struct user_namespace *user_ns;
73 struct net *net_n 73 struct net *net_ns;
74 const struct cred *cred; 74 const struct cred *cred;
75 char *sourc 75 char *source;
76 char *subty 76 char *subtype;
77 void *secur 77 void *security;
78 void *s_fs_ 78 void *s_fs_info;
79 unsigned int sb_fla 79 unsigned int sb_flags;
80 unsigned int sb_fla 80 unsigned int sb_flags_mask;
81 unsigned int s_ifla 81 unsigned int s_iflags;
>> 82 unsigned int lsm_flags;
82 enum fs_context_purpose purpos 83 enum fs_context_purpose purpose:8;
83 ... 84 ...
84 }; 85 };
85 86
86 The fs_context fields are as follows: 87 The fs_context fields are as follows:
87 88
88 * :: 89 * ::
89 90
90 const struct fs_context_operations *ops 91 const struct fs_context_operations *ops
91 92
92 These are operations that can be done on 93 These are operations that can be done on a filesystem context (see
93 below). This must be set by the ->init_f 94 below). This must be set by the ->init_fs_context() file_system_type
94 operation. 95 operation.
95 96
96 * :: 97 * ::
97 98
98 struct file_system_type *fs_type 99 struct file_system_type *fs_type
99 100
100 A pointer to the file_system_type of the 101 A pointer to the file_system_type of the filesystem that is being
101 constructed or reconfigured. This retain 102 constructed or reconfigured. This retains a reference on the type owner.
102 103
103 * :: 104 * ::
104 105
105 void *fs_private 106 void *fs_private
106 107
107 A pointer to the file system's private da 108 A pointer to the file system's private data. This is where the filesystem
108 will need to store any options it parses. 109 will need to store any options it parses.
109 110
110 * :: 111 * ::
111 112
112 struct dentry *root 113 struct dentry *root
113 114
114 A pointer to the root of the mountable tr 115 A pointer to the root of the mountable tree (and indirectly, the
115 superblock thereof). This is filled in b 116 superblock thereof). This is filled in by the ->get_tree() op. If this
116 is set, an active reference on root->d_sb 117 is set, an active reference on root->d_sb must also be held.
117 118
118 * :: 119 * ::
119 120
120 struct user_namespace *user_ns 121 struct user_namespace *user_ns
121 struct net *net_ns 122 struct net *net_ns
122 123
123 There are a subset of the namespaces in u 124 There are a subset of the namespaces in use by the invoking process. They
124 retain references on each namespace. The 125 retain references on each namespace. The subscribed namespaces may be
125 replaced by the filesystem to reflect oth 126 replaced by the filesystem to reflect other sources, such as the parent
126 mount superblock on an automount. 127 mount superblock on an automount.
127 128
128 * :: 129 * ::
129 130
130 const struct cred *cred 131 const struct cred *cred
131 132
132 The mounter's credentials. This retains 133 The mounter's credentials. This retains a reference on the credentials.
133 134
134 * :: 135 * ::
135 136
136 char *source 137 char *source
137 138
138 This specifies the source. It may be a b 139 This specifies the source. It may be a block device (e.g. /dev/sda1) or
139 something more exotic, such as the "host: 140 something more exotic, such as the "host:/path" that NFS desires.
140 141
141 * :: 142 * ::
142 143
143 char *subtype 144 char *subtype
144 145
145 This is a string to be added to the type 146 This is a string to be added to the type displayed in /proc/mounts to
146 qualify it (used by FUSE). This is avail 147 qualify it (used by FUSE). This is available for the filesystem to set if
147 desired. 148 desired.
148 149
149 * :: 150 * ::
150 151
151 void *security 152 void *security
152 153
153 A place for the LSMs to hang their securi 154 A place for the LSMs to hang their security data for the superblock. The
154 relevant security operations are describe 155 relevant security operations are described below.
155 156
156 * :: 157 * ::
157 158
158 void *s_fs_info 159 void *s_fs_info
159 160
160 The proposed s_fs_info for a new superblo 161 The proposed s_fs_info for a new superblock, set in the superblock by
161 sget_fc(). This can be used to distingui 162 sget_fc(). This can be used to distinguish superblocks.
162 163
163 * :: 164 * ::
164 165
165 unsigned int sb_flags 166 unsigned int sb_flags
166 unsigned int sb_flags_mask 167 unsigned int sb_flags_mask
167 168
168 Which bits SB_* flags are to be set/clear 169 Which bits SB_* flags are to be set/cleared in super_block::s_flags.
169 170
170 * :: 171 * ::
171 172
172 unsigned int s_iflags 173 unsigned int s_iflags
173 174
174 These will be bitwise-OR'd with s->s_ifla 175 These will be bitwise-OR'd with s->s_iflags when a superblock is created.
175 176
176 * :: 177 * ::
177 178
178 enum fs_context_purpose 179 enum fs_context_purpose
179 180
180 This indicates the purpose for which the 181 This indicates the purpose for which the context is intended. The
181 available values are: 182 available values are:
182 183
183 ========================== ====== 184 ========================== ======================================
184 FS_CONTEXT_FOR_MOUNT, New su 185 FS_CONTEXT_FOR_MOUNT, New superblock for explicit mount
185 FS_CONTEXT_FOR_SUBMOUNT New au 186 FS_CONTEXT_FOR_SUBMOUNT New automatic submount of extant mount
186 FS_CONTEXT_FOR_RECONFIGURE Change 187 FS_CONTEXT_FOR_RECONFIGURE Change an existing mount
187 ========================== ====== 188 ========================== ======================================
188 189
189 The mount context is created by calling vfs_ne 190 The mount context is created by calling vfs_new_fs_context() or
190 vfs_dup_fs_context() and is destroyed with put 191 vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the
191 structure is not refcounted. 192 structure is not refcounted.
192 193
193 VFS, security and filesystem mount options are 194 VFS, security and filesystem mount options are set individually with
194 vfs_parse_mount_option(). Options provided by 195 vfs_parse_mount_option(). Options provided by the old mount(2) system call as
195 a page of data can be parsed with generic_pars 196 a page of data can be parsed with generic_parse_monolithic().
196 197
197 When mounting, the filesystem is allowed to ta 198 When mounting, the filesystem is allowed to take data from any of the pointers
198 and attach it to the superblock (or whatever), 199 and attach it to the superblock (or whatever), provided it clears the pointer
199 in the mount context. 200 in the mount context.
200 201
201 The filesystem is also allowed to allocate res 202 The filesystem is also allowed to allocate resources and pin them with the
202 mount context. For instance, NFS might pin th 203 mount context. For instance, NFS might pin the appropriate protocol version
203 module. 204 module.
204 205
205 206
206 The Filesystem Context Operations 207 The Filesystem Context Operations
207 ================================= 208 =================================
208 209
209 The filesystem context points to a table of op 210 The filesystem context points to a table of operations::
210 211
211 struct fs_context_operations { 212 struct fs_context_operations {
212 void (*free)(struct fs_context 213 void (*free)(struct fs_context *fc);
213 int (*dup)(struct fs_context * 214 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
214 int (*parse_param)(struct fs_c 215 int (*parse_param)(struct fs_context *fc,
215 struct fs_p 216 struct fs_parameter *param);
216 int (*parse_monolithic)(struct 217 int (*parse_monolithic)(struct fs_context *fc, void *data);
217 int (*get_tree)(struct fs_cont 218 int (*get_tree)(struct fs_context *fc);
218 int (*reconfigure)(struct fs_c 219 int (*reconfigure)(struct fs_context *fc);
219 }; 220 };
220 221
221 These operations are invoked by the various st 222 These operations are invoked by the various stages of the mount procedure to
222 manage the filesystem context. They are as fo 223 manage the filesystem context. They are as follows:
223 224
224 * :: 225 * ::
225 226
226 void (*free)(struct fs_context *fc); 227 void (*free)(struct fs_context *fc);
227 228
228 Called to clean up the filesystem-specifi 229 Called to clean up the filesystem-specific part of the filesystem context
229 when the context is destroyed. It should 230 when the context is destroyed. It should be aware that parts of the
230 context may have been removed and NULL'd 231 context may have been removed and NULL'd out by ->get_tree().
231 232
232 * :: 233 * ::
233 234
234 int (*dup)(struct fs_context *fc, stru 235 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
235 236
236 Called when a filesystem context has been 237 Called when a filesystem context has been duplicated to duplicate the
237 filesystem-private data. An error may be 238 filesystem-private data. An error may be returned to indicate failure to
238 do this. 239 do this.
239 240
240 .. Warning:: 241 .. Warning::
241 242
242 Note that even if this fails, put_fs_ 243 Note that even if this fails, put_fs_context() will be called
243 immediately thereafter, so ->dup() *m 244 immediately thereafter, so ->dup() *must* make the
244 filesystem-private data safe for ->fr 245 filesystem-private data safe for ->free().
245 246
246 * :: 247 * ::
247 248
248 int (*parse_param)(struct fs_context * 249 int (*parse_param)(struct fs_context *fc,
249 struct fs_parameter 250 struct fs_parameter *param);
250 251
251 Called when a parameter is being added to 252 Called when a parameter is being added to the filesystem context. param
252 points to the key name and maybe a value 253 points to the key name and maybe a value object. VFS-specific options
253 will have been weeded out and fc->sb_flag 254 will have been weeded out and fc->sb_flags updated in the context.
254 Security options will also have been weed 255 Security options will also have been weeded out and fc->security updated.
255 256
256 The parameter can be parsed with fs_parse 257 The parameter can be parsed with fs_parse() and fs_lookup_param(). Note
257 that the source(s) are presented as param 258 that the source(s) are presented as parameters named "source".
258 259
259 If successful, 0 should be returned or a 260 If successful, 0 should be returned or a negative error code otherwise.
260 261
261 * :: 262 * ::
262 263
263 int (*parse_monolithic)(struct fs_cont 264 int (*parse_monolithic)(struct fs_context *fc, void *data);
264 265
265 Called when the mount(2) system call is i 266 Called when the mount(2) system call is invoked to pass the entire data
266 page in one go. If this is expected to b 267 page in one go. If this is expected to be just a list of "key[=val]"
267 items separated by commas, then this may 268 items separated by commas, then this may be set to NULL.
268 269
269 The return value is as for ->parse_param( 270 The return value is as for ->parse_param().
270 271
271 If the filesystem (e.g. NFS) needs to exa 272 If the filesystem (e.g. NFS) needs to examine the data first and then
272 finds it's the standard key-val list then 273 finds it's the standard key-val list then it may pass it off to
273 generic_parse_monolithic(). 274 generic_parse_monolithic().
274 275
275 * :: 276 * ::
276 277
277 int (*get_tree)(struct fs_context *fc) 278 int (*get_tree)(struct fs_context *fc);
278 279
279 Called to get or create the mountable roo 280 Called to get or create the mountable root and superblock, using the
280 information stored in the filesystem cont 281 information stored in the filesystem context (reconfiguration goes via a
281 different vector). It may detach any res 282 different vector). It may detach any resources it desires from the
282 filesystem context and transfer them to t 283 filesystem context and transfer them to the superblock it creates.
283 284
284 On success it should set fc->root to the 285 On success it should set fc->root to the mountable root and return 0. In
285 the case of an error, it should return a 286 the case of an error, it should return a negative error code.
286 287
287 The phase on a userspace-driven context w 288 The phase on a userspace-driven context will be set to only allow this to
288 be called once on any particular context. 289 be called once on any particular context.
289 290
290 * :: 291 * ::
291 292
292 int (*reconfigure)(struct fs_context * 293 int (*reconfigure)(struct fs_context *fc);
293 294
294 Called to effect reconfiguration of a sup 295 Called to effect reconfiguration of a superblock using information stored
295 in the filesystem context. It may detach 296 in the filesystem context. It may detach any resources it desires from
296 the filesystem context and transfer them 297 the filesystem context and transfer them to the superblock. The
297 superblock can be found from fc->root->d_ 298 superblock can be found from fc->root->d_sb.
298 299
299 On success it should return 0. In the ca 300 On success it should return 0. In the case of an error, it should return
300 a negative error code. 301 a negative error code.
301 302
302 .. Note:: reconfigure is intended as a re 303 .. Note:: reconfigure is intended as a replacement for remount_fs.
303 304
304 305
305 Filesystem context Security 306 Filesystem context Security
306 =========================== 307 ===========================
307 308
308 The filesystem context contains a security poi 309 The filesystem context contains a security pointer that the LSMs can use for
309 building up a security context for the superbl 310 building up a security context for the superblock to be mounted. There are a
310 number of operations used by the new mount cod 311 number of operations used by the new mount code for this purpose:
311 312
312 * :: 313 * ::
313 314
314 int security_fs_context_alloc(struct f 315 int security_fs_context_alloc(struct fs_context *fc,
315 struct d 316 struct dentry *reference);
316 317
317 Called to initialise fc->security (which 318 Called to initialise fc->security (which is preset to NULL) and allocate
318 any resources needed. It should return 0 319 any resources needed. It should return 0 on success or a negative error
319 code on failure. 320 code on failure.
320 321
321 reference will be non-NULL if the context 322 reference will be non-NULL if the context is being created for superblock
322 reconfiguration (FS_CONTEXT_FOR_RECONFIGU 323 reconfiguration (FS_CONTEXT_FOR_RECONFIGURE) in which case it indicates
323 the root dentry of the superblock to be r 324 the root dentry of the superblock to be reconfigured. It will also be
324 non-NULL in the case of a submount (FS_CO 325 non-NULL in the case of a submount (FS_CONTEXT_FOR_SUBMOUNT) in which case
325 it indicates the automount point. 326 it indicates the automount point.
326 327
327 * :: 328 * ::
328 329
329 int security_fs_context_dup(struct fs_ 330 int security_fs_context_dup(struct fs_context *fc,
330 struct fs_ 331 struct fs_context *src_fc);
331 332
332 Called to initialise fc->security (which 333 Called to initialise fc->security (which is preset to NULL) and allocate
333 any resources needed. The original files 334 any resources needed. The original filesystem context is pointed to by
334 src_fc and may be used for reference. It 335 src_fc and may be used for reference. It should return 0 on success or a
335 negative error code on failure. 336 negative error code on failure.
336 337
337 * :: 338 * ::
338 339
339 void security_fs_context_free(struct f 340 void security_fs_context_free(struct fs_context *fc);
340 341
341 Called to clean up anything attached to f 342 Called to clean up anything attached to fc->security. Note that the
342 contents may have been transferred to a s 343 contents may have been transferred to a superblock and the pointer cleared
343 during get_tree. 344 during get_tree.
344 345
345 * :: 346 * ::
346 347
347 int security_fs_context_parse_param(st 348 int security_fs_context_parse_param(struct fs_context *fc,
348 st 349 struct fs_parameter *param);
349 350
350 Called for each mount parameter, includin 351 Called for each mount parameter, including the source. The arguments are
351 as for the ->parse_param() method. It sh 352 as for the ->parse_param() method. It should return 0 to indicate that
352 the parameter should be passed on to the 353 the parameter should be passed on to the filesystem, 1 to indicate that
353 the parameter should be discarded or an e 354 the parameter should be discarded or an error to indicate that the
354 parameter should be rejected. 355 parameter should be rejected.
355 356
356 The value pointed to by param may be modi 357 The value pointed to by param may be modified (if a string) or stolen
357 (provided the value pointer is NULL'd out 358 (provided the value pointer is NULL'd out). If it is stolen, 1 must be
358 returned to prevent it being passed to th 359 returned to prevent it being passed to the filesystem.
359 360
360 * :: 361 * ::
361 362
362 int security_fs_context_validate(struc 363 int security_fs_context_validate(struct fs_context *fc);
363 364
364 Called after all the options have been pa 365 Called after all the options have been parsed to validate the collection
365 as a whole and to do any necessary alloca 366 as a whole and to do any necessary allocation so that
366 security_sb_get_tree() and security_sb_re 367 security_sb_get_tree() and security_sb_reconfigure() are less likely to
367 fail. It should return 0 or a negative e 368 fail. It should return 0 or a negative error code.
368 369
369 In the case of reconfiguration, the targe 370 In the case of reconfiguration, the target superblock will be accessible
370 via fc->root. 371 via fc->root.
371 372
372 * :: 373 * ::
373 374
374 int security_sb_get_tree(struct fs_con 375 int security_sb_get_tree(struct fs_context *fc);
375 376
376 Called during the mount procedure to veri 377 Called during the mount procedure to verify that the specified superblock
377 is allowed to be mounted and to transfer 378 is allowed to be mounted and to transfer the security data there. It
378 should return 0 or a negative error code. 379 should return 0 or a negative error code.
379 380
380 * :: 381 * ::
381 382
382 void security_sb_reconfigure(struct fs 383 void security_sb_reconfigure(struct fs_context *fc);
383 384
384 Called to apply any reconfiguration to an 385 Called to apply any reconfiguration to an LSM's context. It must not
385 fail. Error checking and resource alloca 386 fail. Error checking and resource allocation must be done in advance by
386 the parameter parsing and validation hook 387 the parameter parsing and validation hooks.
387 388
388 * :: 389 * ::
389 390
390 int security_sb_mountpoint(struct fs_c 391 int security_sb_mountpoint(struct fs_context *fc,
391 struct path 392 struct path *mountpoint,
392 unsigned in 393 unsigned int mnt_flags);
393 394
394 Called during the mount procedure to veri 395 Called during the mount procedure to verify that the root dentry attached
395 to the context is permitted to be attache 396 to the context is permitted to be attached to the specified mountpoint.
396 It should return 0 on success or a negati 397 It should return 0 on success or a negative error code on failure.
397 398
398 399
399 VFS Filesystem context API 400 VFS Filesystem context API
400 ========================== 401 ==========================
401 402
402 There are four operations for creating a files 403 There are four operations for creating a filesystem context and one for
403 destroying a context: 404 destroying a context:
404 405
405 * :: 406 * ::
406 407
407 struct fs_context *fs_context_for_mount 408 struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,
408 409 unsigned int sb_flags);
409 410
410 Allocate a filesystem context for the pur 411 Allocate a filesystem context for the purpose of setting up a new mount,
411 whether that be with a new superblock or 412 whether that be with a new superblock or sharing an existing one. This
412 sets the superblock flags, initialises th 413 sets the superblock flags, initialises the security and calls
413 fs_type->init_fs_context() to initialise 414 fs_type->init_fs_context() to initialise the filesystem private data.
414 415
415 fs_type specifies the filesystem type tha 416 fs_type specifies the filesystem type that will manage the context and
416 sb_flags presets the superblock flags sto 417 sb_flags presets the superblock flags stored therein.
417 418
418 * :: 419 * ::
419 420
420 struct fs_context *fs_context_for_recon 421 struct fs_context *fs_context_for_reconfigure(
421 struct dentry *dentry, 422 struct dentry *dentry,
422 unsigned int sb_flags, 423 unsigned int sb_flags,
423 unsigned int sb_flags_mask); 424 unsigned int sb_flags_mask);
424 425
425 Allocate a filesystem context for the pur 426 Allocate a filesystem context for the purpose of reconfiguring an
426 existing superblock. dentry provides a r 427 existing superblock. dentry provides a reference to the superblock to be
427 configured. sb_flags and sb_flags_mask i 428 configured. sb_flags and sb_flags_mask indicate which superblock flags
428 need changing and to what. 429 need changing and to what.
429 430
430 * :: 431 * ::
431 432
432 struct fs_context *fs_context_for_submo 433 struct fs_context *fs_context_for_submount(
433 struct file_system_type *fs_ty 434 struct file_system_type *fs_type,
434 struct dentry *reference); 435 struct dentry *reference);
435 436
436 Allocate a filesystem context for the pur 437 Allocate a filesystem context for the purpose of creating a new mount for
437 an automount point or other derived super 438 an automount point or other derived superblock. fs_type specifies the
438 filesystem type that will manage the cont 439 filesystem type that will manage the context and the reference dentry
439 supplies the parameters. Namespaces are 440 supplies the parameters. Namespaces are propagated from the reference
440 dentry's superblock also. 441 dentry's superblock also.
441 442
442 Note that it's not a requirement that the 443 Note that it's not a requirement that the reference dentry be of the same
443 filesystem type as fs_type. 444 filesystem type as fs_type.
444 445
445 * :: 446 * ::
446 447
447 struct fs_context *vfs_dup_fs_context( 448 struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);
448 449
449 Duplicate a filesystem context, copying a 450 Duplicate a filesystem context, copying any options noted and duplicating
450 or additionally referencing any resources 451 or additionally referencing any resources held therein. This is available
451 for use where a filesystem has to get a m 452 for use where a filesystem has to get a mount within a mount, such as NFS4
452 does by internally mounting the root of t 453 does by internally mounting the root of the target server and then doing a
453 private pathwalk to the target directory. 454 private pathwalk to the target directory.
454 455
455 The purpose in the new context is inherit 456 The purpose in the new context is inherited from the old one.
456 457
457 * :: 458 * ::
458 459
459 void put_fs_context(struct fs_context * 460 void put_fs_context(struct fs_context *fc);
460 461
461 Destroy a filesystem context, releasing a 462 Destroy a filesystem context, releasing any resources it holds. This
462 calls the ->free() operation. This is in 463 calls the ->free() operation. This is intended to be called by anyone who
463 created a filesystem context. 464 created a filesystem context.
464 465
465 .. Warning:: 466 .. Warning::
466 467
467 filesystem contexts are not refcounted 468 filesystem contexts are not refcounted, so this causes unconditional
468 destruction. 469 destruction.
469 470
470 In all the above operations, apart from the pu 471 In all the above operations, apart from the put op, the return is a mount
471 context pointer or a negative error code. 472 context pointer or a negative error code.
472 473
473 For the remaining operations, if an error occu 474 For the remaining operations, if an error occurs, a negative error code will be
474 returned. 475 returned.
475 476
476 * :: 477 * ::
477 478
478 int vfs_parse_fs_param(struct fs_conte 479 int vfs_parse_fs_param(struct fs_context *fc,
479 struct fs_param 480 struct fs_parameter *param);
480 481
481 Supply a single mount parameter to the fi 482 Supply a single mount parameter to the filesystem context. This includes
482 the specification of the source/device wh 483 the specification of the source/device which is specified as the "source"
483 parameter (which may be specified multipl 484 parameter (which may be specified multiple times if the filesystem
484 supports that). 485 supports that).
485 486
486 param specifies the parameter key name an 487 param specifies the parameter key name and the value. The parameter is
487 first checked to see if it corresponds to 488 first checked to see if it corresponds to a standard mount flag (in which
488 case it is used to set an SB_xxx flag and 489 case it is used to set an SB_xxx flag and consumed) or a security option
489 (in which case the LSM consumes it) befor 490 (in which case the LSM consumes it) before it is passed on to the
490 filesystem. 491 filesystem.
491 492
492 The parameter value is typed and can be o 493 The parameter value is typed and can be one of:
493 494
494 ==================== ====== 495 ==================== =============================
495 fs_value_is_flag Parame 496 fs_value_is_flag Parameter not given a value
496 fs_value_is_string Value 497 fs_value_is_string Value is a string
497 fs_value_is_blob Value 498 fs_value_is_blob Value is a binary blob
498 fs_value_is_filename Value 499 fs_value_is_filename Value is a filename* + dirfd
499 fs_value_is_file Value 500 fs_value_is_file Value is an open file (file*)
500 ==================== ====== 501 ==================== =============================
501 502
502 If there is a value, that value is stored 503 If there is a value, that value is stored in a union in the struct in one
503 of param->{string,blob,name,file}. Note 504 of param->{string,blob,name,file}. Note that the function may steal and
504 clear the pointer, but then becomes respo 505 clear the pointer, but then becomes responsible for disposing of the
505 object. 506 object.
506 507
507 * :: 508 * ::
508 509
509 int vfs_parse_fs_string(struct fs_conte 510 int vfs_parse_fs_string(struct fs_context *fc, const char *key,
510 const char *val 511 const char *value, size_t v_size);
511 512
512 A wrapper around vfs_parse_fs_param() tha 513 A wrapper around vfs_parse_fs_param() that copies the value string it is
513 passed. 514 passed.
514 515
515 * :: 516 * ::
516 517
517 int generic_parse_monolithic(struct fs_ 518 int generic_parse_monolithic(struct fs_context *fc, void *data);
518 519
519 Parse a sys_mount() data page, assuming t 520 Parse a sys_mount() data page, assuming the form to be a text list
520 consisting of key[=val] options separated 521 consisting of key[=val] options separated by commas. Each item in the
521 list is passed to vfs_mount_option(). Th 522 list is passed to vfs_mount_option(). This is the default when the
522 ->parse_monolithic() method is NULL. 523 ->parse_monolithic() method is NULL.
523 524
524 * :: 525 * ::
525 526
526 int vfs_get_tree(struct fs_context *fc) 527 int vfs_get_tree(struct fs_context *fc);
527 528
528 Get or create the mountable root and supe 529 Get or create the mountable root and superblock, using the parameters in
529 the filesystem context to select/configur 530 the filesystem context to select/configure the superblock. This invokes
530 the ->get_tree() method. 531 the ->get_tree() method.
531 532
532 * :: 533 * ::
533 534
534 struct vfsmount *vfs_create_mount(struc 535 struct vfsmount *vfs_create_mount(struct fs_context *fc);
535 536
536 Create a mount given the parameters in th 537 Create a mount given the parameters in the specified filesystem context.
537 Note that this does not attach the mount 538 Note that this does not attach the mount to anything.
538 539
539 540
540 Superblock Creation Helpers 541 Superblock Creation Helpers
541 =========================== 542 ===========================
542 543
543 A number of VFS helpers are available for use 544 A number of VFS helpers are available for use by filesystems for the creation
544 or looking up of superblocks. 545 or looking up of superblocks.
545 546
546 * :: 547 * ::
547 548
548 struct super_block * 549 struct super_block *
549 sget_fc(struct fs_context *fc, 550 sget_fc(struct fs_context *fc,
550 int (*test)(struct super_block 551 int (*test)(struct super_block *sb, struct fs_context *fc),
551 int (*set)(struct super_block * 552 int (*set)(struct super_block *sb, struct fs_context *fc));
552 553
553 This is the core routine. If test is non 554 This is the core routine. If test is non-NULL, it searches for an
554 existing superblock matching the criteria 555 existing superblock matching the criteria held in the fs_context, using
555 the test function to match them. If no m 556 the test function to match them. If no match is found, a new superblock
556 is created and the set function is called 557 is created and the set function is called to set it up.
557 558
558 Prior to the set function being called, f 559 Prior to the set function being called, fc->s_fs_info will be transferred
559 to sb->s_fs_info - and fc->s_fs_info will 560 to sb->s_fs_info - and fc->s_fs_info will be cleared if set returns
560 success (ie. 0). 561 success (ie. 0).
561 562
562 The following helpers all wrap sget_fc(): 563 The following helpers all wrap sget_fc():
563 564
564 (1) vfs_get_single_super 565 (1) vfs_get_single_super
565 566
566 Only one such superblock may exist 567 Only one such superblock may exist in the system. Any further
567 attempt to get a new superblock ge 568 attempt to get a new superblock gets this one (and any parameter
568 differences are ignored). 569 differences are ignored).
569 570
570 (2) vfs_get_keyed_super 571 (2) vfs_get_keyed_super
571 572
572 Multiple superblocks of this type 573 Multiple superblocks of this type may exist and they're keyed on
573 their s_fs_info pointer (for examp 574 their s_fs_info pointer (for example this may refer to a
574 namespace). 575 namespace).
575 576
576 (3) vfs_get_independent_super 577 (3) vfs_get_independent_super
577 578
578 Multiple independent superblocks o 579 Multiple independent superblocks of this type may exist. This
579 function never matches an existing 580 function never matches an existing one and always creates a new
580 one. 581 one.
581 582
582 583
583 Parameter Description 584 Parameter Description
584 ===================== 585 =====================
585 586
586 Parameters are described using structures defi 587 Parameters are described using structures defined in linux/fs_parser.h.
587 There's a core description struct that links e 588 There's a core description struct that links everything together::
588 589
589 struct fs_parameter_description { 590 struct fs_parameter_description {
590 const struct fs_parameter_spec 591 const struct fs_parameter_spec *specs;
591 const struct fs_parameter_enum 592 const struct fs_parameter_enum *enums;
592 }; 593 };
593 594
594 For example:: 595 For example::
595 596
596 enum { 597 enum {
597 Opt_autocell, 598 Opt_autocell,
598 Opt_bar, 599 Opt_bar,
599 Opt_dyn, 600 Opt_dyn,
600 Opt_foo, 601 Opt_foo,
601 Opt_source, 602 Opt_source,
602 }; 603 };
603 604
604 static const struct fs_parameter_descr 605 static const struct fs_parameter_description afs_fs_parameters = {
605 .specs = afs_param_sp 606 .specs = afs_param_specs,
606 .enums = afs_param_en 607 .enums = afs_param_enums,
607 }; 608 };
608 609
609 The members are as follows: 610 The members are as follows:
610 611
611 (1) :: 612 (1) ::
612 613
613 const struct fs_parameter_specification 614 const struct fs_parameter_specification *specs;
614 615
615 Table of parameter specifications, termin 616 Table of parameter specifications, terminated with a null entry, where the
616 entries are of type:: 617 entries are of type::
617 618
618 struct fs_parameter_spec { 619 struct fs_parameter_spec {
619 const char *name; 620 const char *name;
620 u8 opt; 621 u8 opt;
621 enum fs_parameter_type type:8 622 enum fs_parameter_type type:8;
622 unsigned short flags; 623 unsigned short flags;
623 }; 624 };
624 625
625 The 'name' field is a string to match exa 626 The 'name' field is a string to match exactly to the parameter key (no
626 wildcards, patterns and no case-independe 627 wildcards, patterns and no case-independence) and 'opt' is the value that
627 will be returned by the fs_parser() funct 628 will be returned by the fs_parser() function in the case of a successful
628 match. 629 match.
629 630
630 The 'type' field indicates the desired va 631 The 'type' field indicates the desired value type and must be one of:
631 632
632 ======================= ============== 633 ======================= ======================= =====================
633 TYPE NAME EXPECTED VALUE 634 TYPE NAME EXPECTED VALUE RESULT IN
634 ======================= ============== 635 ======================= ======================= =====================
635 fs_param_is_flag No value 636 fs_param_is_flag No value n/a
636 fs_param_is_bool Boolean value 637 fs_param_is_bool Boolean value result->boolean
637 fs_param_is_u32 32-bit unsigne 638 fs_param_is_u32 32-bit unsigned int result->uint_32
638 fs_param_is_u32_octal 32-bit octal i 639 fs_param_is_u32_octal 32-bit octal int result->uint_32
639 fs_param_is_u32_hex 32-bit hex int 640 fs_param_is_u32_hex 32-bit hex int result->uint_32
640 fs_param_is_s32 32-bit signed 641 fs_param_is_s32 32-bit signed int result->int_32
641 fs_param_is_u64 64-bit unsigne 642 fs_param_is_u64 64-bit unsigned int result->uint_64
642 fs_param_is_enum Enum value nam 643 fs_param_is_enum Enum value name result->uint_32
643 fs_param_is_string Arbitrary stri 644 fs_param_is_string Arbitrary string param->string
644 fs_param_is_blob Binary blob 645 fs_param_is_blob Binary blob param->blob
645 fs_param_is_blockdev Blockdev path 646 fs_param_is_blockdev Blockdev path * Needs lookup
646 fs_param_is_path Path 647 fs_param_is_path Path * Needs lookup
647 fs_param_is_fd File descripto 648 fs_param_is_fd File descriptor result->int_32
648 fs_param_is_uid User ID (u32) <<
649 fs_param_is_gid Group ID (u32) <<
650 ======================= ============== 649 ======================= ======================= =====================
651 650
652 Note that if the value is of fs_param_is_ 651 Note that if the value is of fs_param_is_bool type, fs_parse() will try
653 to match any string value against "0", "1 652 to match any string value against "0", "1", "no", "yes", "false", "true".
654 653
655 Each parameter can also be qualified with 654 Each parameter can also be qualified with 'flags':
656 655
657 ======================= ============== 656 ======================= ================================================
658 fs_param_v_optional The value is o 657 fs_param_v_optional The value is optional
659 fs_param_neg_with_no result->negate 658 fs_param_neg_with_no result->negated set if key is prefixed with "no"
660 fs_param_neg_with_empty result->negate 659 fs_param_neg_with_empty result->negated set if value is ""
661 fs_param_deprecated The parameter 660 fs_param_deprecated The parameter is deprecated.
662 ======================= ============== 661 ======================= ================================================
663 662
664 These are wrapped with a number of conven 663 These are wrapped with a number of convenience wrappers:
665 664
666 ======================= ============== 665 ======================= ===============================================
667 MACRO SPECIFIES 666 MACRO SPECIFIES
668 ======================= ============== 667 ======================= ===============================================
669 fsparam_flag() fs_param_is_fl 668 fsparam_flag() fs_param_is_flag
670 fsparam_flag_no() fs_param_is_fl 669 fsparam_flag_no() fs_param_is_flag, fs_param_neg_with_no
671 fsparam_bool() fs_param_is_bo 670 fsparam_bool() fs_param_is_bool
672 fsparam_u32() fs_param_is_u3 671 fsparam_u32() fs_param_is_u32
673 fsparam_u32oct() fs_param_is_u3 672 fsparam_u32oct() fs_param_is_u32_octal
674 fsparam_u32hex() fs_param_is_u3 673 fsparam_u32hex() fs_param_is_u32_hex
675 fsparam_s32() fs_param_is_s3 674 fsparam_s32() fs_param_is_s32
676 fsparam_u64() fs_param_is_u6 675 fsparam_u64() fs_param_is_u64
677 fsparam_enum() fs_param_is_en 676 fsparam_enum() fs_param_is_enum
678 fsparam_string() fs_param_is_st 677 fsparam_string() fs_param_is_string
679 fsparam_blob() fs_param_is_bl 678 fsparam_blob() fs_param_is_blob
680 fsparam_bdev() fs_param_is_bl 679 fsparam_bdev() fs_param_is_blockdev
681 fsparam_path() fs_param_is_pa 680 fsparam_path() fs_param_is_path
682 fsparam_fd() fs_param_is_fd 681 fsparam_fd() fs_param_is_fd
683 fsparam_uid() fs_param_is_ui <<
684 fsparam_gid() fs_param_is_gi <<
685 ======================= ============== 682 ======================= ===============================================
686 683
687 all of which take two arguments, name str 684 all of which take two arguments, name string and option number - for
688 example:: 685 example::
689 686
690 static const struct fs_parameter_spec 687 static const struct fs_parameter_spec afs_param_specs[] = {
691 fsparam_flag ("autocell", 688 fsparam_flag ("autocell", Opt_autocell),
692 fsparam_flag ("dyn", 689 fsparam_flag ("dyn", Opt_dyn),
693 fsparam_string ("source", 690 fsparam_string ("source", Opt_source),
694 fsparam_flag_no ("foo", 691 fsparam_flag_no ("foo", Opt_foo),
695 {} 692 {}
696 }; 693 };
697 694
698 An addition macro, __fsparam() is provide 695 An addition macro, __fsparam() is provided that takes an additional pair
699 of arguments to specify the type and the 696 of arguments to specify the type and the flags for anything that doesn't
700 match one of the above macros. 697 match one of the above macros.
701 698
702 (2) :: 699 (2) ::
703 700
704 const struct fs_parameter_enum *enums; 701 const struct fs_parameter_enum *enums;
705 702
706 Table of enum value names to integer mapp 703 Table of enum value names to integer mappings, terminated with a null
707 entry. This is of type:: 704 entry. This is of type::
708 705
709 struct fs_parameter_enum { 706 struct fs_parameter_enum {
710 u8 opt; 707 u8 opt;
711 char name[14]; 708 char name[14];
712 u8 value; 709 u8 value;
713 }; 710 };
714 711
715 Where the array is an unsorted list of { 712 Where the array is an unsorted list of { parameter ID, name }-keyed
716 elements that indicate the value to map t 713 elements that indicate the value to map to, e.g.::
717 714
718 static const struct fs_parameter_enum 715 static const struct fs_parameter_enum afs_param_enums[] = {
719 { Opt_bar, "x", 1}, 716 { Opt_bar, "x", 1},
720 { Opt_bar, "y", 23}, 717 { Opt_bar, "y", 23},
721 { Opt_bar, "z", 42}, 718 { Opt_bar, "z", 42},
722 }; 719 };
723 720
724 If a parameter of type fs_param_is_enum i 721 If a parameter of type fs_param_is_enum is encountered, fs_parse() will
725 try to look the value up in the enum tabl 722 try to look the value up in the enum table and the result will be stored
726 in the parse result. 723 in the parse result.
727 724
728 The parser should be pointed to by the parser 725 The parser should be pointed to by the parser pointer in the file_system_type
729 struct as this will provide validation on regi 726 struct as this will provide validation on registration (if
730 CONFIG_VALIDATE_FS_PARSER=y) and will allow th 727 CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
731 userspace using the fsinfo() syscall. 728 userspace using the fsinfo() syscall.
732 729
733 730
734 Parameter Helper Functions 731 Parameter Helper Functions
735 ========================== 732 ==========================
736 733
737 A number of helper functions are provided to h 734 A number of helper functions are provided to help a filesystem or an LSM
738 process the parameters it is given. 735 process the parameters it is given.
739 736
740 * :: 737 * ::
741 738
742 int lookup_constant(const struct consta 739 int lookup_constant(const struct constant_table tbl[],
743 const char *name, i 740 const char *name, int not_found);
744 741
745 Look up a constant by name in a table of 742 Look up a constant by name in a table of name -> integer mappings. The
746 table is an array of elements of the foll 743 table is an array of elements of the following type::
747 744
748 struct constant_table { 745 struct constant_table {
749 const char *name; 746 const char *name;
750 int value; 747 int value;
751 }; 748 };
752 749
753 If a match is found, the corresponding va 750 If a match is found, the corresponding value is returned. If a match
754 isn't found, the not_found value is retur 751 isn't found, the not_found value is returned instead.
755 752
756 * :: 753 * ::
757 754
758 bool validate_constant_table(const stru 755 bool validate_constant_table(const struct constant_table *tbl,
759 size_t tbl 756 size_t tbl_size,
760 int low, i 757 int low, int high, int special);
761 758
762 Validate a constant table. Checks that a 759 Validate a constant table. Checks that all the elements are appropriately
763 ordered, that there are no duplicates and 760 ordered, that there are no duplicates and that the values are between low
764 and high inclusive, though provision is m 761 and high inclusive, though provision is made for one allowable special
765 value outside of that range. If no speci 762 value outside of that range. If no special value is required, special
766 should just be set to lie inside the low- 763 should just be set to lie inside the low-to-high range.
767 764
768 If all is good, true is returned. If the 765 If all is good, true is returned. If the table is invalid, errors are
769 logged to the kernel log buffer and false 766 logged to the kernel log buffer and false is returned.
770 767
771 * :: 768 * ::
772 769
773 bool fs_validate_description(const stru 770 bool fs_validate_description(const struct fs_parameter_description *desc);
774 771
775 This performs some validation checks on a 772 This performs some validation checks on a parameter description. It
776 returns true if the description is good a 773 returns true if the description is good and false if it is not. It will
777 log errors to the kernel log buffer if va 774 log errors to the kernel log buffer if validation fails.
778 775
779 * :: 776 * ::
780 777
781 int fs_parse(struct fs_context *fc, 778 int fs_parse(struct fs_context *fc,
782 const struct fs_parameter 779 const struct fs_parameter_description *desc,
783 struct fs_parameter *para 780 struct fs_parameter *param,
784 struct fs_parse_result *r 781 struct fs_parse_result *result);
785 782
786 This is the main interpreter of parameter 783 This is the main interpreter of parameters. It uses the parameter
787 description to look up a parameter by key 784 description to look up a parameter by key name and to convert that to an
788 option number (which it returns). 785 option number (which it returns).
789 786
790 If successful, and if the parameter type 787 If successful, and if the parameter type indicates the result is a
791 boolean, integer, enum, uid, or gid type, !! 788 boolean, integer or enum type, the value is converted by this function and
792 function and the result stored in !! 789 the result stored in result->{boolean,int_32,uint_32,uint_64}.
793 result->{boolean,int_32,uint_32,uint_64,u <<
794 790
795 If a match isn't initially made, the key 791 If a match isn't initially made, the key is prefixed with "no" and no
796 value is present then an attempt will be 792 value is present then an attempt will be made to look up the key with the
797 prefix removed. If this matches a parame 793 prefix removed. If this matches a parameter for which the type has flag
798 fs_param_neg_with_no set, then a match wi 794 fs_param_neg_with_no set, then a match will be made and result->negated
799 will be set to true. 795 will be set to true.
800 796
801 If the parameter isn't matched, -ENOPARAM 797 If the parameter isn't matched, -ENOPARAM will be returned; if the
802 parameter is matched, but the value is er 798 parameter is matched, but the value is erroneous, -EINVAL will be
803 returned; otherwise the parameter's optio 799 returned; otherwise the parameter's option number will be returned.
804 800
805 * :: 801 * ::
806 802
807 int fs_lookup_param(struct fs_context * 803 int fs_lookup_param(struct fs_context *fc,
808 struct fs_parameter 804 struct fs_parameter *value,
809 bool want_bdev, 805 bool want_bdev,
810 unsigned int flags, 806 unsigned int flags,
811 struct path *_path) 807 struct path *_path);
812 808
813 This takes a parameter that carries a str 809 This takes a parameter that carries a string or filename type and attempts
814 to do a path lookup on it. If the parame 810 to do a path lookup on it. If the parameter expects a blockdev, a check
815 is made that the inode actually represent 811 is made that the inode actually represents one.
816 812
817 Returns 0 if successful and ``*_path`` wi 813 Returns 0 if successful and ``*_path`` will be set; returns a negative
818 error code if not. 814 error code if not.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.