From mboxrd@z Thu Jan 1 00:00:00 1970 From: David Howells Subject: [MANPAGE PATCH] Add manpage for fsopen(2), fspick(2) and fsmount(2) Date: Tue, 10 Jul 2018 23:54:09 +0100 Message-ID: <15488.1531263249@warthog.procyon.org.uk> References: <153126264966.14533.3388004240803696769.stgit@warthog.procyon.org.uk> <153126248868.14533.9751473662727327569.stgit@warthog.procyon.org.uk> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 8BIT Return-path: In-Reply-To: <153126264966.14533.3388004240803696769.stgit@warthog.procyon.org.uk> Content-ID: <15487.1531263249.1@warthog.procyon.org.uk> Sender: linux-kernel-owner@vger.kernel.org To: Michael Kerrisk 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 List-Id: linux-man@vger.kernel.org Archived-At: List-Archive: List-Post: Add a manual page to document the fsopen(), fspick() and fsmount() system calls. Signed-off-by: David Howells --- 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 +.\" +.\" %%%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 +.br +.B #include +.br +.B #include +.br +.BR "#include " "/* 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