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