From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,SPF_PASS,WEIRD_QUOTING autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D384BC3279B for ; Tue, 10 Jul 2018 22:54:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 792072098B for ; Tue, 10 Jul 2018 22:54:15 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 792072098B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732358AbeGJWz3 convert rfc822-to-8bit (ORCPT ); Tue, 10 Jul 2018 18:55:29 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:40452 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1732246AbeGJWz3 (ORCPT ); Tue, 10 Jul 2018 18:55:29 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 54760400589B; Tue, 10 Jul 2018 22:54:11 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-149.rdu2.redhat.com [10.10.120.149]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3C50E2166BA2; Tue, 10 Jul 2018 22:54:10 +0000 (UTC) Organization: Red Hat UK Ltd. Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in England and Wales under Company Registration No. 3798903 From: David Howells In-Reply-To: <153126264966.14533.3388004240803696769.stgit@warthog.procyon.org.uk> References: <153126264966.14533.3388004240803696769.stgit@warthog.procyon.org.uk> <153126248868.14533.9751473662727327569.stgit@warthog.procyon.org.uk> 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 Subject: [MANPAGE PATCH] Add manpage for fsopen(2), fspick(2) and fsmount(2) MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <15487.1531263249.1@warthog.procyon.org.uk> Content-Transfer-Encoding: 8BIT Date: Tue, 10 Jul 2018 23:54:09 +0100 Message-ID: <15488.1531263249@warthog.procyon.org.uk> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Tue, 10 Jul 2018 22:54:11 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Tue, 10 Jul 2018 22:54:11 +0000 (UTC) for IP:'10.11.54.6' DOMAIN:'int-mx06.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'dhowells@redhat.com' RCPT:'' Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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