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