mount_api.rst 27 KB

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