docs: filesystems: convert mount_api.txt to ReST

- Add a SPDX header; - Adjust document and section titles; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add table markups; - Add lists markups; - Add it to filesystems/index.rst.

Mauro Carvalho Chehab committed 6 years ago

Commit 791a17e1 parent a02dcdf4 files · +218 −116Browse files

Unified · Split

4 files

Documentation/filesystems/index.rst +1 −0
Documentation/filesystems/mount_api.rst +215 −114
include/linux/fs_context.h +1 −1
include/linux/lsm_hooks.h +1 −1

Documentation/filesystems/index.rst+1−0

@@ -30,6 +30,7 @@ algorithms work. · 29 unmodified lines
30	files	30	files
31	locks	31	locks
32	mandatory-locking	32	mandatory-locking
		33	mount_api
33		34
34	automount-support	35	automount-support
35		36

Documentation/filesystems/mount_api.rstrenamed from Documentation/filesystems/mount_api.txt+215−114

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

include/linux/fs_context.h+1−1

@@ -85,7 +85,7 @@ struct p_log { · 84 unmodified lines
85	* Superblock creation fills in ->root whereas reconfiguration begins with this	85	* Superblock creation fills in ->root whereas reconfiguration begins with this
86	* already set.	86	* already set.
87	*	87	*
88	* See Documentation/filesystems/mount_api.txt	88	* See Documentation/filesystems/mount_api.rst
89	*/	89	*/
90	struct fs_context {	90	struct fs_context {
91	const struct fs_context_operations *ops;	91	const struct fs_context_operations *ops;

include/linux/lsm_hooks.h+1−1

@@ -77,7 +77,7 @@ · 76 unmodified lines
77	* state. This is called immediately after commit_creds().	77	* state. This is called immediately after commit_creds().
78	*	78	*
79	* Security hooks for mount using fs_context.	79	* Security hooks for mount using fs_context.
80	* [See also Documentation/filesystems/mount_api.txt]	80	* [See also Documentation/filesystems/mount_api.rst]
81	*	81	*
82	* @fs_context_dup:	82	* @fs_context_dup:
83	* Allocate and attach a security structure to sc->security. This pointer	83	* Allocate and attach a security structure to sc->security. This pointer

docs: filesystems: convert mount_api.txt to ReST

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code