Linux-Fsdevel Archive on lore.kernel.org
help / color / mirror / Atom feed
From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: David Howells <dhowells@redhat.com>, viro@zeniv.linux.org.uk
Cc: mtk.manpages@gmail.com, linux-fsdevel@vger.kernel.org,
	linux-man@vger.kernel.org, linux-api@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH 3/5] Add manpage for fspick(2)
Date: Thu, 27 Aug 2020 13:05:02 +0200	[thread overview]
Message-ID: <b968aced-c375-4c85-b086-9874d12e07f4@gmail.com> (raw)
In-Reply-To: <159827189767.306468.1803062787718957199.stgit@warthog.procyon.org.uk>

Hello David,

On 8/24/20 2:24 PM, David Howells wrote:
> Add a manual page to document the fspick() system call.
> 
> Signed-off-by: David Howells <dhowells@redhat.com>
> ---
> 
>  man2/fspick.2 |  180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 180 insertions(+)
>  create mode 100644 man2/fspick.2
> 
> diff --git a/man2/fspick.2 b/man2/fspick.2
> new file mode 100644
> index 000000000..72bf645dd
> --- /dev/null
> +++ b/man2/fspick.2
> @@ -0,0 +1,180 @@
> +'\" t
> +.\" Copyright (c) 2020 David Howells <dhowells@redhat.com>
> +.\"
> +.\" %%%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 2020-08-24 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +fspick \- Select filesystem for reconfiguration
> +.SH SYNOPSIS
> +.nf
> +.B #include <sys/types.h>
> +.B #include <sys/mount.h>
> +.B #include <unistd.h>
> +.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.  The file descriptor 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 final component of the path.
> +.TP
> +.B FSPICK_NO_AUTOMOUNT
> +Don't follow automounts in the final 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 the target mount 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

Better: s/using that/in order/

> +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

s/descriptor/descriptor returned by fspick()/

> +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 of 8 messages, so it's possible for some to get lost.

What if there are no pending error messages to retrieve? What does
read() do in that case? Please add an explanation here.

> +.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.
> +Additionally, 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 .

MAXPATHLEN is not, I think, a constant known in user space. What is this?
Should it be PATH_MAX?

> +.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.

Please note the necessary capability here. Also, there was no mention of 
capabilities/privileges in DESCRIPTION. Should there have been?

> +.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.2.
> +.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 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)

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

  reply	other threads:[~2020-08-27 11:21 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-24 12:24 [PATCH 1/5] Add manpage for open_tree(2) David Howells
2020-08-24 12:24 ` [PATCH 2/5] Add manpages for move_mount(2) David Howells
2020-08-27 11:04   ` Michael Kerrisk (man-pages)
2021-08-13  0:21     ` Michael Kerrisk (man-pages)
2021-01-22  8:39   ` Michael Kerrisk (man-pages)
2020-08-24 12:24 ` [PATCH 3/5] Add manpage for fspick(2) David Howells
2020-08-27 11:05   ` Michael Kerrisk (man-pages) [this message]
2021-08-13  0:22     ` Michael Kerrisk (man-pages)
2021-01-22  8:40   ` Michael Kerrisk (man-pages)
2020-08-24 12:25 ` [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2) David Howells
2020-08-27 11:07   ` Michael Kerrisk (man-pages)
2021-08-13  0:22     ` Michael Kerrisk (man-pages)
2020-09-02 15:01   ` Michael Kerrisk (man-pages)
2020-09-02 16:14   ` David Howells
2020-09-02 20:14     ` Michael Kerrisk (man-pages)
2020-09-11 12:44       ` Michael Kerrisk (man-pages)
2020-10-16  6:50         ` Michael Kerrisk (man-pages)
2021-01-22  8:41           ` Michael Kerrisk (man-pages)
2020-08-24 12:25 ` [PATCH 5/5] Add manpage for fsconfig(2) David Howells
2020-08-27 11:07   ` Michael Kerrisk (man-pages)
2021-08-13  0:23     ` Michael Kerrisk (man-pages)
2021-01-22  8:40   ` Michael Kerrisk (man-pages)
2020-08-27 11:01 ` [PATCH 1/5] Add manpage for open_tree(2) Michael Kerrisk (man-pages)
2021-01-22  8:39   ` Michael Kerrisk (man-pages)
2021-08-13  0:20   ` Michael Kerrisk (man-pages)
2021-02-25 19:03 ` Aurélien Aptel
  -- strict thread matches above, loose matches on Subject: below --
2020-08-07 14:02 David Howells
2020-08-07 14:02 ` [PATCH 3/5] Add manpage for fspick(2) David Howells
2020-08-22 20:05   ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=b968aced-c375-4c85-b086-9874d12e07f4@gmail.com \
    --to=mtk.manpages@gmail.com \
    --cc=dhowells@redhat.com \
    --cc=linux-api@vger.kernel.org \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=viro@zeniv.linux.org.uk \
    --subject='Re: [PATCH 3/5] Add manpage for fspick(2)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).