|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | STANDARDS | HISTORY | EXAMPLES | SEE ALSO | COLOPHON |
|
|
|
fspick(2) System Calls Manual fspick(2)
fspick - select filesystem for reconfiguration
Standard C library (libc, -lc)
#include <fcntl.h> /* Definition of AT_* constants */
#include <sys/mount.h>
int fspick(int dirfd, const char *path, unsigned int flags);
The fspick() system call is part of the suite of file-descriptor-
based mount facilities in Linux.
fspick() creates a new filesystem configuration context for the
extant filesystem instance associated with the path described by
dirfd and path, places it into reconfiguration mode (similar to
mount(8) with the -o remount option). A new file descriptor
associated with the filesystem configuration context is then
returned. The calling process must have the CAP_SYS_ADMIN
capability in order to create a new filesystem configuration
context.
The resultant file descriptor can be used with fsconfig(2) to
specify the desired set of changes to filesystem parameters of the
filesystem instance. Once the desired set of changes have been
configured, the changes can be effectuated by calling fsconfig(2)
with the FSCONFIG_CMD_RECONFIGURE command. In contrast to the
behaviour of MS_REMOUNT with mount(2), fspick() instantiates the
filesystem configuration context with a copy of the extant
filesystem's filesystem parameters; thus, subsequent
FSCONFIG_CMD_RECONFIGURE operations will only update filesystem
parameters explicitly modified with fsconfig(2).
As with "*at()" system calls, fspick() uses the dirfd argument in
conjunction with the path argument to determine the path to
operate on, as follows:
• If the pathname given in path is absolute, then dirfd is
ignored.
• If the pathname given in path is relative and dirfd is the
special value AT_FDCWD, then path is interpreted relative to
the current working directory of the calling process (like
open(2)).
• If the pathname given in path is relative, then it is
interpreted relative to the directory referred to by the file
descriptor dirfd (rather than relative to the current working
directory of the calling process, as is done by open(2) for a
relative pathname). In this case, dirfd must be a directory
that was opened for reading (O_RDONLY) or using the O_PATH
flag.
• If path is an empty string, and flags contains
FSPICK_EMPTY_PATH, then the file descriptor dirfd is operated
on directly. In this case, dirfd may refer to any type of
file, not just a directory.
See openat(2) for an explanation of why the dirfd argument is
useful.
flags can be used to control aspects of how path is resolved and
properties of the returned file descriptor. A value for flags is
constructed by bitwise ORing zero or more of the following
constants:
FSPICK_CLOEXEC
Set the close-on-exec (FD_CLOEXEC) flag on the new
file descriptor. See the description of the
O_CLOEXEC flag in open(2) for reasons why this may
be useful.
FSPICK_EMPTY_PATH
If path is an empty string, operate on the file
referred to by dirfd (which may have been obtained
from open(2), fsmount(2), or open_tree(2)). In this
case, dirfd may refer to any type of file, not just
a directory. If dirfd is AT_FDCWD, fspick() will
operate on the current working directory of the
calling process.
FSPICK_SYMLINK_NOFOLLOW
Do not follow symbolic links in the terminal
component of path. If path references a symbolic
link, the returned filesystem context will reference
the filesystem that the symbolic link itself resides
on.
FSPICK_NO_AUTOMOUNT
Do not automount the terminal ("basename") component
of path if it is a directory that is an automount
point. This allows you to reconfigure an automount
point, rather than the location that would be
mounted. This flag has no effect if the automount
point has already been mounted over.
As with filesystem contexts created with fsopen(2), the file
descriptor returned by fspick() may be queried for message strings
at any time by calling read(2) on the file descriptor. (See the
"Message retrieval interface" subsection in fsopen(2) for more
details on the message format.)
On success, a new file descriptor is returned. On error, -1 is
returned, and errno is set to indicate the error.
EACCES Search permission is denied for one of the directories in
the path prefix of path. (See also path_resolution(7).)
EBADF path is relative but dirfd is neither AT_FDCWD nor a valid
file descriptor.
EFAULT path is NULL or a pointer to a location outside the calling
process's accessible address space.
EINVAL Invalid flag specified in flags.
ELOOP Too many symbolic links encountered when resolving path.
EMFILE The calling process has too many open files to create more.
ENAMETOOLONG
path is longer than PATH_MAX.
ENFILE The system has too many open files to create more.
ENOENT A component of path does not exist, or is a dangling
symbolic link.
ENOENT path is an empty string, but FSPICK_EMPTY_PATH is not
specified in flags.
ENOTDIR
A component of the path prefix of path is not a directory;
or path is relative and dirfd is a file descriptor
referring to a file other than a directory.
ENOMEM The kernel could not allocate sufficient memory to complete
the operation.
EPERM The calling process does not have the required
CAP_SYS_ADMIN capability.
Linux.
Linux 5.2. glibc 2.36.
The following example sets the read-only flag on the filesystem
instance referenced by the mount object attached at /tmp.
int fsfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
The above procedure is roughly equivalent to the following mount
operation using mount(2):
mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
With the notable caveat that in this example, mount(2) will clear
all other filesystem parameters (such as MS_DIRSYNC or
MS_SYNCHRONOUS); fsconfig(2) will only modify the ro parameter.
fsconfig(2), fsmount(2), fsopen(2), mount(2), mount_setattr(2),
move_mount(2), open_tree(2), mount_namespaces(7)
This page is part of the man-pages (Linux kernel and C library
user-space interface documentation) project. Information about
the project can be found at
⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report
for this manual page, see
⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
This page was obtained from the tarball man-pages-6.16.tar.gz
fetched from
⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
2026-01-16. If you discover any rendering problems in this HTML
version of the page, or you believe there is a better or more up-
to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not
part of the original manual page), send a mail to
man-pages@man7.org
Linux man-pages 6.16 2025-10-01 fspick(2)
Pages that refer to this page: fsconfig(2), fsmount(2), fsopen(2), move_mount(2), open(2), open_tree(2), syscalls(2)
|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|