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