Linux-Fsdevel Archive on lore.kernel.org
help / color / mirror / Atom feed
From: David Howells <dhowells@redhat.com>
To: mtk.manpages@gmail.com, viro@zeniv.linux.org.uk
Cc: dhowells@redhat.com, linux-fsdevel@vger.kernel.org,
	linux-man@vger.kernel.org, linux-api@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH 5/5] Add manpage for fsconfig(2)
Date: Mon, 24 Aug 2020 13:25:12 +0100	[thread overview]
Message-ID: <159827191245.306468.4903071494263813779.stgit@warthog.procyon.org.uk> (raw)
In-Reply-To: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk>

Add a manual page to document the fsconfig() system call.

Signed-off-by: David Howells <dhowells@redhat.com>
---

 man2/fsconfig.2 |  277 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 277 insertions(+)
 create mode 100644 man2/fsconfig.2

diff --git a/man2/fsconfig.2 b/man2/fsconfig.2
new file mode 100644
index 000000000..da53d2fcb
--- /dev/null
+++ b/man2/fsconfig.2
@@ -0,0 +1,277 @@
+'\" 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 FSCONFIG 2 2020-08-24 "Linux" "Linux Programmer's Manual"
+.SH NAME
+fsconfig \- Filesystem parameterisation
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/mount.h>
+.B #include <unistd.h>
+.B #include <sys/mount.h>
+.PP
+.BI "int fsconfig(int *" fd ", unsigned int " cmd ", const char *" key ,
+.br
+.BI "             const void __user *" value ", int " aux ");"
+.br
+.BI
+.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call.
+.SH DESCRIPTION
+.PP
+.BR fsconfig ()
+is used to supply parameters to and issue commands against a filesystem
+configuration context as set up by
+.BR fsopen (2)
+or
+.BR fspick (2).
+The context is supplied attached to the file descriptor specified by
+.I fd
+argument.
+.PP
+The
+.I cmd
+argument indicates the command to be issued, where some of the commands simply
+supply parameters to the context.  The meaning of
+.IR key ", " value " and " aux
+are command-dependent; unless required for the command, these should be set to
+NULL or 0.
+.PP
+The available commands are:
+.TP
+.B FSCONFIG_SET_FLAG
+Set the parameter named by
+.IR key
+to true.  This may fail with error
+.B EINVAL
+if the parameter requires an argument.
+.TP
+.B FSCONFIG_SET_STRING
+Set the parameter named by
+.I key
+to a string.  This may fail with error
+.B EINVAL
+if the parser doesn't want a parameter here, wants a non-string or the string
+cannot be interpreted appropriately.
+.I value
+points to a NUL-terminated string.
+.TP
+.B FSCONFIG_SET_BINARY
+Set the parameter named by
+.I key
+to be a binary blob argument.  This may cause
+.B EINVAL
+to be returned if the filesystem parser isn't expecting a binary blob and it
+can't be converted to something usable.
+.I value
+points to the data and
+.I aux
+indicates the size of the data.
+.TP
+.B FSCONFIG_SET_PATH
+Set the parameter named by
+.I key
+to the object at the provided path.
+.I value
+should point to a NUL-terminated pathname string and aux may indicate
+.B AT_FDCWD
+or a file descriptor indicating a directory from which to begin a relative
+path resolution.  This may fail with error
+.B EINVAL
+if the parameter isn't expecting a path; it may also fail if the path cannot
+be resolved with the typcal errors for that
+.RB "(" ENOENT ", " ENOTDIR ", " EPERM ", " EACCES ", etc.)."
+.IP
+Note that FSCONFIG_SET_STRING can be used instead, implying AT_FDCWD.
+.TP
+.B FSCONFIG_SET_PATH_EMPTY
+As FSCONFIG_SET_PATH, but with
+.B AT_EMPTY_PATH
+applied to the pathwalk.
+.TP
+.B FSCONFIG_SET_FD
+Set the parameter named by
+.I key
+to the file descriptor specified by
+.IR aux .
+This will fail with
+.B EINVAL
+if the parameter doesn't expect a file descriptor or
+.B EBADF
+if the file descriptor is invalid.
+.IP
+Note that FSCONFIG_SET_STRING can be used instead with the file descriptor
+passed as a decimal string.
+.TP
+.B FSCONFIG_CMD_CREATE
+This command triggers the filesystem to take the parameters set in the context
+and to try to create filesystem representation in the kernel.  If an existing
+representation can be shared, the filesystem may do that instead if the
+parameters permit.  This is intended for use with
+.BR fsopen (2).
+.TP
+.B FSCONFIG_CMD_RECONFIGURE
+This command causes the driver to alter the parameters of an already live
+filesystem instance according to the parameters stored in the context.  This
+is intended for use with
+.BR fspick (2),
+but may also by used against the context created by
+.BR fsopen()
+after
+.BR fsmount (2)
+has been called on it.
+
+.\"________________________________________________________
+.SH EXAMPLES
+.PP
+.in +4n
+.nf
+fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
+
+fsconfig(sfd, FSCONFIG_SET_STRING, "user_xattr", "false", 0);
+
+fsconfig(sfd, FSCONFIG_SET_BINARY, "ms_pac", pac_buffer, pac_size);
+
+fsconfig(sfd, FSCONFIG_SET_PATH, "journal", "/dev/sdd4", AT_FDCWD);
+
+dirfd = open("/dev/", O_PATH);
+fsconfig(sfd, FSCONFIG_SET_PATH, "journal", "sdd4", dirfd);
+
+fd = open("/overlays/mine/", O_PATH);
+fsconfig(sfd, FSCONFIG_SET_PATH_EMPTY, "lower_dir", "", fd);
+
+pipe(pipefds);
+fsconfig(sfd, FSCONFIG_SET_FD, "fd", NULL, pipefds[1]);
+.fi
+.in
+.PP
+.SH RETURN VALUE
+On success, the function returns 0.  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 EACCES
+Mounting a read-only filesystem was attempted without specifying the
+.RB ' ro '
+parameter.
+.TP
+.B EACCES
+A specified block device is located on a filesystem mounted with the
+.B MS_NODEV
+option.
+.\" mtk: Probably: write permission is required for MS_BIND, with
+.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required.
+.TP
+.B EBADF
+The file descriptor given by
+.I fd
+or possibly by
+.I aux
+(depending on the command) is invalid.
+.TP
+.B EBUSY
+The context attached to
+.I fd
+is in the wrong state for the given command.
+.TP
+.B EBUSY
+The filesystem representation cannot be reconfigured read-only because it still
+holds files open for writing.
+.TP
+.B EFAULT
+One of the pointer arguments points outside the accessible address space.
+.TP
+.B EINVAL
+.I fd
+does not refer to a filesystem configuration context.
+.TP
+.B EINVAL
+One of the source parameters referred to an invalid superblock.
+.TP
+.B ELOOP
+Too many links encountered during pathname resolution.
+.TP
+.B ENAMETOOLONG
+A path name 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 ENOTBLK
+Once of the parameters does not refer to a block device (and a device was
+required).
+.TP
+.B ENOTDIR
+.IR pathname ,
+or a prefix of
+.IR source ,
+is not a directory.
+.TP
+.B EOPNOTSUPP
+The command given by
+.I cmd
+was not valid.
+.TP
+.B ENXIO
+The major number of a block device parameter is out of range.
+.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 fsconfig ()
+was added to Linux in kernel 5.2.
+.SH NOTES
+Glibc does not (yet) provide a wrapper for the
+.BR fsconfig ()
+system call; call it using
+.BR syscall (2).
+.SH SEE ALSO
+.BR mountpoint (1),
+.BR fsmount (2),
+.BR fsopen (2),
+.BR fspick (2),
+.BR mount_namespaces (7),
+.BR path_resolution (7)



  parent reply	other threads:[~2020-08-24 12:25 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)
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 ` David Howells [this message]
2020-08-27 11:07   ` [PATCH 5/5] Add manpage for fsconfig(2) 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 5/5] Add manpage for fsconfig(2) David Howells
2020-08-22 20:18   ` 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=159827191245.306468.4903071494263813779.stgit@warthog.procyon.org.uk \
    --to=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=mtk.manpages@gmail.com \
    --cc=viro@zeniv.linux.org.uk \
    --subject='Re: [PATCH 5/5] Add manpage for fsconfig(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).