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