.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH fspick 2 (date) "Linux man-pages (unreleased)"
.SH NAME
fspick \- select filesystem for reconfiguration
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <fcntl.h>" "          /* Definition of " AT_* " constants */"
.B #include <sys/mount.h>
.P
.BI "int fspick(int " dirfd ", const char *" path ", unsigned int " flags );
.fi
.SH DESCRIPTION
The
.BR fspick ()
system call is part of
the suite of file-descriptor-based mount facilities in Linux.
.P
.BR fspick ()
creates a new filesystem configuration context
for the extant filesystem instance
associated with the path described by
.I dirfd
and
.IR path ,
places it into reconfiguration mode
(similar to
.BR mount (8)
with the
.B \-o\~remount
option).
A new file descriptor
associated with the filesystem configuration context
is then returned.
The calling process must have the
.B \%CAP_SYS_ADMIN
capability in order to create a new filesystem configuration context.
.P
The resultant file descriptor can be used with
.BR 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
.BR fsconfig (2)
with the
.B \%FSCONFIG_CMD_RECONFIGURE
command.
In contrast to
the behaviour of
.B MS_REMOUNT
with
.BR mount (2),
.BR fspick ()
instantiates the filesystem configuration context
with a copy of
the extant filesystem's filesystem parameters;
thus,
subsequent
.B \%FSCONFIG_CMD_RECONFIGURE
operations
will only update filesystem parameters
explicitly modified with
.BR fsconfig (2).
.P
As with "*at()" system calls,
.BR fspick ()
uses the
.I dirfd
argument in conjunction with the
.I path
argument to determine the path to operate on, as follows:
.IP \[bu] 3
If the pathname given in
.I path
is absolute, then
.I dirfd
is ignored.
.IP \[bu]
If the pathname given in
.I path
is relative and
.I dirfd
is the special value
.BR \%AT_FDCWD ,
then
.I path
is interpreted relative to
the current working directory
of the calling process (like
.BR open (2)).
.IP \[bu]
If the pathname given in
.I path
is relative,
then it is interpreted relative to
the directory referred to by the file descriptor
.I dirfd
(rather than relative to
the current working directory
of the calling process,
as is done by
.BR open (2)
for a relative pathname).
In this case,
.I dirfd
must be a directory
that was opened for reading
.RB ( O_RDONLY )
or using the
.B O_PATH
flag.
.IP \[bu]
If
.I path
is an empty string,
and
.I flags
contains
.BR \%FSPICK_EMPTY_PATH ,
then the file descriptor
.I dirfd
is operated on directly.
In this case,
.I dirfd
may refer to any type of file,
not just a directory.
.P
See
.BR openat (2)
for an explanation of why the
.I dirfd
argument is useful.
.P
.I flags
can be used to control aspects of how
.I path
is resolved and
properties of the returned file descriptor.
A value for
.I flags
is constructed by bitwise ORing
zero or more of the following constants:
.RS
.TP
.B FSPICK_CLOEXEC
Set the close-on-exec
.RB ( FD_CLOEXEC )
flag on the new file descriptor.
See the description of the
.B O_CLOEXEC
flag in
.BR open (2)
for reasons why this may be useful.
.TP
.B FSPICK_EMPTY_PATH
If
.I path
is an empty string,
operate on the file referred to by
.I dirfd
(which may have been obtained from
.BR open (2),
.BR fsmount (2),
or
.BR open_tree (2)).
In this case,
.I dirfd
may refer to any type of file,
not just a directory.
If
.I dirfd
is
.BR \%AT_FDCWD ,
.BR fspick ()
will operate on the current working directory
of the calling process.
.TP
.B FSPICK_SYMLINK_NOFOLLOW
Do not follow symbolic links
in the terminal component of
.IR path .
If
.I path
references a symbolic link,
the returned filesystem context will reference
the filesystem that the symbolic link itself resides on.
.TP
.B FSPICK_NO_AUTOMOUNT
Do not automount the terminal ("basename") component of
.I 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.
.RE
.P
As with filesystem contexts created with
.BR fsopen (2),
the file descriptor returned by
.BR fspick ()
may be queried for message strings at any time by calling
.BR read (2)
on the file descriptor.
(See the "Message retrieval interface" subsection in
.BR fsopen (2)
for more details on the message format.)
.SH RETURN VALUE
On success, a new file descriptor is returned.
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EACCES
Search permission is denied
for one of the directories
in the path prefix of
.IR path .
(See also
.BR path_resolution (7).)
.TP
.B EBADF
.I path
is relative but
.I dirfd
is neither
.B \%AT_FDCWD
nor a valid file descriptor.
.TP
.B EFAULT
.I path
is NULL
or a pointer to a location
outside the calling process's accessible address space.
.TP
.B EINVAL
Invalid flag specified in
.IR flags .
.TP
.B ELOOP
Too many symbolic links encountered when resolving
.IR path .
.TP
.B EMFILE
The calling process has too many open files to create more.
.TP
.B ENAMETOOLONG
.I path
is longer than
.BR PATH_MAX .
.TP
.B ENFILE
The system has too many open files to create more.
.TP
.B ENOENT
A component of
.I path
does not exist,
or is a dangling symbolic link.
.TP
.B ENOENT
.I path
is an empty string, but
.B \%FSPICK_EMPTY_PATH
is not specified in
.IR flags .
.TP
.B ENOTDIR
A component of the path prefix of
.I path
is not a directory;
or
.I path
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.TP
.B ENOMEM
The kernel could not allocate sufficient memory to complete the operation.
.TP
.B EPERM
The calling process does not have the required
.B \%CAP_SYS_ADMIN
capability.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 5.2.
.\" commit cf3cba4a429be43e5527a3f78859b1bfd9ebc5fb
.\" commit 400913252d09f9cfb8cce33daee43167921fc343
glibc 2.36.
.SH EXAMPLES
The following example sets the read-only flag
on the filesystem instance referenced by
the mount object attached at
.IR /tmp .
.P
.in +4n
.EX
int fsfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
.EE
.in
.P
The above procedure is roughly equivalent to
the following mount operation using
.BR mount (2):
.P
.in +4n
.EX
mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);
.EE
.in
.P
With the notable caveat that
in this example,
.BR mount (2)
will clear all other filesystem parameters
(such as
.B MS_DIRSYNC
or
.BR MS_SYNCHRONOUS );
.BR fsconfig (2)
will only modify the
.B ro
parameter.
.SH SEE ALSO
.BR fsconfig (2),
.BR fsmount (2),
.BR fsopen (2),
.BR mount (2),
.BR mount_setattr (2),
.BR move_mount (2),
.BR open_tree (2),
.BR mount_namespaces (7)