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