Debian Codegraph @

upstream/debian-unstable/man2/fspick.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fspick 2 2025-12-25 "Linux man-pages 6.18"
6 .SH NAME
7 fspick \- select filesystem for reconfiguration
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
14 .B #include <sys/mount.h>
15 .P
16 .BI "int fspick(int " dirfd ", const char *" path ", unsigned int " flags );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR fspick ()
21 system call is part of
22 the suite of file-descriptor-based mount facilities in Linux.
23 .P
24 .BR fspick ()
25 creates a new filesystem configuration context
26 for the extant filesystem instance
27 associated with the path described by
28 .I dirfd
29 and
30 .IR path ,
31 places it into reconfiguration mode
32 (similar to
33 .BR mount (8)
34 with the
35 .B \-o\~remount
36 option).
37 A new file descriptor
38 associated with the filesystem configuration context
39 is then returned.
40 The calling process must have the
41 .B \%CAP_SYS_ADMIN
42 capability in order to create a new filesystem configuration context.
43 .P
44 The resultant file descriptor can be used with
45 .BR fsconfig (2)
46 to specify the desired set of changes to
47 filesystem parameters of the filesystem instance.
48 Once the desired set of changes have been configured,
49 the changes can be effectuated by calling
50 .BR fsconfig (2)
51 with the
52 .B \%FSCONFIG_CMD_RECONFIGURE
53 command.
54 In contrast to
55 the behavior of
56 .B MS_REMOUNT
57 with
58 .BR mount (2),
59 .BR fspick ()
60 instantiates the filesystem configuration context
61 with a copy of
62 the extant filesystem's filesystem parameters;
63 thus,
64 subsequent
65 .B \%FSCONFIG_CMD_RECONFIGURE
66 operations
67 will only update filesystem parameters
68 explicitly modified with
69 .BR fsconfig (2).
70 .P
71 As with "*at()" system calls,
72 .BR fspick ()
73 uses the
74 .I dirfd
75 argument in conjunction with the
76 .I path
77 argument to determine the path to operate on, as follows:
78 .IP \[bu] 3
79 If the pathname given in
80 .I path
81 is absolute, then
82 .I dirfd
83 is ignored.
84 .IP \[bu]
85 If the pathname given in
86 .I path
87 is relative and
88 .I dirfd
89 is the special value
90 .BR \%AT_FDCWD ,
91 then
92 .I path
93 is interpreted relative to
94 the current working directory
95 of the calling process (like
96 .BR open (2)).
97 .IP \[bu]
98 If the pathname given in
99 .I path
100 is relative,
101 then it is interpreted relative to
102 the directory referred to by the file descriptor
103 .I dirfd
104 (rather than relative to
105 the current working directory
106 of the calling process,
107 as is done by
108 .BR open (2)
109 for a relative pathname).
110 In this case,
111 .I dirfd
112 must be a directory
113 that was opened for reading
114 .RB ( O_RDONLY )
115 or using the
116 .B O_PATH
117 flag.
118 .IP \[bu]
119 If
120 .I path
121 is an empty string,
122 and
123 .I flags
124 contains
125 .BR \%FSPICK_EMPTY_PATH ,
126 then the file descriptor
127 .I dirfd
128 is operated on directly.
129 In this case,
130 .I dirfd
131 may refer to any type of file,
132 not just a directory.
133 .P
134 See
135 .BR openat (2)
136 for an explanation of why the
137 .I dirfd
138 argument is useful.
139 .P
140 .I flags
141 can be used to control aspects of how
142 .I path
143 is resolved and
144 properties of the returned file descriptor.
145 A value for
146 .I flags
147 is constructed by bitwise ORing
148 zero or more of the following constants:
149 .RS
150 .TP
151 .B FSPICK_CLOEXEC
152 Set the close-on-exec
153 .RB ( FD_CLOEXEC )
154 flag on the new file descriptor.
155 See the description of the
156 .B O_CLOEXEC
157 flag in
158 .BR open (2)
159 for reasons why this may be useful.
160 .TP
161 .B FSPICK_EMPTY_PATH
162 If
163 .I path
164 is an empty string,
165 operate on the file referred to by
166 .I dirfd
167 (which may have been obtained from
168 .BR open (2),
169 .BR fsmount (2),
170 or
171 .BR open_tree (2)).
172 In this case,
173 .I dirfd
174 may refer to any type of file,
175 not just a directory.
176 If
177 .I dirfd
178 is
179 .BR \%AT_FDCWD ,
180 .BR fspick ()
181 will operate on the current working directory
182 of the calling process.
183 .TP
184 .B FSPICK_SYMLINK_NOFOLLOW
185 Do not follow symbolic links
186 in the terminal component of
187 .IR path .
188 If
189 .I path
190 references a symbolic link,
191 the returned filesystem context will reference
192 the filesystem that the symbolic link itself resides on.
193 .TP
194 .B FSPICK_NO_AUTOMOUNT
195 Do not automount the terminal ("basename") component of
196 .I path
197 if it is a directory that is an automount point.
198 This allows you to reconfigure an automount point,
199 rather than the location that would be mounted.
200 This flag has no effect
201 if the automount point has already been mounted over.
202 .RE
203 .P
204 As with filesystem contexts created with
205 .BR fsopen (2),
206 the file descriptor returned by
207 .BR fspick ()
208 may be queried for message strings at any time by calling
209 .BR read (2)
210 on the file descriptor.
211 (See the "Message retrieval interface" subsection in
212 .BR fsopen (2)
213 for more details on the message format.)
214 .SH RETURN VALUE
215 On success, a new file descriptor is returned.
216 On error, \-1 is returned, and
217 .I errno
218 is set to indicate the error.
219 .SH ERRORS
220 .TP
221 .B EACCES
222 Search permission is denied
223 for one of the directories
224 in the path prefix of
225 .IR path .
226 (See also
227 .BR path_resolution (7).)
228 .TP
229 .B EBADF
230 .I path
231 is relative but
232 .I dirfd
233 is neither
234 .B \%AT_FDCWD
235 nor a valid file descriptor.
236 .TP
237 .B EFAULT
238 .I path
239 is NULL
240 or a pointer to a location
241 outside the calling process's accessible address space.
242 .TP
243 .B EINVAL
244 Invalid flag specified in
245 .IR flags .
246 .TP
247 .B ELOOP
248 Too many symbolic links encountered when resolving
249 .IR path .
250 .TP
251 .B EMFILE
252 The calling process has too many open files to create more.
253 .TP
254 .B ENAMETOOLONG
255 .I path
256 is longer than
257 .BR PATH_MAX .
258 .TP
259 .B ENFILE
260 The system has too many open files to create more.
261 .TP
262 .B ENOENT
263 A component of
264 .I path
265 does not exist,
266 or is a dangling symbolic link.
267 .TP
268 .B ENOENT
269 .I path
270 is an empty string, but
271 .B \%FSPICK_EMPTY_PATH
272 is not specified in
273 .IR flags .
274 .TP
275 .B ENOTDIR
276 A component of the path prefix of
277 .I path
278 is not a directory;
279 or
280 .I path
281 is relative and
282 .I dirfd
283 is a file descriptor referring to a file other than a directory.
284 .TP
285 .B ENOMEM
286 The kernel could not allocate sufficient memory to complete the operation.
287 .TP
288 .B EPERM
289 The calling process does not have the required
290 .B \%CAP_SYS_ADMIN
291 capability.
292 .SH STANDARDS
293 Linux.
294 .SH HISTORY
295 Linux 5.2.
296 .\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
297 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
298 glibc 2.36.
299 .SH EXAMPLES
300 The following example sets the read-only flag
301 on the filesystem instance referenced by
302 the mount object attached at
303 .IR /tmp .
304 .P
305 .in +4n
306 .EX
307 int fsfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
308 fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
309 fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
310 .EE
311 .in
312 .P
313 The above procedure is roughly equivalent to
314 the following mount operation using
315 .BR mount (2):
316 .P
317 .in +4n
318 .EX
319 mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
320 .EE
321 .in
322 .P
323 With the notable caveat that
324 in this example,
325 .BR mount (2)
326 will clear all other filesystem parameters
327 (such as
328 .B MS_DIRSYNC
329 or
330 .BR MS_SYNCHRONOUS );
331 .BR fsconfig (2)
332 will only modify the
333 .B ro
334 parameter.
335 .SH SEE ALSO
336 .BR fsconfig (2),
337 .BR fsmount (2),
338 .BR fsopen (2),
339 .BR mount (2),
340 .BR mount_setattr (2),
341 .BR move_mount (2),
342 .BR open_tree (2),
343 .BR mount_namespaces (7)