linux/Documentation/filesystems/mount_api.rst
<<
>>
Prefs
   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.
 825