[MANPAGE] fspick.2

[David Howells]

'\" t
.\" Copyright (c) 2019 David Howells <dhowells@xxxxxxxxxx>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.TH FSPICK 2 2019-10-10 "Linux" "Linux Programmer's Manual"
.SH NAME
fspick \- Select filesystem for reconfiguration
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.br
.B #include <sys/mount.h>
.br
.B #include <unistd.h>
.br
.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
.PP
.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags );
.fi
.PP
.IR Note :
There is no glibc wrapper for this system call.
.SH DESCRIPTION
.PP
.BR fspick ()
creates a new filesystem configuration context within the kernel and attaches a
pre-existing superblock to it so that it can be reconfigured (similar to
.BR mount (8)
with the "-o remount" option).  The configuration context is marked as being in
reconfiguration mode and attached to a file descriptor, which is returned to
the caller.  This can be marked close-on-exec by setting
.B FSPICK_CLOEXEC
in
.IR flags .
.PP
The target is whichever superblock backs the object determined by
.IR dfd ", " pathname " and " flags .
The following can be set in
.I flags
to control the pathwalk to that object:
.TP
.B FSPICK_SYMLINK_NOFOLLOW
Don't follow symbolic links in the terminal component of the path.
.TP
.B FSPICK_NO_AUTOMOUNT
Don't follow automounts in the terminal component of the path.
.TP
.B FSPICK_EMPTY_PATH
Allow an empty string to be specified as the pathname.  This allows
.I dirfd
to specify a path exactly.
.PP
After calling fspick(), the file descriptor should be passed to the
.BR fsconfig (2)
system call, using that to specify the desired changes to filesystem and
security parameters.
.PP
When the parameters are all set, the
.BR fsconfig ()
system call should then be called again with
.B FSCONFIG_CMD_RECONFIGURE
as the command argument to effect the reconfiguration.
.PP
After the reconfiguration has taken place, the context is wiped clean (apart
from the superblock attachment, which remains) and can be reused to make
another reconfiguration.
.PP
The file descriptor also serves as a channel by which more comprehensive error,
warning and information messages may be retrieved from the kernel using
.BR read (2).


.\"________________________________________________________
.SS Message Retrieval Interface
The context file descriptor may be queried for message strings at any time by
calling
.BR read (2)
on the file descriptor.  This will return formatted messages that are prefixed
to indicate their class:
.TP
\fB"e <message>"\fP
An error message string was logged.
.TP
\fB"i <message>"\fP
An informational message string was logged.
.TP
\fB"w <message>"\fP
An warning message string was logged.
.PP
Messages are removed from the queue as they're read and the queue has a limited
depth, so it's possible for some to get lost.

.\"________________________________________________________
.SH EXAMPLES
To illustrate the process, here's an example whereby this can be used to
reconfigure a filesystem:
.PP
.in +4n
.nf
sfd = fspick(AT_FDCWD, "/mnt", FSPICK_NO_AUTOMOUNT | FSPICK_CLOEXEC);
fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
fsconfig(sfd, FSCONFIG_SET_STRING, "user_xattr", "false", 0);
fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
.fi
.in
.PP


.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH RETURN VALUE
On success, the function returns a file descriptor.  On error, \-1 is returned,
and
.I errno
is set appropriately.
.SH ERRORS
The error values given below result from filesystem type independent
errors.
Each filesystem type may have its own special errors and its
own special behavior.
See the Linux kernel source code for details.
.TP
.B EACCES
A component of a path was not searchable.
(See also
.BR path_resolution (7).)
.TP
.B EFAULT
.I pathname
points outside the user address space.
.TP
.B EINVAL
.I flags
includes an undefined value.
.TP
.B ELOOP
Too many links encountered during pathname resolution.
.TP
.B EMFILE
The system has too many open files to create more.
.TP
.B ENFILE
The process has too many open files to create more.
.TP
.B ENAMETOOLONG
A pathname was longer than
.BR MAXPATHLEN .
.TP
.B ENOENT
A pathname was empty or had a nonexistent component.
.TP
.B ENOMEM
The kernel could not allocate sufficient memory to complete the call.
.TP
.B EPERM
The caller does not have the required privileges.
.SH CONFORMING TO
These functions are Linux-specific and should not be used in programs intended
to be portable.
.SH VERSIONS
.BR fsopen "(), " fsmount "() and " fspick ()
were added to Linux in kernel 5.1.
.SH NOTES
Glibc does not (yet) provide a wrapper for the
.BR fspick "()"
system call; call it using
.BR syscall (2).
.SH SEE ALSO
.BR mountpoint (1),
.BR fsconfig (2),
.BR fsopen (2),
.BR path_resolution (7),
.BR mount (8)