Loading...
1.. SPDX-License-Identifier: GPL-2.0
2
3====================
4Filesystem Mount API
5====================
6
7.. CONTENTS
8
9 (1) Overview.
10
11 (2) The filesystem context.
12
13 (3) The filesystem context operations.
14
15 (4) Filesystem context security.
16
17 (5) VFS filesystem context API.
18
19 (6) Superblock creation helpers.
20
21 (7) Parameter description.
22
23 (8) Parameter helper functions.
24
25
26Overview
27========
28
29The 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
47To support this, the file_system_type struct gains two new fields::
48
49 int (*init_fs_context)(struct fs_context *fc);
50 const struct fs_parameter_description *parameters;
51
52The first is invoked to set up the filesystem-specific parts of a filesystem
53context, including the additional space, and the second points to the
54parameter description for validation at registration time and querying by a
55future system call.
56
57Note that security initialisation is done *after* the filesystem is called so
58that the namespaces may be adjusted first.
59
60
61The Filesystem context
62======================
63
64The creation and reconfiguration of a superblock is governed by a filesystem
65context. This is represented by the fs_context structure::
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;
81 unsigned int s_iflags;
82 enum fs_context_purpose purpose:8;
83 ...
84 };
85
86The fs_context fields are as follows:
87
88 * ::
89
90 const struct fs_context_operations *ops
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
96 * ::
97
98 struct file_system_type *fs_type
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
103 * ::
104
105 void *fs_private
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
110 * ::
111
112 struct dentry *root
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
118 * ::
119
120 struct user_namespace *user_ns
121 struct net *net_ns
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
128 * ::
129
130 const struct cred *cred
131
132 The mounter's credentials. This retains a reference on the credentials.
133
134 * ::
135
136 char *source
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
141 * ::
142
143 char *subtype
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
149 * ::
150
151 void *security
152
153 A place for the LSMs to hang their security data for the superblock. The
154 relevant security operations are described below.
155
156 * ::
157
158 void *s_fs_info
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
163 * ::
164
165 unsigned int sb_flags
166 unsigned int sb_flags_mask
167
168 Which bits SB_* flags are to be set/cleared in super_block::s_flags.
169
170 * ::
171
172 unsigned int s_iflags
173
174 These will be bitwise-OR'd with s->s_iflags when a superblock is created.
175
176 * ::
177
178 enum fs_context_purpose
179
180 This indicates the purpose for which the context is intended. The
181 available values are:
182
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 ========================== ======================================
188
189The mount context is created by calling vfs_new_fs_context() or
190vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the
191structure is not refcounted.
192
193VFS, security and filesystem mount options are set individually with
194vfs_parse_mount_option(). Options provided by the old mount(2) system call as
195a page of data can be parsed with generic_parse_monolithic().
196
197When mounting, the filesystem is allowed to take data from any of the pointers
198and attach it to the superblock (or whatever), provided it clears the pointer
199in the mount context.
200
201The filesystem is also allowed to allocate resources and pin them with the
202mount context. For instance, NFS might pin the appropriate protocol version
203module.
204
205
206The Filesystem Context Operations
207=================================
208
209The filesystem context points to a table of operations::
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,
215 struct fs_parameter *param);
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
221These operations are invoked by the various stages of the mount procedure to
222manage the filesystem context. They are as follows:
223
224 * ::
225
226 void (*free)(struct fs_context *fc);
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
232 * ::
233
234 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
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
240 .. Warning::
241
242 Note that even if this fails, put_fs_context() will be called
243 immediately thereafter, so ->dup() *must* make the
244 filesystem-private data safe for ->free().
245
246 * ::
247
248 int (*parse_param)(struct fs_context *fc,
249 struct fs_parameter *param);
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
261 * ::
262
263 int (*parse_monolithic)(struct fs_context *fc, void *data);
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
275 * ::
276
277 int (*get_tree)(struct fs_context *fc);
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
290 * ::
291
292 int (*reconfigure)(struct fs_context *fc);
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
302 .. Note:: reconfigure is intended as a replacement for remount_fs.
303
304
305Filesystem context Security
306===========================
307
308The filesystem context contains a security pointer that the LSMs can use for
309building up a security context for the superblock to be mounted. There are a
310number of operations used by the new mount code for this purpose:
311
312 * ::
313
314 int security_fs_context_alloc(struct fs_context *fc,
315 struct dentry *reference);
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
327 * ::
328
329 int security_fs_context_dup(struct fs_context *fc,
330 struct fs_context *src_fc);
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
337 * ::
338
339 void security_fs_context_free(struct fs_context *fc);
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
345 * ::
346
347 int security_fs_context_parse_param(struct fs_context *fc,
348 struct fs_parameter *param);
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
360 * ::
361
362 int security_fs_context_validate(struct fs_context *fc);
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
372 * ::
373
374 int security_sb_get_tree(struct fs_context *fc);
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
380 * ::
381
382 void security_sb_reconfigure(struct fs_context *fc);
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
388 * ::
389
390 int security_sb_mountpoint(struct fs_context *fc,
391 struct path *mountpoint,
392 unsigned int mnt_flags);
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
399VFS Filesystem context API
400==========================
401
402There are four operations for creating a filesystem context and one for
403destroying a context:
404
405 * ::
406
407 struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,
408 unsigned int sb_flags);
409
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.
414
415 fs_type specifies the filesystem type that will manage the context and
416 sb_flags presets the superblock flags stored therein.
417
418 * ::
419
420 struct fs_context *fs_context_for_reconfigure(
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
430 * ::
431
432 struct fs_context *fs_context_for_submount(
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.
444
445 * ::
446
447 struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);
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
457 * ::
458
459 void put_fs_context(struct fs_context *fc);
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
465 .. Warning::
466
467 filesystem contexts are not refcounted, so this causes unconditional
468 destruction.
469
470In all the above operations, apart from the put op, the return is a mount
471context pointer or a negative error code.
472
473For the remaining operations, if an error occurs, a negative error code will be
474returned.
475
476 * ::
477
478 int vfs_parse_fs_param(struct fs_context *fc,
479 struct fs_parameter *param);
480
481 Supply a single mount parameter to the filesystem context. This includes
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
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 ==================== =============================
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
507 * ::
508
509 int vfs_parse_fs_string(struct fs_context *fc, const char *key,
510 const char *value, size_t v_size);
511
512 A wrapper around vfs_parse_fs_param() that copies the value string it is
513 passed.
514
515 * ::
516
517 int generic_parse_monolithic(struct fs_context *fc, void *data);
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
522 ->parse_monolithic() method is NULL.
523
524 * ::
525
526 int vfs_get_tree(struct fs_context *fc);
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
532 * ::
533
534 struct vfsmount *vfs_create_mount(struct fs_context *fc);
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
540Superblock Creation Helpers
541===========================
542
543A number of VFS helpers are available for use by filesystems for the creation
544or looking up of superblocks.
545
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));
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
562The following helpers all wrap sget_fc():
563
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.
581
582
583Parameter Description
584=====================
585
586Parameters are described using structures defined in linux/fs_parser.h.
587There's a core description struct that links everything together::
588
589 struct fs_parameter_description {
590 const struct fs_parameter_spec *specs;
591 const struct fs_parameter_enum *enums;
592 };
593
594For example::
595
596 enum {
597 Opt_autocell,
598 Opt_bar,
599 Opt_dyn,
600 Opt_foo,
601 Opt_source,
602 };
603
604 static const struct fs_parameter_description afs_fs_parameters = {
605 .specs = afs_param_specs,
606 .enums = afs_param_enums,
607 };
608
609The members are as follows:
610
611 (1) ::
612
613 const struct fs_parameter_specification *specs;
614
615 Table of parameter specifications, terminated with a null entry, where the
616 entries are of type::
617
618 struct fs_parameter_spec {
619 const char *name;
620 u8 opt;
621 enum fs_parameter_type type:8;
622 unsigned short flags;
623 };
624
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:
631
632 ======================= ======================= =====================
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
641 fs_param_is_u64 64-bit unsigned int result->uint_64
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
647 fs_param_is_fd File descriptor result->int_32
648 fs_param_is_uid User ID (u32) result->uid
649 fs_param_is_gid Group ID (u32) result->gid
650 ======================= ======================= =====================
651
652 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", "no", "yes", "false", "true".
654
655 Each parameter can also be qualified with 'flags':
656
657 ======================= ================================================
658 fs_param_v_optional The value is optional
659 fs_param_neg_with_no result->negated set if key is prefixed with "no"
660 fs_param_neg_with_empty result->negated set if value is ""
661 fs_param_deprecated The parameter is deprecated.
662 ======================= ================================================
663
664 These are wrapped with a number of convenience wrappers:
665
666 ======================= ===============================================
667 MACRO SPECIFIES
668 ======================= ===============================================
669 fsparam_flag() fs_param_is_flag
670 fsparam_flag_no() fs_param_is_flag, fs_param_neg_with_no
671 fsparam_bool() fs_param_is_bool
672 fsparam_u32() fs_param_is_u32
673 fsparam_u32oct() fs_param_is_u32_octal
674 fsparam_u32hex() fs_param_is_u32_hex
675 fsparam_s32() fs_param_is_s32
676 fsparam_u64() fs_param_is_u64
677 fsparam_enum() fs_param_is_enum
678 fsparam_string() fs_param_is_string
679 fsparam_blob() fs_param_is_blob
680 fsparam_bdev() fs_param_is_blockdev
681 fsparam_path() fs_param_is_path
682 fsparam_fd() fs_param_is_fd
683 fsparam_uid() fs_param_is_uid
684 fsparam_gid() fs_param_is_gid
685 ======================= ===============================================
686
687 all of which take two arguments, name string and option number - for
688 example::
689
690 static const struct fs_parameter_spec afs_param_specs[] = {
691 fsparam_flag ("autocell", Opt_autocell),
692 fsparam_flag ("dyn", Opt_dyn),
693 fsparam_string ("source", Opt_source),
694 fsparam_flag_no ("foo", Opt_foo),
695 {}
696 };
697
698 An addition macro, __fsparam() is provided that takes an additional pair
699 of arguments to specify the type and the flags for anything that doesn't
700 match one of the above macros.
701
702 (2) ::
703
704 const struct fs_parameter_enum *enums;
705
706 Table of enum value names to integer mappings, terminated with a null
707 entry. This is of type::
708
709 struct fs_parameter_enum {
710 u8 opt;
711 char name[14];
712 u8 value;
713 };
714
715 Where the array is an unsorted list of { parameter ID, name }-keyed
716 elements that indicate the value to map to, e.g.::
717
718 static const struct fs_parameter_enum afs_param_enums[] = {
719 { Opt_bar, "x", 1},
720 { Opt_bar, "y", 23},
721 { Opt_bar, "z", 42},
722 };
723
724 If a parameter of type fs_param_is_enum is encountered, fs_parse() will
725 try to look the value up in the enum table and the result will be stored
726 in the parse result.
727
728The parser should be pointed to by the parser pointer in the file_system_type
729struct as this will provide validation on registration (if
730CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
731userspace using the fsinfo() syscall.
732
733
734Parameter Helper Functions
735==========================
736
737A number of helper functions are provided to help a filesystem or an LSM
738process the parameters it is given.
739
740 * ::
741
742 int lookup_constant(const struct constant_table tbl[],
743 const char *name, int not_found);
744
745 Look up a constant by name in a table of name -> integer mappings. The
746 table is an array of elements of the following type::
747
748 struct constant_table {
749 const char *name;
750 int value;
751 };
752
753 If a match is found, the corresponding value is returned. If a match
754 isn't found, the not_found value is returned instead.
755
756 * ::
757
758 bool validate_constant_table(const struct constant_table *tbl,
759 size_t tbl_size,
760 int low, int high, int special);
761
762 Validate a constant table. Checks that all the elements are appropriately
763 ordered, that there are no duplicates and that the values are between low
764 and high inclusive, though provision is made for one allowable special
765 value outside of that range. If no special value is required, special
766 should just be set to lie inside the low-to-high range.
767
768 If all is good, true is returned. If the table is invalid, errors are
769 logged to the kernel log buffer and false is returned.
770
771 * ::
772
773 bool fs_validate_description(const char *name,
774 const struct fs_parameter_description *desc);
775
776 This performs some validation checks on a parameter description. It
777 returns true if the description is good and false if it is not. It will
778 log errors to the kernel log buffer if validation fails.
779
780 * ::
781
782 int fs_parse(struct fs_context *fc,
783 const struct fs_parameter_description *desc,
784 struct fs_parameter *param,
785 struct fs_parse_result *result);
786
787 This is the main interpreter of parameters. It uses the parameter
788 description to look up a parameter by key name and to convert that to an
789 option number (which it returns).
790
791 If successful, and if the parameter type indicates the result is a
792 boolean, integer, enum, uid, or gid type, the value is converted by this
793 function and the result stored in
794 result->{boolean,int_32,uint_32,uint_64,uid,gid}.
795
796 If a match isn't initially made, the key is prefixed with "no" and no
797 value is present then an attempt will be made to look up the key with the
798 prefix removed. If this matches a parameter for which the type has flag
799 fs_param_neg_with_no set, then a match will be made and result->negated
800 will be set to true.
801
802 If the parameter isn't matched, -ENOPARAM will be returned; if the
803 parameter is matched, but the value is erroneous, -EINVAL will be
804 returned; otherwise the parameter's option number will be returned.
805
806 * ::
807
808 int fs_lookup_param(struct fs_context *fc,
809 struct fs_parameter *value,
810 bool want_bdev,
811 unsigned int flags,
812 struct path *_path);
813
814 This takes a parameter that carries a string or filename type and attempts
815 to do a path lookup on it. If the parameter expects a blockdev, a check
816 is made that the inode actually represents one.
817
818 Returns 0 if successful and ``*_path`` will be set; returns a negative
819 error code if not.
1.. SPDX-License-Identifier: GPL-2.0
2
3====================
4Filesystem Mount API
5====================
6
7.. CONTENTS
8
9 (1) Overview.
10
11 (2) The filesystem context.
12
13 (3) The filesystem context operations.
14
15 (4) Filesystem context security.
16
17 (5) VFS filesystem context API.
18
19 (6) Superblock creation helpers.
20
21 (7) Parameter description.
22
23 (8) Parameter helper functions.
24
25
26Overview
27========
28
29The 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
47To support this, the file_system_type struct gains two new fields::
48
49 int (*init_fs_context)(struct fs_context *fc);
50 const struct fs_parameter_description *parameters;
51
52The first is invoked to set up the filesystem-specific parts of a filesystem
53context, including the additional space, and the second points to the
54parameter description for validation at registration time and querying by a
55future system call.
56
57Note that security initialisation is done *after* the filesystem is called so
58that the namespaces may be adjusted first.
59
60
61The Filesystem context
62======================
63
64The creation and reconfiguration of a superblock is governed by a filesystem
65context. This is represented by the fs_context structure::
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;
81 unsigned int s_iflags;
82 unsigned int lsm_flags;
83 enum fs_context_purpose purpose:8;
84 ...
85 };
86
87The fs_context fields are as follows:
88
89 * ::
90
91 const struct fs_context_operations *ops
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
97 * ::
98
99 struct file_system_type *fs_type
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
104 * ::
105
106 void *fs_private
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
111 * ::
112
113 struct dentry *root
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
119 * ::
120
121 struct user_namespace *user_ns
122 struct net *net_ns
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
129 * ::
130
131 const struct cred *cred
132
133 The mounter's credentials. This retains a reference on the credentials.
134
135 * ::
136
137 char *source
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
142 * ::
143
144 char *subtype
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
150 * ::
151
152 void *security
153
154 A place for the LSMs to hang their security data for the superblock. The
155 relevant security operations are described below.
156
157 * ::
158
159 void *s_fs_info
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
164 * ::
165
166 unsigned int sb_flags
167 unsigned int sb_flags_mask
168
169 Which bits SB_* flags are to be set/cleared in super_block::s_flags.
170
171 * ::
172
173 unsigned int s_iflags
174
175 These will be bitwise-OR'd with s->s_iflags when a superblock is created.
176
177 * ::
178
179 enum fs_context_purpose
180
181 This indicates the purpose for which the context is intended. The
182 available values are:
183
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 ========================== ======================================
189
190The mount context is created by calling vfs_new_fs_context() or
191vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the
192structure is not refcounted.
193
194VFS, security and filesystem mount options are set individually with
195vfs_parse_mount_option(). Options provided by the old mount(2) system call as
196a page of data can be parsed with generic_parse_monolithic().
197
198When mounting, the filesystem is allowed to take data from any of the pointers
199and attach it to the superblock (or whatever), provided it clears the pointer
200in the mount context.
201
202The filesystem is also allowed to allocate resources and pin them with the
203mount context. For instance, NFS might pin the appropriate protocol version
204module.
205
206
207The Filesystem Context Operations
208=================================
209
210The filesystem context points to a table of operations::
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,
216 struct fs_parameter *param);
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
222These operations are invoked by the various stages of the mount procedure to
223manage the filesystem context. They are as follows:
224
225 * ::
226
227 void (*free)(struct fs_context *fc);
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
233 * ::
234
235 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
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
241 .. Warning::
242
243 Note that even if this fails, put_fs_context() will be called
244 immediately thereafter, so ->dup() *must* make the
245 filesystem-private data safe for ->free().
246
247 * ::
248
249 int (*parse_param)(struct fs_context *fc,
250 struct fs_parameter *param);
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
262 * ::
263
264 int (*parse_monolithic)(struct fs_context *fc, void *data);
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
276 * ::
277
278 int (*get_tree)(struct fs_context *fc);
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
291 * ::
292
293 int (*reconfigure)(struct fs_context *fc);
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
303 .. Note:: reconfigure is intended as a replacement for remount_fs.
304
305
306Filesystem context Security
307===========================
308
309The filesystem context contains a security pointer that the LSMs can use for
310building up a security context for the superblock to be mounted. There are a
311number of operations used by the new mount code for this purpose:
312
313 * ::
314
315 int security_fs_context_alloc(struct fs_context *fc,
316 struct dentry *reference);
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
328 * ::
329
330 int security_fs_context_dup(struct fs_context *fc,
331 struct fs_context *src_fc);
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
338 * ::
339
340 void security_fs_context_free(struct fs_context *fc);
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
346 * ::
347
348 int security_fs_context_parse_param(struct fs_context *fc,
349 struct fs_parameter *param);
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
361 * ::
362
363 int security_fs_context_validate(struct fs_context *fc);
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
373 * ::
374
375 int security_sb_get_tree(struct fs_context *fc);
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
381 * ::
382
383 void security_sb_reconfigure(struct fs_context *fc);
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
389 * ::
390
391 int security_sb_mountpoint(struct fs_context *fc,
392 struct path *mountpoint,
393 unsigned int mnt_flags);
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
400VFS Filesystem context API
401==========================
402
403There are four operations for creating a filesystem context and one for
404destroying a context:
405
406 * ::
407
408 struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,
409 unsigned int sb_flags);
410
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.
415
416 fs_type specifies the filesystem type that will manage the context and
417 sb_flags presets the superblock flags stored therein.
418
419 * ::
420
421 struct fs_context *fs_context_for_reconfigure(
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
431 * ::
432
433 struct fs_context *fs_context_for_submount(
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.
445
446 * ::
447
448 struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);
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
458 * ::
459
460 void put_fs_context(struct fs_context *fc);
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
466 .. Warning::
467
468 filesystem contexts are not refcounted, so this causes unconditional
469 destruction.
470
471In all the above operations, apart from the put op, the return is a mount
472context pointer or a negative error code.
473
474For the remaining operations, if an error occurs, a negative error code will be
475returned.
476
477 * ::
478
479 int vfs_parse_fs_param(struct fs_context *fc,
480 struct fs_parameter *param);
481
482 Supply a single mount parameter to the filesystem context. This includes
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
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 ==================== =============================
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
508 * ::
509
510 int vfs_parse_fs_string(struct fs_context *fc, const char *key,
511 const char *value, size_t v_size);
512
513 A wrapper around vfs_parse_fs_param() that copies the value string it is
514 passed.
515
516 * ::
517
518 int generic_parse_monolithic(struct fs_context *fc, void *data);
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
523 ->parse_monolithic() method is NULL.
524
525 * ::
526
527 int vfs_get_tree(struct fs_context *fc);
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
533 * ::
534
535 struct vfsmount *vfs_create_mount(struct fs_context *fc);
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
541Superblock Creation Helpers
542===========================
543
544A number of VFS helpers are available for use by filesystems for the creation
545or looking up of superblocks.
546
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));
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
563The following helpers all wrap sget_fc():
564
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))
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.
593
594
595Parameter Description
596=====================
597
598Parameters are described using structures defined in linux/fs_parser.h.
599There's a core description struct that links everything together::
600
601 struct fs_parameter_description {
602 const struct fs_parameter_spec *specs;
603 const struct fs_parameter_enum *enums;
604 };
605
606For example::
607
608 enum {
609 Opt_autocell,
610 Opt_bar,
611 Opt_dyn,
612 Opt_foo,
613 Opt_source,
614 };
615
616 static const struct fs_parameter_description afs_fs_parameters = {
617 .specs = afs_param_specs,
618 .enums = afs_param_enums,
619 };
620
621The members are as follows:
622
623 (1) ::
624
625 const struct fs_parameter_specification *specs;
626
627 Table of parameter specifications, terminated with a null entry, where the
628 entries are of type::
629
630 struct fs_parameter_spec {
631 const char *name;
632 u8 opt;
633 enum fs_parameter_type type:8;
634 unsigned short flags;
635 };
636
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:
643
644 ======================= ======================= =====================
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
653 fs_param_is_u64 64-bit unsigned int result->uint_64
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
659 fs_param_is_fd File descriptor result->int_32
660 ======================= ======================= =====================
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
665 Each parameter can also be qualified with 'flags':
666
667 ======================= ================================================
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.
672 ======================= ================================================
673
674 These are wrapped with a number of convenience wrappers:
675
676 ======================= ===============================================
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
693 ======================= ===============================================
694
695 all of which take two arguments, name string and option number - for
696 example::
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 {}
704 };
705
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.
709
710 (2) ::
711
712 const struct fs_parameter_enum *enums;
713
714 Table of enum value names to integer mappings, terminated with a null
715 entry. This is of type::
716
717 struct fs_parameter_enum {
718 u8 opt;
719 char name[14];
720 u8 value;
721 };
722
723 Where the array is an unsorted list of { parameter ID, name }-keyed
724 elements that indicate the value to map to, e.g.::
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
736The parser should be pointed to by the parser pointer in the file_system_type
737struct as this will provide validation on registration (if
738CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
739userspace using the fsinfo() syscall.
740
741
742Parameter Helper Functions
743==========================
744
745A number of helper functions are provided to help a filesystem or an LSM
746process the parameters it is given.
747
748 * ::
749
750 int lookup_constant(const struct constant_table tbl[],
751 const char *name, int not_found);
752
753 Look up a constant by name in a table of name -> integer mappings. The
754 table is an array of elements of the following type::
755
756 struct constant_table {
757 const char *name;
758 int value;
759 };
760
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.
763
764 * ::
765
766 bool validate_constant_table(const struct constant_table *tbl,
767 size_t tbl_size,
768 int low, int high, int special);
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
777 logged to the kernel log buffer and false is returned.
778
779 * ::
780
781 bool fs_validate_description(const struct fs_parameter_description *desc);
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
785 log errors to the kernel log buffer if validation fails.
786
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);
793
794 This is the main interpreter of parameters. It uses the parameter
795 description to look up a parameter by key name and to convert that to an
796 option number (which it returns).
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
800 the result stored in result->{boolean,int_32,uint_32,uint_64}.
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
805 fs_param_neg_with_no set, then a match will be made and result->negated
806 will be set to true.
807
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.
811
812 * ::
813
814 int fs_lookup_param(struct fs_context *fc,
815 struct fs_parameter *value,
816 bool want_bdev,
817 struct path *_path);
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
823 Returns 0 if successful and ``*_path`` will be set; returns a negative
824 error code if not.