0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================
0004 Filesystem Mount API
0005 ====================
0006
0007 .. CONTENTS
0008
0009 (1) Overview.
0010
0011 (2) The filesystem context.
0012
0013 (3) The filesystem context operations.
0014
0015 (4) Filesystem context security.
0016
0017 (5) VFS filesystem context API.
0018
0019 (6) Superblock creation helpers.
0020
0021 (7) Parameter description.
0022
0023 (8) Parameter helper functions.
0024
0025
0026 Overview
0027 ========
0028
0029 The creation of new mounts is now to be done in a multistep process:
0030
0031 (1) Create a filesystem context.
0032
0033 (2) Parse the parameters and attach them to the context. Parameters are
0034 expected to be passed individually from userspace, though legacy binary
0035 parameters can also be handled.
0036
0037 (3) Validate and pre-process the context.
0038
0039 (4) Get or create a superblock and mountable root.
0040
0041 (5) Perform the mount.
0042
0043 (6) Return an error message attached to the context.
0044
0045 (7) Destroy the context.
0046
0047 To support this, the file_system_type struct gains two new fields::
0048
0049 int (*init_fs_context)(struct fs_context *fc);
0050 const struct fs_parameter_description *parameters;
0051
0052 The first is invoked to set up the filesystem-specific parts of a filesystem
0053 context, including the additional space, and the second points to the
0054 parameter description for validation at registration time and querying by a
0055 future system call.
0056
0057 Note that security initialisation is done *after* the filesystem is called so
0058 that the namespaces may be adjusted first.
0059
0060
0061 The Filesystem context
0062 ======================
0063
0064 The creation and reconfiguration of a superblock is governed by a filesystem
0065 context. This is represented by the fs_context structure::
0066
0067 struct fs_context {
0068 const struct fs_context_operations *ops;
0069 struct file_system_type *fs_type;
0070 void *fs_private;
0071 struct dentry *root;
0072 struct user_namespace *user_ns;
0073 struct net *net_ns;
0074 const struct cred *cred;
0075 char *source;
0076 char *subtype;
0077 void *security;
0078 void *s_fs_info;
0079 unsigned int sb_flags;
0080 unsigned int sb_flags_mask;
0081 unsigned int s_iflags;
0082 unsigned int lsm_flags;
0083 enum fs_context_purpose purpose:8;
0084 ...
0085 };
0086
0087 The fs_context fields are as follows:
0088
0089 * ::
0090
0091 const struct fs_context_operations *ops
0092
0093 These are operations that can be done on a filesystem context (see
0094 below). This must be set by the ->init_fs_context() file_system_type
0095 operation.
0096
0097 * ::
0098
0099 struct file_system_type *fs_type
0100
0101 A pointer to the file_system_type of the filesystem that is being
0102 constructed or reconfigured. This retains a reference on the type owner.
0103
0104 * ::
0105
0106 void *fs_private
0107
0108 A pointer to the file system's private data. This is where the filesystem
0109 will need to store any options it parses.
0110
0111 * ::
0112
0113 struct dentry *root
0114
0115 A pointer to the root of the mountable tree (and indirectly, the
0116 superblock thereof). This is filled in by the ->get_tree() op. If this
0117 is set, an active reference on root->d_sb must also be held.
0118
0119 * ::
0120
0121 struct user_namespace *user_ns
0122 struct net *net_ns
0123
0124 There are a subset of the namespaces in use by the invoking process. They
0125 retain references on each namespace. The subscribed namespaces may be
0126 replaced by the filesystem to reflect other sources, such as the parent
0127 mount superblock on an automount.
0128
0129 * ::
0130
0131 const struct cred *cred
0132
0133 The mounter's credentials. This retains a reference on the credentials.
0134
0135 * ::
0136
0137 char *source
0138
0139 This specifies the source. It may be a block device (e.g. /dev/sda1) or
0140 something more exotic, such as the "host:/path" that NFS desires.
0141
0142 * ::
0143
0144 char *subtype
0145
0146 This is a string to be added to the type displayed in /proc/mounts to
0147 qualify it (used by FUSE). This is available for the filesystem to set if
0148 desired.
0149
0150 * ::
0151
0152 void *security
0153
0154 A place for the LSMs to hang their security data for the superblock. The
0155 relevant security operations are described below.
0156
0157 * ::
0158
0159 void *s_fs_info
0160
0161 The proposed s_fs_info for a new superblock, set in the superblock by
0162 sget_fc(). This can be used to distinguish superblocks.
0163
0164 * ::
0165
0166 unsigned int sb_flags
0167 unsigned int sb_flags_mask
0168
0169 Which bits SB_* flags are to be set/cleared in super_block::s_flags.
0170
0171 * ::
0172
0173 unsigned int s_iflags
0174
0175 These will be bitwise-OR'd with s->s_iflags when a superblock is created.
0176
0177 * ::
0178
0179 enum fs_context_purpose
0180
0181 This indicates the purpose for which the context is intended. The
0182 available values are:
0183
0184 ========================== ======================================
0185 FS_CONTEXT_FOR_MOUNT, New superblock for explicit mount
0186 FS_CONTEXT_FOR_SUBMOUNT New automatic submount of extant mount
0187 FS_CONTEXT_FOR_RECONFIGURE Change an existing mount
0188 ========================== ======================================
0189
0190 The mount context is created by calling vfs_new_fs_context() or
0191 vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the
0192 structure is not refcounted.
0193
0194 VFS, security and filesystem mount options are set individually with
0195 vfs_parse_mount_option(). Options provided by the old mount(2) system call as
0196 a page of data can be parsed with generic_parse_monolithic().
0197
0198 When mounting, the filesystem is allowed to take data from any of the pointers
0199 and attach it to the superblock (or whatever), provided it clears the pointer
0200 in the mount context.
0201
0202 The filesystem is also allowed to allocate resources and pin them with the
0203 mount context. For instance, NFS might pin the appropriate protocol version
0204 module.
0205
0206
0207 The Filesystem Context Operations
0208 =================================
0209
0210 The filesystem context points to a table of operations::
0211
0212 struct fs_context_operations {
0213 void (*free)(struct fs_context *fc);
0214 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
0215 int (*parse_param)(struct fs_context *fc,
0216 struct fs_parameter *param);
0217 int (*parse_monolithic)(struct fs_context *fc, void *data);
0218 int (*get_tree)(struct fs_context *fc);
0219 int (*reconfigure)(struct fs_context *fc);
0220 };
0221
0222 These operations are invoked by the various stages of the mount procedure to
0223 manage the filesystem context. They are as follows:
0224
0225 * ::
0226
0227 void (*free)(struct fs_context *fc);
0228
0229 Called to clean up the filesystem-specific part of the filesystem context
0230 when the context is destroyed. It should be aware that parts of the
0231 context may have been removed and NULL'd out by ->get_tree().
0232
0233 * ::
0234
0235 int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
0236
0237 Called when a filesystem context has been duplicated to duplicate the
0238 filesystem-private data. An error may be returned to indicate failure to
0239 do this.
0240
0241 .. Warning::
0242
0243 Note that even if this fails, put_fs_context() will be called
0244 immediately thereafter, so ->dup() *must* make the
0245 filesystem-private data safe for ->free().
0246
0247 * ::
0248
0249 int (*parse_param)(struct fs_context *fc,
0250 struct fs_parameter *param);
0251
0252 Called when a parameter is being added to the filesystem context. param
0253 points to the key name and maybe a value object. VFS-specific options
0254 will have been weeded out and fc->sb_flags updated in the context.
0255 Security options will also have been weeded out and fc->security updated.
0256
0257 The parameter can be parsed with fs_parse() and fs_lookup_param(). Note
0258 that the source(s) are presented as parameters named "source".
0259
0260 If successful, 0 should be returned or a negative error code otherwise.
0261
0262 * ::
0263
0264 int (*parse_monolithic)(struct fs_context *fc, void *data);
0265
0266 Called when the mount(2) system call is invoked to pass the entire data
0267 page in one go. If this is expected to be just a list of "key[=val]"
0268 items separated by commas, then this may be set to NULL.
0269
0270 The return value is as for ->parse_param().
0271
0272 If the filesystem (e.g. NFS) needs to examine the data first and then
0273 finds it's the standard key-val list then it may pass it off to
0274 generic_parse_monolithic().
0275
0276 * ::
0277
0278 int (*get_tree)(struct fs_context *fc);
0279
0280 Called to get or create the mountable root and superblock, using the
0281 information stored in the filesystem context (reconfiguration goes via a
0282 different vector). It may detach any resources it desires from the
0283 filesystem context and transfer them to the superblock it creates.
0284
0285 On success it should set fc->root to the mountable root and return 0. In
0286 the case of an error, it should return a negative error code.
0287
0288 The phase on a userspace-driven context will be set to only allow this to
0289 be called once on any particular context.
0290
0291 * ::
0292
0293 int (*reconfigure)(struct fs_context *fc);
0294
0295 Called to effect reconfiguration of a superblock using information stored
0296 in the filesystem context. It may detach any resources it desires from
0297 the filesystem context and transfer them to the superblock. The
0298 superblock can be found from fc->root->d_sb.
0299
0300 On success it should return 0. In the case of an error, it should return
0301 a negative error code.
0302
0303 .. Note:: reconfigure is intended as a replacement for remount_fs.
0304
0305
0306 Filesystem context Security
0307 ===========================
0308
0309 The filesystem context contains a security pointer that the LSMs can use for
0310 building up a security context for the superblock to be mounted. There are a
0311 number of operations used by the new mount code for this purpose:
0312
0313 * ::
0314
0315 int security_fs_context_alloc(struct fs_context *fc,
0316 struct dentry *reference);
0317
0318 Called to initialise fc->security (which is preset to NULL) and allocate
0319 any resources needed. It should return 0 on success or a negative error
0320 code on failure.
0321
0322 reference will be non-NULL if the context is being created for superblock
0323 reconfiguration (FS_CONTEXT_FOR_RECONFIGURE) in which case it indicates
0324 the root dentry of the superblock to be reconfigured. It will also be
0325 non-NULL in the case of a submount (FS_CONTEXT_FOR_SUBMOUNT) in which case
0326 it indicates the automount point.
0327
0328 * ::
0329
0330 int security_fs_context_dup(struct fs_context *fc,
0331 struct fs_context *src_fc);
0332
0333 Called to initialise fc->security (which is preset to NULL) and allocate
0334 any resources needed. The original filesystem context is pointed to by
0335 src_fc and may be used for reference. It should return 0 on success or a
0336 negative error code on failure.
0337
0338 * ::
0339
0340 void security_fs_context_free(struct fs_context *fc);
0341
0342 Called to clean up anything attached to fc->security. Note that the
0343 contents may have been transferred to a superblock and the pointer cleared
0344 during get_tree.
0345
0346 * ::
0347
0348 int security_fs_context_parse_param(struct fs_context *fc,
0349 struct fs_parameter *param);
0350
0351 Called for each mount parameter, including the source. The arguments are
0352 as for the ->parse_param() method. It should return 0 to indicate that
0353 the parameter should be passed on to the filesystem, 1 to indicate that
0354 the parameter should be discarded or an error to indicate that the
0355 parameter should be rejected.
0356
0357 The value pointed to by param may be modified (if a string) or stolen
0358 (provided the value pointer is NULL'd out). If it is stolen, 1 must be
0359 returned to prevent it being passed to the filesystem.
0360
0361 * ::
0362
0363 int security_fs_context_validate(struct fs_context *fc);
0364
0365 Called after all the options have been parsed to validate the collection
0366 as a whole and to do any necessary allocation so that
0367 security_sb_get_tree() and security_sb_reconfigure() are less likely to
0368 fail. It should return 0 or a negative error code.
0369
0370 In the case of reconfiguration, the target superblock will be accessible
0371 via fc->root.
0372
0373 * ::
0374
0375 int security_sb_get_tree(struct fs_context *fc);
0376
0377 Called during the mount procedure to verify that the specified superblock
0378 is allowed to be mounted and to transfer the security data there. It
0379 should return 0 or a negative error code.
0380
0381 * ::
0382
0383 void security_sb_reconfigure(struct fs_context *fc);
0384
0385 Called to apply any reconfiguration to an LSM's context. It must not
0386 fail. Error checking and resource allocation must be done in advance by
0387 the parameter parsing and validation hooks.
0388
0389 * ::
0390
0391 int security_sb_mountpoint(struct fs_context *fc,
0392 struct path *mountpoint,
0393 unsigned int mnt_flags);
0394
0395 Called during the mount procedure to verify that the root dentry attached
0396 to the context is permitted to be attached to the specified mountpoint.
0397 It should return 0 on success or a negative error code on failure.
0398
0399
0400 VFS Filesystem context API
0401 ==========================
0402
0403 There are four operations for creating a filesystem context and one for
0404 destroying a context:
0405
0406 * ::
0407
0408 struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,
0409 unsigned int sb_flags);
0410
0411 Allocate a filesystem context for the purpose of setting up a new mount,
0412 whether that be with a new superblock or sharing an existing one. This
0413 sets the superblock flags, initialises the security and calls
0414 fs_type->init_fs_context() to initialise the filesystem private data.
0415
0416 fs_type specifies the filesystem type that will manage the context and
0417 sb_flags presets the superblock flags stored therein.
0418
0419 * ::
0420
0421 struct fs_context *fs_context_for_reconfigure(
0422 struct dentry *dentry,
0423 unsigned int sb_flags,
0424 unsigned int sb_flags_mask);
0425
0426 Allocate a filesystem context for the purpose of reconfiguring an
0427 existing superblock. dentry provides a reference to the superblock to be
0428 configured. sb_flags and sb_flags_mask indicate which superblock flags
0429 need changing and to what.
0430
0431 * ::
0432
0433 struct fs_context *fs_context_for_submount(
0434 struct file_system_type *fs_type,
0435 struct dentry *reference);
0436
0437 Allocate a filesystem context for the purpose of creating a new mount for
0438 an automount point or other derived superblock. fs_type specifies the
0439 filesystem type that will manage the context and the reference dentry
0440 supplies the parameters. Namespaces are propagated from the reference
0441 dentry's superblock also.
0442
0443 Note that it's not a requirement that the reference dentry be of the same
0444 filesystem type as fs_type.
0445
0446 * ::
0447
0448 struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);
0449
0450 Duplicate a filesystem context, copying any options noted and duplicating
0451 or additionally referencing any resources held therein. This is available
0452 for use where a filesystem has to get a mount within a mount, such as NFS4
0453 does by internally mounting the root of the target server and then doing a
0454 private pathwalk to the target directory.
0455
0456 The purpose in the new context is inherited from the old one.
0457
0458 * ::
0459
0460 void put_fs_context(struct fs_context *fc);
0461
0462 Destroy a filesystem context, releasing any resources it holds. This
0463 calls the ->free() operation. This is intended to be called by anyone who
0464 created a filesystem context.
0465
0466 .. Warning::
0467
0468 filesystem contexts are not refcounted, so this causes unconditional
0469 destruction.
0470
0471 In all the above operations, apart from the put op, the return is a mount
0472 context pointer or a negative error code.
0473
0474 For the remaining operations, if an error occurs, a negative error code will be
0475 returned.
0476
0477 * ::
0478
0479 int vfs_parse_fs_param(struct fs_context *fc,
0480 struct fs_parameter *param);
0481
0482 Supply a single mount parameter to the filesystem context. This includes
0483 the specification of the source/device which is specified as the "source"
0484 parameter (which may be specified multiple times if the filesystem
0485 supports that).
0486
0487 param specifies the parameter key name and the value. The parameter is
0488 first checked to see if it corresponds to a standard mount flag (in which
0489 case it is used to set an SB_xxx flag and consumed) or a security option
0490 (in which case the LSM consumes it) before it is passed on to the
0491 filesystem.
0492
0493 The parameter value is typed and can be one of:
0494
0495 ==================== =============================
0496 fs_value_is_flag Parameter not given a value
0497 fs_value_is_string Value is a string
0498 fs_value_is_blob Value is a binary blob
0499 fs_value_is_filename Value is a filename* + dirfd
0500 fs_value_is_file Value is an open file (file*)
0501 ==================== =============================
0502
0503 If there is a value, that value is stored in a union in the struct in one
0504 of param->{string,blob,name,file}. Note that the function may steal and
0505 clear the pointer, but then becomes responsible for disposing of the
0506 object.
0507
0508 * ::
0509
0510 int vfs_parse_fs_string(struct fs_context *fc, const char *key,
0511 const char *value, size_t v_size);
0512
0513 A wrapper around vfs_parse_fs_param() that copies the value string it is
0514 passed.
0515
0516 * ::
0517
0518 int generic_parse_monolithic(struct fs_context *fc, void *data);
0519
0520 Parse a sys_mount() data page, assuming the form to be a text list
0521 consisting of key[=val] options separated by commas. Each item in the
0522 list is passed to vfs_mount_option(). This is the default when the
0523 ->parse_monolithic() method is NULL.
0524
0525 * ::
0526
0527 int vfs_get_tree(struct fs_context *fc);
0528
0529 Get or create the mountable root and superblock, using the parameters in
0530 the filesystem context to select/configure the superblock. This invokes
0531 the ->get_tree() method.
0532
0533 * ::
0534
0535 struct vfsmount *vfs_create_mount(struct fs_context *fc);
0536
0537 Create a mount given the parameters in the specified filesystem context.
0538 Note that this does not attach the mount to anything.
0539
0540
0541 Superblock Creation Helpers
0542 ===========================
0543
0544 A number of VFS helpers are available for use by filesystems for the creation
0545 or looking up of superblocks.
0546
0547 * ::
0548
0549 struct super_block *
0550 sget_fc(struct fs_context *fc,
0551 int (*test)(struct super_block *sb, struct fs_context *fc),
0552 int (*set)(struct super_block *sb, struct fs_context *fc));
0553
0554 This is the core routine. If test is non-NULL, it searches for an
0555 existing superblock matching the criteria held in the fs_context, using
0556 the test function to match them. If no match is found, a new superblock
0557 is created and the set function is called to set it up.
0558
0559 Prior to the set function being called, fc->s_fs_info will be transferred
0560 to sb->s_fs_info - and fc->s_fs_info will be cleared if set returns
0561 success (ie. 0).
0562
0563 The following helpers all wrap sget_fc():
0564
0565 * ::
0566
0567 int vfs_get_super(struct fs_context *fc,
0568 enum vfs_get_super_keying keying,
0569 int (*fill_super)(struct super_block *sb,
0570 struct fs_context *fc))
0571
0572 This creates/looks up a deviceless superblock. The keying indicates how
0573 many superblocks of this type may exist and in what manner they may be
0574 shared:
0575
0576 (1) vfs_get_single_super
0577
0578 Only one such superblock may exist in the system. Any further
0579 attempt to get a new superblock gets this one (and any parameter
0580 differences are ignored).
0581
0582 (2) vfs_get_keyed_super
0583
0584 Multiple superblocks of this type may exist and they're keyed on
0585 their s_fs_info pointer (for example this may refer to a
0586 namespace).
0587
0588 (3) vfs_get_independent_super
0589
0590 Multiple independent superblocks of this type may exist. This
0591 function never matches an existing one and always creates a new
0592 one.
0593
0594
0595 Parameter Description
0596 =====================
0597
0598 Parameters are described using structures defined in linux/fs_parser.h.
0599 There's a core description struct that links everything together::
0600
0601 struct fs_parameter_description {
0602 const struct fs_parameter_spec *specs;
0603 const struct fs_parameter_enum *enums;
0604 };
0605
0606 For example::
0607
0608 enum {
0609 Opt_autocell,
0610 Opt_bar,
0611 Opt_dyn,
0612 Opt_foo,
0613 Opt_source,
0614 };
0615
0616 static const struct fs_parameter_description afs_fs_parameters = {
0617 .specs = afs_param_specs,
0618 .enums = afs_param_enums,
0619 };
0620
0621 The members are as follows:
0622
0623 (1) ::
0624
0625 const struct fs_parameter_specification *specs;
0626
0627 Table of parameter specifications, terminated with a null entry, where the
0628 entries are of type::
0629
0630 struct fs_parameter_spec {
0631 const char *name;
0632 u8 opt;
0633 enum fs_parameter_type type:8;
0634 unsigned short flags;
0635 };
0636
0637 The 'name' field is a string to match exactly to the parameter key (no
0638 wildcards, patterns and no case-independence) and 'opt' is the value that
0639 will be returned by the fs_parser() function in the case of a successful
0640 match.
0641
0642 The 'type' field indicates the desired value type and must be one of:
0643
0644 ======================= ======================= =====================
0645 TYPE NAME EXPECTED VALUE RESULT IN
0646 ======================= ======================= =====================
0647 fs_param_is_flag No value n/a
0648 fs_param_is_bool Boolean value result->boolean
0649 fs_param_is_u32 32-bit unsigned int result->uint_32
0650 fs_param_is_u32_octal 32-bit octal int result->uint_32
0651 fs_param_is_u32_hex 32-bit hex int result->uint_32
0652 fs_param_is_s32 32-bit signed int result->int_32
0653 fs_param_is_u64 64-bit unsigned int result->uint_64
0654 fs_param_is_enum Enum value name result->uint_32
0655 fs_param_is_string Arbitrary string param->string
0656 fs_param_is_blob Binary blob param->blob
0657 fs_param_is_blockdev Blockdev path * Needs lookup
0658 fs_param_is_path Path * Needs lookup
0659 fs_param_is_fd File descriptor result->int_32
0660 ======================= ======================= =====================
0661
0662 Note that if the value is of fs_param_is_bool type, fs_parse() will try
0663 to match any string value against "0", "1", "no", "yes", "false", "true".
0664
0665 Each parameter can also be qualified with 'flags':
0666
0667 ======================= ================================================
0668 fs_param_v_optional The value is optional
0669 fs_param_neg_with_no result->negated set if key is prefixed with "no"
0670 fs_param_neg_with_empty result->negated set if value is ""
0671 fs_param_deprecated The parameter is deprecated.
0672 ======================= ================================================
0673
0674 These are wrapped with a number of convenience wrappers:
0675
0676 ======================= ===============================================
0677 MACRO SPECIFIES
0678 ======================= ===============================================
0679 fsparam_flag() fs_param_is_flag
0680 fsparam_flag_no() fs_param_is_flag, fs_param_neg_with_no
0681 fsparam_bool() fs_param_is_bool
0682 fsparam_u32() fs_param_is_u32
0683 fsparam_u32oct() fs_param_is_u32_octal
0684 fsparam_u32hex() fs_param_is_u32_hex
0685 fsparam_s32() fs_param_is_s32
0686 fsparam_u64() fs_param_is_u64
0687 fsparam_enum() fs_param_is_enum
0688 fsparam_string() fs_param_is_string
0689 fsparam_blob() fs_param_is_blob
0690 fsparam_bdev() fs_param_is_blockdev
0691 fsparam_path() fs_param_is_path
0692 fsparam_fd() fs_param_is_fd
0693 ======================= ===============================================
0694
0695 all of which take two arguments, name string and option number - for
0696 example::
0697
0698 static const struct fs_parameter_spec afs_param_specs[] = {
0699 fsparam_flag ("autocell", Opt_autocell),
0700 fsparam_flag ("dyn", Opt_dyn),
0701 fsparam_string ("source", Opt_source),
0702 fsparam_flag_no ("foo", Opt_foo),
0703 {}
0704 };
0705
0706 An addition macro, __fsparam() is provided that takes an additional pair
0707 of arguments to specify the type and the flags for anything that doesn't
0708 match one of the above macros.
0709
0710 (2) ::
0711
0712 const struct fs_parameter_enum *enums;
0713
0714 Table of enum value names to integer mappings, terminated with a null
0715 entry. This is of type::
0716
0717 struct fs_parameter_enum {
0718 u8 opt;
0719 char name[14];
0720 u8 value;
0721 };
0722
0723 Where the array is an unsorted list of { parameter ID, name }-keyed
0724 elements that indicate the value to map to, e.g.::
0725
0726 static const struct fs_parameter_enum afs_param_enums[] = {
0727 { Opt_bar, "x", 1},
0728 { Opt_bar, "y", 23},
0729 { Opt_bar, "z", 42},
0730 };
0731
0732 If a parameter of type fs_param_is_enum is encountered, fs_parse() will
0733 try to look the value up in the enum table and the result will be stored
0734 in the parse result.
0735
0736 The parser should be pointed to by the parser pointer in the file_system_type
0737 struct as this will provide validation on registration (if
0738 CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
0739 userspace using the fsinfo() syscall.
0740
0741
0742 Parameter Helper Functions
0743 ==========================
0744
0745 A number of helper functions are provided to help a filesystem or an LSM
0746 process the parameters it is given.
0747
0748 * ::
0749
0750 int lookup_constant(const struct constant_table tbl[],
0751 const char *name, int not_found);
0752
0753 Look up a constant by name in a table of name -> integer mappings. The
0754 table is an array of elements of the following type::
0755
0756 struct constant_table {
0757 const char *name;
0758 int value;
0759 };
0760
0761 If a match is found, the corresponding value is returned. If a match
0762 isn't found, the not_found value is returned instead.
0763
0764 * ::
0765
0766 bool validate_constant_table(const struct constant_table *tbl,
0767 size_t tbl_size,
0768 int low, int high, int special);
0769
0770 Validate a constant table. Checks that all the elements are appropriately
0771 ordered, that there are no duplicates and that the values are between low
0772 and high inclusive, though provision is made for one allowable special
0773 value outside of that range. If no special value is required, special
0774 should just be set to lie inside the low-to-high range.
0775
0776 If all is good, true is returned. If the table is invalid, errors are
0777 logged to the kernel log buffer and false is returned.
0778
0779 * ::
0780
0781 bool fs_validate_description(const struct fs_parameter_description *desc);
0782
0783 This performs some validation checks on a parameter description. It
0784 returns true if the description is good and false if it is not. It will
0785 log errors to the kernel log buffer if validation fails.
0786
0787 * ::
0788
0789 int fs_parse(struct fs_context *fc,
0790 const struct fs_parameter_description *desc,
0791 struct fs_parameter *param,
0792 struct fs_parse_result *result);
0793
0794 This is the main interpreter of parameters. It uses the parameter
0795 description to look up a parameter by key name and to convert that to an
0796 option number (which it returns).
0797
0798 If successful, and if the parameter type indicates the result is a
0799 boolean, integer or enum type, the value is converted by this function and
0800 the result stored in result->{boolean,int_32,uint_32,uint_64}.
0801
0802 If a match isn't initially made, the key is prefixed with "no" and no
0803 value is present then an attempt will be made to look up the key with the
0804 prefix removed. If this matches a parameter for which the type has flag
0805 fs_param_neg_with_no set, then a match will be made and result->negated
0806 will be set to true.
0807
0808 If the parameter isn't matched, -ENOPARAM will be returned; if the
0809 parameter is matched, but the value is erroneous, -EINVAL will be
0810 returned; otherwise the parameter's option number will be returned.
0811
0812 * ::
0813
0814 int fs_lookup_param(struct fs_context *fc,
0815 struct fs_parameter *value,
0816 bool want_bdev,
0817 struct path *_path);
0818
0819 This takes a parameter that carries a string or filename type and attempts
0820 to do a path lookup on it. If the parameter expects a blockdev, a check
0821 is made that the inode actually represents one.
0822
0823 Returns 0 if successful and ``*_path`` will be set; returns a negative
0824 error code if not.
