Debian Codegraph @

upstream/debian-unstable/man2/fsmount.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fsmount 2 2025-10-01 "Linux man-pages 6.18"
6 .SH NAME
7 fsmount \- instantiate mount object from 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 fsmount(int " fsfd ", unsigned int " flags \
16 ", unsigned int " attr_flags );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR fsmount ()
21 system call is part of
22 the suite of file-descriptor-based mount facilities in Linux.
23 .P
24 .BR fsmount ()
25 creates a new detached mount object
26 for the root of the new filesystem instance
27 referenced by the filesystem context file descriptor
28 .IR fsfd .
29 A new file descriptor
30 associated with the detached mount object
31 is then returned.
32 In order to create a mount object with
33 .BR fsmount (),
34 the calling process must have the
35 .B \%CAP_SYS_ADMIN
36 capability.
37 .P
38 The filesystem context must have been created with a call to
39 .BR fsopen (2)
40 and then had a filesystem instance instantiated with a call to
41 .BR fsconfig (2)
42 with
43 .B \%FSCONFIG_CMD_CREATE
44 or
45 .B \%FSCONFIG_CMD_CREATE_EXCL
46 in order to be in the correct state
47 for this operation
48 (the "awaiting-mount" mode in kernel-developer parlance).
49 .\" FS_CONTEXT_AWAITING_MOUNT is the term the kernel uses for this.
50 Unlike
51 .BR open_tree (2)
52 with
53 .BR \%OPEN_TREE_CLONE ,
54 .BR fsmount ()
55 can only be called once
56 in the lifetime of a filesystem context
57 to produce a mount object.
58 .P
59 As with file descriptors returned from
60 .BR open_tree (2)
61 called with
62 .BR OPEN_TREE_CLONE ,
63 the returned file descriptor
64 can then be used with
65 .BR move_mount (2),
66 .BR mount_setattr (2),
67 or other such system calls to do further mount operations.
68 This mount object will be unmounted and destroyed
69 when the file descriptor is closed
70 if it was not otherwise attached to a mount point
71 by calling
72 .BR move_mount (2).
73 (Note that the unmount operation on
74 .BR close (2)
75 is lazy\[em]akin to calling
76 .BR umount2 (2)
77 with
78 .BR MNT_DETACH ;
79 any existing open references to files
80 from the mount object
81 will continue to work,
82 and the mount object will only be completely destroyed
83 once it ceases to be busy.)
84 The returned file descriptor
85 also acts the same as one produced by
86 .BR open (2)
87 with
88 .BR O_PATH ,
89 meaning it can also be used as a
90 .I dirfd
91 argument
92 to "*at()" system calls.
93 .P
94 .I flags
95 controls the creation of the returned file descriptor.
96 A value for
97 .I flags
98 is constructed by bitwise ORing
99 zero or more of the following constants:
100 .RS
101 .TP
102 .B FSMOUNT_CLOEXEC
103 Set the close-on-exec
104 .RB ( FD_CLOEXEC )
105 flag on the new file descriptor.
106 See the description of the
107 .B O_CLOEXEC
108 flag in
109 .BR open (2)
110 for reasons why this may be useful.
111 .RE
112 .P
113 .I attr_flags
114 specifies mount attributes
115 which will be applied to the created mount object,
116 in the form of
117 .BI \%MOUNT_ATTR_ *
118 flags.
119 The flags are interpreted as though
120 .BR mount_setattr (2)
121 was called with
122 .I attr.attr_set
123 set to the same value as
124 .IR attr_flags .
125 .BI \%MOUNT_ATTR_ *
126 flags which would require
127 specifying additional fields in
128 .BR mount_attr (2type)
129 (such as
130 .BR \%MOUNT_ATTR_IDMAP )
131 are not valid flag values for
132 .IR attr_flags .
133 .P
134 If the
135 .BR fsmount ()
136 operation is successful,
137 the filesystem context
138 associated with the file descriptor
139 .I fsfd
140 is reset
141 and placed into reconfiguration mode,
142 as if it were just returned by
143 .BR fspick (2).
144 You may continue to use
145 .BR fsconfig (2)
146 with the now-reset filesystem context,
147 including issuing the
148 .B \%FSCONFIG_CMD_RECONFIGURE
149 command
150 to reconfigure the filesystem instance.
151 .SH RETURN VALUE
152 On success, a new file descriptor is returned.
153 On error, \-1 is returned, and
154 .I errno
155 is set to indicate the error.
156 .SH ERRORS
157 .TP
158 .B EBUSY
159 The filesystem context associated with
160 .I fsfd
161 is not in the right state
162 to be used by
163 .BR fsmount ().
164 .TP
165 .B EINVAL
166 .I flags
167 had an invalid flag set.
168 .TP
169 .B EINVAL
170 .I attr_flags
171 had an invalid
172 .BI MOUNT_ATTR_ *
173 flag set.
174 .TP
175 .B EMFILE
176 The calling process has too many open files to create more.
177 .TP
178 .B ENFILE
179 The system has too many open files to create more.
180 .TP
181 .B ENOSPC
182 The "anonymous" mount namespace
183 necessary to contain the new mount object
184 could not be allocated,
185 as doing so would exceed
186 the configured per-user limit on
187 the number of mount namespaces in the current user namespace.
188 (See also
189 .BR namespaces (7).)
190 .TP
191 .B ENOMEM
192 The kernel could not allocate sufficient memory to complete the operation.
193 .TP
194 .B EPERM
195 The calling process does not have the required
196 .B CAP_SYS_ADMIN
197 capability.
198 .SH STANDARDS
199 Linux.
200 .SH HISTORY
201 Linux 5.2.
202 .\" commit 93766fbd2696c2c4453dd8e1070977e9cd4e6b6d
203 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
204 glibc 2.36.
205 .SH EXAMPLES
206 .in +4n
207 .EX
208 int fsfd, mntfd, tmpfd;
209 \&
210 fsfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
211 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
212 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC,
213 MOUNT_ATTR_NODEV | MOUNT_ATTR_NOEXEC);
214 \&
215 /* Create a new file without attaching the mount object */
216 tmpfd = openat(mntfd, "tmpfile", O_CREAT | O_EXCL | O_RDWR, 0600);
217 unlinkat(mntfd, "tmpfile", 0);
218 \&
219 /* Attach the mount object to "/tmp" */
220 move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
221 .EE
222 .in
223 .SH SEE ALSO
224 .BR fsconfig (2),
225 .BR fsopen (2),
226 .BR fspick (2),
227 .BR mount (2),
228 .BR mount_setattr (2),
229 .BR move_mount (2),
230 .BR open_tree (2),
231 .BR mount_namespaces (7)