Debian Codegraph @

upstream/debian-unstable/man2/fsopen.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fsopen 2 2025-12-25 "Linux man-pages 6.18"
6 .SH NAME
7 fsopen \- create a new filesystem context
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .B #include <sys/mount.h>
14 .P
15 .BI "int fsopen(const char *" fsname ", unsigned int " flags );
16 .fi
17 .SH DESCRIPTION
18 The
19 .BR fsopen ()
20 system call is part of
21 the suite of file-descriptor-based mount facilities in Linux.
22 .P
23 .BR fsopen ()
24 creates a blank filesystem configuration context within the kernel
25 for the filesystem named by
26 .I fsname
27 and places it into creation mode.
28 A new file descriptor
29 associated with the filesystem configuration context
30 is then returned.
31 The calling process must have the
32 .B \%CAP_SYS_ADMIN
33 capability in order to create a new filesystem configuration context.
34 .P
35 A filesystem configuration context is
36 an in-kernel representation of a pending transaction,
37 containing a set of configuration parameters that are to be applied
38 when creating a new instance of a filesystem
39 (or modifying the configuration of an existing filesystem instance,
40 such as when using
41 .BR fspick (2)).
42 .P
43 After obtaining a filesystem configuration context with
44 .BR fsopen (),
45 the general workflow for operating on the context looks like the following:
46 .IP (1) 5
47 Pass the filesystem context file descriptor to
48 .BR fsconfig (2)
49 to specify any desired filesystem parameters.
50 This may be done as many times as necessary.
51 .IP (2)
52 Pass the same filesystem context file descriptor to
53 .BR fsconfig (2)
54 with
55 .B \%FSCONFIG_CMD_CREATE
56 to create an instance of the configured filesystem.
57 .IP (3)
58 Pass the same filesystem context file descriptor to
59 .BR fsmount (2)
60 to create a new detached mount object for
61 the root of the filesystem instance,
62 which is then attached to a new file descriptor.
63 (This also places the filesystem context file descriptor into
64 reconfiguration mode,
65 similar to the mode produced by
66 .BR fspick (2).)
67 Once a mount object has been created with
68 .BR fsmount (2),
69 the filesystem context file descriptor can be safely closed.
70 .IP (4)
71 Now that a mount object has been created,
72 you may
73 .RS
74 .IP \[bu] 3
75 use the detached mount object file descriptor as a
76 .I dirfd
77 argument to "*at()" system calls;
78 and/or
79 .IP \[bu]
80 attach the mount object to a mount point
81 by passing the mount object file descriptor to
82 .BR move_mount (2).
83 This will also prevent the mount object from
84 being unmounted and destroyed when
85 the mount object file descriptor is closed.
86 .RE
87 .IP
88 The mount object file descriptor will
89 remain associated with the mount object
90 even after doing the above operations,
91 so you may repeatedly use the mount object file descriptor with
92 .BR move_mount (2)
93 and/or "*at()" system calls
94 as many times as necessary.
95 .P
96 A filesystem context will move between different modes
97 throughout its lifecycle
98 (such as the creation phase
99 when created with
100 .BR fsopen (),
101 the reconfiguration phase
102 when an existing filesystem instance is selected with
103 .BR fspick (2),
104 and the intermediate "awaiting-mount" phase
105 .\" FS_CONTEXT_AWAITING_MOUNT is the term the kernel uses for this.
106 between
107 .B \%FSCONFIG_CMD_CREATE
108 and
109 .BR fsmount (2)),
110 which has an impact on
111 what operations are permitted on the filesystem context.
112 .P
113 The file descriptor returned by
114 .BR fsopen ()
115 also acts as a channel for filesystem drivers to
116 provide more comprehensive diagnostic information
117 than is normally provided through the standard
118 .BR errno (3)
119 interface for system calls.
120 If an error occurs at any time during the workflow mentioned above,
121 calling
122 .BR read (2)
123 on the filesystem context file descriptor
124 will retrieve any ancillary information about the encountered errors.
125 (See the "Message retrieval interface" section
126 for more details on the message format.)
127 .P
128 .I flags
129 can be used to control aspects of
130 the creation of the filesystem configuration context file descriptor.
131 A value for
132 .I flags
133 is constructed by bitwise ORing
134 zero or more of the following constants:
135 .RS
136 .TP
137 .B FSOPEN_CLOEXEC
138 Set the close-on-exec
139 .RB ( FD_CLOEXEC )
140 flag on the new file descriptor.
141 See the description of the
142 .B O_CLOEXEC
143 flag in
144 .BR open (2)
145 for reasons why this may be useful.
146 .RE
147 .P
148 A list of filesystems supported by the running kernel
149 (and thus a list of valid values for
150 .IR fsname )
151 can be obtained from
152 .IR /proc/filesystems .
153 (See also
154 .BR proc_filesystems (5).)
155 .SS Message retrieval interface
156 When doing operations on a filesystem configuration context,
157 the filesystem driver may choose to provide
158 ancillary information to userspace
159 in the form of message strings.
160 .P
161 The filesystem context file descriptors returned by
162 .BR fsopen ()
163 and
164 .BR fspick (2)
165 may be queried for message strings at any time by calling
166 .BR read (2)
167 on the file descriptor.
168 Each call to
169 .BR read (2)
170 will return a single message,
171 prefixed to indicate its class:
172 .RS
173 .TP
174 .BI e\~ message
175 An error message was logged.
176 This is usually associated with an error being returned
177 from the corresponding system call which triggered this message.
178 .TP
179 .BI w\~ message
180 A warning message was logged.
181 .TP
182 .BI i\~ message
183 An informational message was logged.
184 .RE
185 .P
186 Messages are removed from the queue as they are read.
187 Note that the message queue has limited depth,
188 so it is possible for messages to get lost.
189 If there are no messages in the message queue,
190 .B read(2)
191 will return \-1 and
192 .I errno
193 will be set to
194 .BR \%ENODATA .
195 If the
196 .I buf
197 argument to
198 .BR read (2)
199 is not large enough to contain the entire message,
200 .BR read (2)
201 will return \-1 and
202 .I errno
203 will be set to
204 .BR \%EMSGSIZE .
205 (See BUGS.)
206 .P
207 If there are multiple filesystem contexts
208 referencing the same filesystem instance
209 (such as if you call
210 .BR fspick (2)
211 multiple times for the same mount),
212 each one gets its own independent message queue.
213 This does not apply to multiple file descriptors that are
214 tied to the same underlying open file description
215 (such as those created with
216 .BR dup (2)).
217 .P
218 Message strings will usually be prefixed by
219 the name of the filesystem or kernel subsystem
220 that logged the message,
221 though this may not always be the case.
222 See the Linux kernel source code for details.
223 .SH RETURN VALUE
224 On success, a new file descriptor is returned.
225 On error, \-1 is returned, and
226 .I errno
227 is set to indicate the error.
228 .SH ERRORS
229 .TP
230 .B EFAULT
231 .I fsname
232 is NULL
233 or a pointer to a location
234 outside the calling process's accessible address space.
235 .TP
236 .B EINVAL
237 .I flags
238 had an invalid flag set.
239 .TP
240 .B EMFILE
241 The calling process has too many open files to create more.
242 .TP
243 .B ENFILE
244 The system has too many open files to create more.
245 .TP
246 .B ENODEV
247 The filesystem named by
248 .I fsname
249 is not supported by the kernel.
250 .TP
251 .B ENOMEM
252 The kernel could not allocate sufficient memory to complete the operation.
253 .TP
254 .B EPERM
255 The calling process does not have the required
256 .B \%CAP_SYS_ADMIN
257 capability.
258 .SH STANDARDS
259 Linux.
260 .SH HISTORY
261 Linux 5.2.
262 .\" commit 24dcb3d90a1f67fe08c68a004af37df059d74005
263 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
264 glibc 2.36.
265 .SH BUGS
266 .SS Message retrieval interface and EMSGSIZE
267 As described in the "Message retrieval interface" subsection above,
268 calling
269 .BR read (2)
270 with too small a buffer to contain
271 the next pending message in the message queue
272 for the filesystem configuration context
273 will cause
274 .BR read (2)
275 to return \-1 and set
276 .BR errno (3)
277 to
278 .BR \%EMSGSIZE .
279 .P
280 However,
281 this failed operation still
282 consumes the message from the message queue.
283 This effectively discards the message silently,
284 as no data is copied into the
285 .BR read (2)
286 buffer.
287 .P
288 Programs should take care to ensure that
289 their buffers are sufficiently large
290 to contain any reasonable message string,
291 in order to avoid silently losing valuable diagnostic information.
292 .\" Aleksa Sarai
293 .\" This unfortunate behavior has existed since this feature was merged, but
294 .\" I have sent a patchset which will finally fix it.
295 .\" <https://lore.kernel.org/r/[email protected]/>
296 .SH EXAMPLES
297 To illustrate the workflow for creating a new mount,
298 the following is an example of how to mount an
299 .BR ext4 (5)
300 filesystem stored on
301 .I /dev/sdb1
302 onto
303 .IR /mnt .
304 .P
305 .in +4n
306 .EX
307 int fsfd, mntfd;
308 \&
309 fsfd = fsopen("ext4", FSOPEN_CLOEXEC);
310 fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
311 fsconfig(fsfd, FSCONFIG_SET_PATH, "source", "/dev/sdb1", AT_FDCWD);
312 fsconfig(fsfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0);
313 fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
314 fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
315 fsconfig(fsfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0)
316 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
317 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_RELATIME);
318 move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
319 .EE
320 .in
321 .P
322 First,
323 an ext4 configuration context is created and attached to the file descriptor
324 .IR fsfd .
325 Then, a series of parameters
326 (such as the source of the filesystem)
327 are provided using
328 .BR fsconfig (2),
329 followed by the filesystem instance being created with
330 .BR \%FSCONFIG_CMD_CREATE .
331 .BR fsmount (2)
332 is then used to create a new mount object attached to the file descriptor
333 .IR mntfd ,
334 which is then attached to the intended mount point using
335 .BR move_mount (2).
336 .P
337 The above procedure is functionally equivalent to
338 the following mount operation using
339 .BR mount (2):
340 .P
341 .in +4n
342 .EX
343 mount("/dev/sdb1", "/mnt", "ext4", MS_RELATIME,
344 "ro,noatime,acl,user_xattr,iversion");
345 .EE
346 .in
347 .P
348 And here's an example of creating a mount object
349 of an NFS server share
350 and setting a Smack security module label.
351 However, instead of attaching it to a mount point,
352 the program uses the mount object directly
353 to open a file from the NFS share.
354 .P
355 .in +4n
356 .EX
357 int fsfd, mntfd, fd;
358 \&
359 fsfd = fsopen("nfs", 0);
360 fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "example.com/pub", 0);
361 fsconfig(fsfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0);
362 fsconfig(fsfd, FSCONFIG_SET_STRING, "rsize", "65536", 0);
363 fsconfig(fsfd, FSCONFIG_SET_STRING, "wsize", "65536", 0);
364 fsconfig(fsfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0);
365 fsconfig(fsfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0);
366 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
367 mntfd = fsmount(fsfd, 0, MOUNT_ATTR_NODEV);
368 fd = openat(mntfd, "src/linux-5.2.tar.xz", O_RDONLY);
369 .EE
370 .in
371 .P
372 Unlike the previous example,
373 this operation has no trivial equivalent with
374 .BR mount (2),
375 as it was not previously possible to create a mount object
376 that is not attached to any mount point.
377 .SH SEE ALSO
378 .BR fsconfig (2),
379 .BR fsmount (2),
380 .BR fspick (2),
381 .BR mount (2),
382 .BR mount_setattr (2),
383 .BR move_mount (2),
384 .BR open_tree (2),
385 .BR mount_namespaces (7)