From: David Howells <dhowells@redhat.com>
To: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: dhowells@redhat.com, viro@zeniv.linux.org.uk,
linux-api@vger.kernel.org, linux-fsdevel@vger.kernel.org,
torvalds@linux-foundation.org, linux-kernel@vger.kernel.org,
linux-man@vger.kernel.org
Subject: [MANPAGE PATCH] Add manpage for fsopen(2), fspick(2) and fsmount(2)
Date: Tue, 10 Jul 2018 23:54:09 +0100 [thread overview]
Message-ID: <15488.1531263249@warthog.procyon.org.uk> (raw)
In-Reply-To: <153126264966.14533.3388004240803696769.stgit@warthog.procyon.org.uk>
Add a manual page to document the fsopen(), fspick() and fsmount() system
calls.
Signed-off-by: David Howells <dhowells@redhat.com>
---
man2/fsmount.2 | 1
man2/fsopen.2 | 357 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
man2/fspick.2 | 1
3 files changed, 359 insertions(+)
create mode 100644 man2/fsmount.2
create mode 100644 man2/fsopen.2
create mode 100644 man2/fspick.2
diff --git a/man2/fsmount.2 b/man2/fsmount.2
new file mode 100644
index 000000000..2bf59fc3e
--- /dev/null
+++ b/man2/fsmount.2
@@ -0,0 +1 @@
+.so man2/fsopen.2
diff --git a/man2/fsopen.2 b/man2/fsopen.2
new file mode 100644
index 000000000..1bc761ab4
--- /dev/null
+++ b/man2/fsopen.2
@@ -0,0 +1,357 @@
+'\" t
+.\" Copyright (c) 2018 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 FSOPEN 2 2018-06-07 "Linux" "Linux Programmer's Manual"
+.SH NAME
+fsopen, fsmount, fspick \- Handle filesystem (re-)configuration and mounting
+.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 fsopen(const char *" fsname ", unsigned int " flags );
+.PP
+.BI "int fsmount(int " fd ", unsigned int " flags ", unsigned int " ms_flags );
+.PP
+.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags );
+.fi
+.PP
+.IR Note :
+There are no glibc wrappers for these system calls.
+.SH DESCRIPTION
+.PP
+.BR fsopen ()
+creates a new filesystem configuration context within the kernel for the
+filesystem named in the
+.I fsname
+parameter and attaches it to a file descriptor, which it then returns. The
+file descriptor can be marked close-on-exec by setting
+.B FSOPEN_CLOEXEC
+in flags.
+.PP
+The
+file descriptor can then be used to configure the desired filesystem parameters
+and security parameters by using
+.BR write (2)
+to pass parameters to it and then writing a command to actually create the
+filesystem representation.
+.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).
+.PP
+Once the kernel's filesystem representation has been created, it can be queried
+by calling
+.BR fsinfo (2)
+on the file descriptor. fsinfo() will spot that the target is actually a
+creation context and look inside that.
+.PP
+.BR fsmount ()
+can then be called to create a mount object that refers to the newly created
+filesystem representation, with the propagation and mount restrictions to be
+applied specified in
+.IR ms_flags .
+The mount object is then attached to a new file descriptor that looks like one
+created by
+.BR open "(2) with " O_PATH " or " open_tree (2).
+This can be passed to
+.BR move_mount (2)
+to attach the mount object to a mountpoint, thereby completing the process.
+.PP
+The file descriptor returned by fsmount() is marked close-on-exec if
+FSMOUNT_CLOEXEC is specified in
+.IR flags .
+.PP
+After fsmount() has completed, the context created by fsopen() is reset and
+moved to reconfiguration state, allowing the new superblock to be reconfigured.
+.PP
+.BR fspick ()
+creates a new filesystem context within the kernel, attaches the superblock
+specified by
+.IR dfd ", " pathname ", " flags
+and puts it into the reconfiguration state and attached the context to a new
+file descriptor that can then be parameterised with
+.BR write (2)
+exactly the same as for the context created by fsopen() above.
+.PP
+.I flags
+is an OR'd together mask of
+.B FSPICK_CLOEXEC
+which indicates that the returned file descriptor should be marked
+close-on-exec and
+.BR FSPICK_SYMLINK_NOFOLLOW ", " FSPICK_NO_AUTOMOUNT " and " FSPICK_EMPTY_PATH
+which control the pathwalk to the target object (see below).
+
+.\"________________________________________________________
+.SS Writable Command Interface
+Superblock (re-)configuration is achieved by writing command strings to the
+context file descriptor using
+.BR write (2).
+Each string is prefixed with a specifier indicating the class of command
+being specified. The available commands include:
+.TP
+\fB"o <option>"\fP
+Specify a filesystem or security parameter.
+.I <option>
+is typically a key or key=val format string. Since the length of the option is
+given to write(), the option may include any sort of character, including
+spaces and commas or even binary data.
+.TP
+\fB"s <name>"\fP
+Specify a device file, network server or other other source specification.
+This may be optional, depending on the filesystem, and it may be possible to
+provide multiple of them to a filesystem.
+.TP
+\fB"x create"\fP
+End the filesystem configuration phase and try and create a representation in
+the kernel with the parameters specified. After this, the context is shifted
+to the mount-pending state waiting for an fsmount() call to occur.
+.TP
+\fB"x reconfigure"\fP
+End a filesystem reconfiguration phase try to apply the parameters to the
+filesystem representation. After this, the context gets reset and put back to
+the start of the reconfiguration phase again.
+.PP
+With this interface, option strings are not limited to 4096 bytes, either
+individually or in sum, and they are also not restricted to text-only options.
+Further, errors may be given individually for each option and not aggregated or
+dumped into the kernel log.
+
+.\"________________________________________________________
+.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.
+
+.\"________________________________________________________
+.SH EXAMPLES
+To illustrate the process, here's an example whereby this can be used to mount
+an ext4 filesystem on /dev/sdb1 onto /mnt. Note that the example ignores the
+fact that
+.BR write (2)
+has a length parameter and that errors might occur.
+.PP
+.in +4n
+.nf
+sfd = fsopen("ext4", FSOPEN_CLOEXEC);
+write(sfd, "s /dev/sdb1");
+write(sfd, "o noatime");
+write(sfd, "o acl");
+write(sfd, "o user_attr");
+write(sfd, "o iversion");
+write(sfd, "x create");
+fsinfo(sfd, NULL, ...);
+mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MS_RELATIME);
+move_mount(mfd, "", sfd, AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+.fi
+.in
+.PP
+Here, an ext4 context is created first and attached to sfd. This is then told
+where its source will be, given a bunch of options and created.
+.BR fsinfo (2)
+can then be used to query the filesystem. Then fsmount() is called to create a
+mount object and
+.BR move_mount (2)
+is called to attach it to its intended mountpoint.
+.PP
+And here's an example of mounting from an NFS server:
+.PP
+.in +4n
+.nf
+sfd = fsopen("nfs", 0);
+write(sfd, "s example.com/pub/linux");
+write(sfd, "o nfsvers=3");
+write(sfd, "o rsize=65536");
+write(sfd, "o wsize=65536");
+write(sfd, "o rdma");
+write(sfd, "x create");
+mfd = fsmount(sfd, 0, MS_NODEV);
+move_mount(mfd, "", sfd, AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+.fi
+.in
+.PP
+Reconfiguration can be achieved by:
+.PP
+.in +4n
+.nf
+sfd = fspick(AT_FDCWD, "/mnt", FSPICK_NO_AUTOMOUNT | FSPICK_CLOEXEC);
+write(sfd, "o ro");
+write(sfd, "x reconfigure");
+.fi
+.in
+.PP
+or:
+.PP
+.in +4n
+.nf
+sfd = fsopen(...);
+...
+mfd = fsmount(sfd, ...);
+...
+write(sfd, "o ro");
+write(sfd, "x reconfigure");
+.fi
+.in
+
+
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success, all three functions return 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 EACCES
+Mounting a read-only filesystem was attempted without giving the
+.B MS_RDONLY
+flag.
+.TP
+.B EACCES
+The block device
+.I source
+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 EBUSY
+.I source
+cannot be reconfigured read-only, because it still holds files open for
+writing.
+.TP
+.B EFAULT
+One of the pointer arguments points outside the user address space.
+.TP
+.B EINVAL
+.I source
+had an invalid superblock.
+.TP
+.B EINVAL
+.I ms_flags
+includes more than one of
+.BR MS_SHARED ,
+.BR MS_PRIVATE ,
+.BR MS_SLAVE ,
+or
+.BR MS_UNBINDABLE .
+.TP
+.BR EINVAL
+An attempt was made to bind mount an unbindable mount.
+.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 ENODEV
+Filesystem
+.I fsname
+not configured in the kernel.
+.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
+.I source
+is not 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 ENXIO
+The major number of the block device
+.I source
+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 fsopen "(), " fsmount "() and " fspick ()
+were added to Linux in kernel 4.18.
+.SH NOTES
+Glibc does not (yet) provide a wrapper for the
+.BR fsopen "() , " fsmount "() or " fspick "()"
+system calls; call them using
+.BR syscall (2).
+.SH SEE ALSO
+.BR mountpoint (1),
+.BR move_mount (2),
+.BR open_tree (2),
+.BR umount (2),
+.BR mount_namespaces (7),
+.BR path_resolution (7),
+.BR findmnt (8),
+.BR lsblk (8),
+.BR mount (8),
+.BR umount (8)
diff --git a/man2/fspick.2 b/man2/fspick.2
new file mode 100644
index 000000000..2bf59fc3e
--- /dev/null
+++ b/man2/fspick.2
@@ -0,0 +1 @@
+.so man2/fsopen.2
next prev parent reply other threads:[~2018-07-10 22:54 UTC|newest]
Thread overview: 113+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-07-10 22:41 [PATCH 00/32] VFS: Introduce filesystem context [ver #9] David Howells
2018-07-10 22:41 ` [PATCH 01/32] vfs: syscall: Add open_tree(2) to reference or clone a mount " David Howells
2018-07-10 22:41 ` [PATCH 02/32] vfs: syscall: Add move_mount(2) to move mounts around " David Howells
2018-07-10 22:41 ` [PATCH 03/32] teach move_mount(2) to work with OPEN_TREE_CLONE " David Howells
2018-07-10 22:41 ` [PATCH 04/32] vfs: Suppress MS_* flag defs within the kernel unless explicitly enabled " David Howells
2018-07-10 22:42 ` [PATCH 05/32] vfs: Introduce the basic header for the new mount API's filesystem context " David Howells
2018-07-10 22:42 ` [PATCH 06/32] vfs: Add LSM hooks for the new mount API " David Howells
2018-07-10 22:42 ` [PATCH 07/32] selinux: Implement the new mount API LSM hooks " David Howells
2018-07-11 14:08 ` Stephen Smalley
2018-07-10 22:42 ` [PATCH 08/32] smack: Implement filesystem context security " David Howells
2018-07-10 23:13 ` Casey Schaufler
2018-07-10 23:19 ` David Howells
2018-07-10 23:28 ` Casey Schaufler
2018-07-10 22:42 ` [PATCH 09/32] apparmor: Implement security hooks for the new mount API " David Howells
2018-07-10 22:42 ` [PATCH 10/32] tomoyo: " David Howells
2018-07-10 23:34 ` Tetsuo Handa
2018-07-10 22:42 ` [PATCH 11/32] vfs: Require specification of size of mount data for internal mounts " David Howells
2018-07-10 22:51 ` Linus Torvalds
2018-07-10 22:42 ` [PATCH 12/32] vfs: Separate changing mount flags full remount " David Howells
2018-07-10 22:42 ` [PATCH 13/32] vfs: Implement a filesystem superblock creation/configuration context " David Howells
2018-07-10 22:43 ` [PATCH 14/32] vfs: Remove unused code after filesystem context changes " David Howells
2018-07-10 22:43 ` [PATCH 15/32] procfs: Move proc_fill_super() to fs/proc/root.c " David Howells
2018-07-10 22:43 ` [PATCH 16/32] proc: Add fs_context support to procfs " David Howells
2018-07-10 22:43 ` [PATCH 17/32] ipc: Convert mqueue fs to fs_context " David Howells
2018-07-10 22:43 ` [PATCH 18/32] cpuset: Use " David Howells
2018-07-10 22:43 ` [PATCH 19/32] kernfs, sysfs, cgroup, intel_rdt: Support " David Howells
2018-07-10 22:43 ` [PATCH 20/32] hugetlbfs: Convert to " David Howells
2018-07-10 22:43 ` [PATCH 21/32] vfs: Remove kern_mount_data() " David Howells
2018-07-10 22:43 ` [PATCH 22/32] vfs: Provide documentation for new mount API " David Howells
2018-07-13 1:37 ` Randy Dunlap
2018-07-13 9:45 ` David Howells
2018-07-10 22:44 ` [PATCH 23/32] Make anon_inodes unconditional " David Howells
2018-07-10 22:44 ` [PATCH 24/32] vfs: syscall: Add fsopen() to prepare for superblock creation " David Howells
2018-07-10 23:59 ` Andy Lutomirski
2018-07-11 1:05 ` Linus Torvalds
2018-07-11 1:15 ` Al Viro
2018-07-11 1:33 ` Andy Lutomirski
2018-07-11 1:48 ` Linus Torvalds
2018-07-11 8:43 ` David Howells
2018-07-11 1:14 ` Jann Horn
2018-07-11 1:16 ` Al Viro
2018-07-11 8:42 ` David Howells
2018-07-11 16:03 ` Linus Torvalds
2018-07-11 7:22 ` David Howells
2018-07-11 16:38 ` Eric Biggers
2018-07-11 17:06 ` Andy Lutomirski
2018-07-12 14:54 ` David Howells
2018-07-12 15:50 ` Linus Torvalds
2018-07-12 16:00 ` Al Viro
2018-07-12 16:07 ` Linus Torvalds
2018-07-12 16:31 ` Al Viro
2018-07-12 16:39 ` Linus Torvalds
2018-07-12 17:14 ` Linus Torvalds
2018-07-12 17:44 ` Al Viro
2018-07-12 17:54 ` Linus Torvalds
2018-07-12 17:52 ` Al Viro
2018-07-12 16:23 ` Andy Lutomirski
2018-07-12 16:31 ` Linus Torvalds
2018-07-12 16:41 ` Al Viro
2018-07-12 16:58 ` Al Viro
2018-07-12 17:54 ` Andy Lutomirski
2018-07-12 20:23 ` David Howells
2018-07-12 20:25 ` Andy Lutomirski
2018-07-12 20:34 ` Linus Torvalds
2018-07-12 20:36 ` Linus Torvalds
2018-07-12 21:26 ` David Howells
2018-07-12 21:40 ` Linus Torvalds
2018-07-12 22:32 ` Theodore Y. Ts'o
2018-07-12 22:54 ` David Howells
2018-07-12 23:21 ` Andy Lutomirski
2018-07-12 23:23 ` Jann Horn
2018-07-12 23:33 ` Jann Horn
2018-07-12 23:35 ` David Howells
2018-07-12 23:50 ` Andy Lutomirski
2018-07-13 0:03 ` David Howells
2018-07-13 0:24 ` Andy Lutomirski
2018-07-13 7:30 ` David Howells
2018-07-19 1:30 ` Eric W. Biederman
2018-07-13 2:35 ` Theodore Y. Ts'o
2018-07-12 21:00 ` David Howells
2018-07-12 21:29 ` Linus Torvalds
2018-07-13 13:27 ` David Howells
2018-07-13 15:01 ` Andy Lutomirski
2018-07-13 15:40 ` David Howells
2018-07-13 17:14 ` Andy Lutomirski
2018-07-17 9:40 ` David Howells
2018-07-11 15:51 ` Jonathan Corbet
2018-07-11 16:18 ` David Howells
2018-07-12 17:15 ` Greg KH
2018-07-12 17:20 ` Al Viro
2018-07-12 18:03 ` Greg KH
2018-07-12 18:30 ` Andy Lutomirski
2018-07-12 18:34 ` Al Viro
2018-07-12 18:35 ` Al Viro
2018-07-12 19:08 ` Greg KH
2018-07-10 22:44 ` [PATCH 25/32] vfs: syscall: Add fsmount() to create a mount for a superblock " David Howells
2018-07-10 22:44 ` [PATCH 26/32] vfs: syscall: Add fspick() to select a superblock for reconfiguration " David Howells
2018-07-10 22:44 ` [PATCH 27/32] vfs: Implement logging through fs_context " David Howells
2018-07-10 22:44 ` [PATCH 28/32] vfs: Add some logging to the core users of the fs_context log " David Howells
2018-07-10 22:44 ` [PATCH 29/32] afs: Add fs_context support " David Howells
2018-07-10 22:44 ` [PATCH 30/32] afs: Use fs_context to pass parameters over automount " David Howells
2018-07-10 22:44 ` [PATCH 31/32] vfs: syscall: Add fsinfo() to query filesystem information " David Howells
2018-07-10 22:45 ` [PATCH 32/32] afs: Add fsinfo support " David Howells
2018-07-10 22:52 ` [MANPAGE PATCH] Add manpages for move_mount(2) and open_tree(2) David Howells
2019-10-09 9:51 ` Michael Kerrisk (man-pages)
2018-07-10 22:54 ` David Howells [this message]
2019-10-09 9:52 ` [MANPAGE PATCH] Add manpage for fsopen(2), fspick(2) and fsmount(2) Michael Kerrisk (man-pages)
2018-07-10 22:55 ` [MANPAGE PATCH] Add manpage for fsinfo(2) David Howells
2019-10-09 9:52 ` Michael Kerrisk (man-pages)
2019-10-09 12:02 ` David Howells
2018-07-10 23:01 ` [PATCH 00/32] VFS: Introduce filesystem context [ver #9] Linus Torvalds
2018-07-12 0:46 ` David Howells
2018-07-18 21:29 ` Getting rid of the usage of write() -- was " David Howells
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=15488.1531263249@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=torvalds@linux-foundation.org \
--cc=viro@zeniv.linux.org.uk \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).