Linux-Fsdevel Archive on
help / color / mirror / Atom feed
From: David Howells <>
Subject: [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2)
Date: Mon, 24 Aug 2020 13:25:05 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

Add a manual page to document the fsopen() and fsmount() system calls.

Signed-off-by: David Howells <>

 man2/fsmount.2 |    1 
 man2/fsopen.2  |  245 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 246 insertions(+)
 create mode 100644 man2/fsmount.2
 create mode 100644 man2/fsopen.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 @@ man2/fsopen.2
diff --git a/man2/fsopen.2 b/man2/fsopen.2
new file mode 100644
index 000000000..1d1bba238
--- /dev/null
+++ b/man2/fsopen.2
@@ -0,0 +1,245 @@
+'\" t
+.\" Copyright (c) 2020 David Howells <>
+.\" 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.
+.TH FSOPEN 2 2020-08-07 "Linux" "Linux Programmer's Manual"
+fsopen, fsmount \- Filesystem parameterisation and mount creation
+.B #include <sys/types.h>
+.B #include <sys/mount.h>
+.B #include <unistd.h>
+.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BI "int fsopen(const char *" fsname ", unsigned int " flags );
+.BI "int fsmount(int " fd ", unsigned int " flags ", unsigned int " mount_attrs );
+.IR Note :
+There are no glibc wrappers for these system calls.
+.BR fsopen ()
+creates a blank filesystem configuration context within the kernel for the
+filesystem named in the
+.I fsname
+parameter, puts it into creation mode and attaches it to a file descriptor,
+which it then returns.  The file descriptor can be marked close-on-exec by
+.IR flags .
+After calling fsopen(), the file descriptor should be passed to the
+.BR fsconfig (2)
+system call, using that to specify the desired filesystem and security
+When the parameters are all set, the
+.BR fsconfig ()
+system call should then be called again with
+as the command argument to effect the creation.
+.BR "[!]\ NOTE" :
+Depending on the filesystem type and parameters, this may rather share an
+existing in-kernel filesystem representation instead of creating a new one.
+In such a case, the parameters specified may be discarded or may overwrite the
+parameters set by a previous mount - at the filesystem's discretion.
+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).
+Once the creation command has been successfully run on a context, the context
+will not accept further configuration.  At
+this point,
+.BR fsmount ()
+should be called to create a mount object.
+.BR fsmount ()
+takes the file descriptor returned by
+.BR fsopen ()
+and creates a mount object for the filesystem root specified there.  The
+attributes of the mount object are set from the
+.I mount_attrs
+parameter.  The attributes specify the propagation and mount restrictions to
+be applied to accesses through this mount.
+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.
+The file descriptor returned by fsmount() is marked close-on-exec if
+FSMOUNT_CLOEXEC is specified in
+.IR flags .
+After fsmount() has completed, the context created by fsopen() is reset and
+moved to reconfiguration state, allowing the new superblock to be
+reconfigured.  See
+.BR fspick (2)
+for details.
+To use either of these calls, the caller requires the appropriate privilege
+(Linux: the
+.SS Message Retrieval Interface
+The context file descriptor may be queried for message strings at any time by
+.BR read (2)
+on the file descriptor.  This will return formatted messages that are prefixed
+to indicate their class:
+\fB"e <message>"\fP
+An error message string was logged.
+\fB"i <message>"\fP
+An informational message string was logged.
+\fB"w <message>"\fP
+An warning message string was logged.
+Messages are removed from the queue as they're read.
+On success, both functions return a file descriptor.  On error, \-1 is
+returned, and
+.I errno
+is set appropriately.
+The error values given below result from filesystem type independent
+Each filesystem type may have its own special errors and its
+own special behavior.
+See the Linux kernel source code for details.
+The context referred to by
+.I fd
+is not in the right state to be used by
+.BR fsmount ().
+One of the pointer arguments points outside the user address space.
+.I flags
+had an invalid flag set.
+.I mount_attrs,
+includes invalid
+The system has too many open files to create more.
+The process has too many open files to create more.
+The filesystem
+.I fsname
+is not available in the kernel.
+The kernel could not allocate sufficient memory to complete the call.
+The caller does not have the required privileges.
+These functions are Linux-specific and should not be used in programs intended
+to be portable.
+.BR fsopen "(), and " fsmount ()
+were added to Linux in kernel 5.2.
+Glibc does not (yet) provide a wrapper for the
+.BR fsopen "() or " fsmount "()"
+system calls; call them using
+.BR syscall (2).
+To illustrate the process, here's an example whereby this can be used to mount
+an ext4 filesystem on /dev/sdb1 onto /mnt.
+.PP +4n
+sfd = fsopen("ext4", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "/dev/sdb1", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "noatime", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "user_attr", NULL, 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "iversion", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MS_RELATIME);
+move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+Here, an ext4 context is created first and attached to sfd.  The context is
+then told where its source will be, given a bunch of options and a superblock
+record object is then created.  Then fsmount() is called to create a mount
+object and
+.BR move_mount (2)
+is called to attach it to its intended mountpoint.
+And here's an example of mounting from an NFS server and setting a Smack
+security module label on it too:
+.PP +4n
+sfd = fsopen("nfs", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "nfsvers", "3", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "rsize", "65536", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "wsize", "65536", 0);
+fsconfig(sfd, FSCONFIG_SET_STRING, "smackfsdef", "foolabel", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "rdma", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+mfd = fsmount(sfd, 0, MS_NODEV);
+move_mount(mfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
+.BR mountpoint (1),
+.BR fsconfig (2),
+.BR fspick (2),
+.BR move_mount (2),
+.BR open_tree (2),
+.BR umount (2),
+.BR mount_namespaces (7),
+.BR path_resolution (7),
+.BR mount (8),
+.BR umount (8)

  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 ` David Howells [this message]
2020-08-27 11:07   ` [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2) 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 4/5] Add manpage for fsopen(2) and fsmount(2) David Howells
2020-08-22 20:08   ` 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:

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

  git send-email \ \ \ \ \ \ \ \ \
    --subject='Re: [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2)' \

* 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).