From patchwork Mon Aug 24 12:24:42 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 11733067 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 70130739 for ; Mon, 24 Aug 2020 12:26:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 5163820838 for ; Mon, 24 Aug 2020 12:26:13 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="h+bSioct" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726747AbgHXMYw (ORCPT ); Mon, 24 Aug 2020 08:24:52 -0400 Received: from us-smtp-2.mimecast.com ([207.211.31.81]:33036 "EHLO us-smtp-delivery-1.mimecast.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1726502AbgHXMYv (ORCPT ); Mon, 24 Aug 2020 08:24:51 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1598271888; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=0ezayPHJbCOH4Sek4r/KNUEKU/MLNOPoHBQLgHtZxKo=; b=h+bSioctpiEDyr5XqVe2IdwHguIdUX6dviZzpKi9B8uPwvPo2lby18qBTAYFLzc2uMWivp MwaOThwN3LCQYR5Qt43aCYWztXqpRtTSCTIjxeH7yxgmqqqMMn13BcxVPUse3YGzUUymWx zfCfzk7Tn/0fLEzdvhekvsq1tVA5Qmo= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-165-fiy4duNVMBGzw8eSnoevFA-1; Mon, 24 Aug 2020 08:24:46 -0400 X-MC-Unique: fiy4duNVMBGzw8eSnoevFA-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 034B680734E; Mon, 24 Aug 2020 12:24:45 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-127.rdu2.redhat.com [10.10.120.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id 82957197E5; Mon, 24 Aug 2020 12:24:43 +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 Subject: [PATCH 1/5] Add manpage for open_tree(2) From: David Howells 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 Date: Mon, 24 Aug 2020 13:24:42 +0100 Message-ID: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.23 MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org Add a manual page to document the open_tree() system call. Signed-off-by: David Howells --- man2/open_tree.2 | 249 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 man2/open_tree.2 diff --git a/man2/open_tree.2 b/man2/open_tree.2 new file mode 100644 index 000000000..d480bd82f --- /dev/null +++ b/man2/open_tree.2 @@ -0,0 +1,249 @@ +'\" t +.\" Copyright (c) 2020 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 OPEN_TREE 2 2020-08-24 "Linux" "Linux Programmer's Manual" +.SH NAME +open_tree \- Pick or clone mount object and attach to fd +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.BR "#include " "/* Definition of AT_* constants */" +.PP +.BI "int open_tree(int " dirfd ", const char *" pathname ", unsigned int " flags ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls. +.SH DESCRIPTION +.BR open_tree () +picks the mount object specified by the pathname and attaches it to a new file +descriptor or clones it and attaches the clone to the file descriptor. The +resultant file descriptor is indistinguishable from one produced by +.BR open "(2) with " O_PATH . +.PP +In the case that the mount object is cloned, the clone will be "unmounted" and +destroyed when the file descriptor is closed if it is not otherwise mounted +somewhere by calling +.BR move_mount (2). +.PP +To select a mount object, no permissions are required on the object referred +to by the path, but execute (search) permission is required on all of the +directories in +.I pathname +that lead to the object. +.PP +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to clone mount objects. +.PP +.BR open_tree () +uses +.IR pathname ", " dirfd " and " flags +to locate the target object in one of a variety of ways: +.TP +[*] By absolute path. +.I pathname +points to an absolute path and +.I dirfd +is ignored. The object is looked up by name, starting from the root of the +filesystem as seen by the calling process. +.TP +[*] By cwd-relative path. +.I pathname +points to a relative path and +.IR dirfd " is " AT_FDCWD . +The object is looked up by name, starting from the current working directory. +.TP +[*] By dir-relative path. +.I pathname +points to relative path and +.I dirfd +indicates a file descriptor pointing to a directory. The object is looked up +by name, starting from the directory specified by +.IR dirfd . +.TP +[*] By file descriptor. +.I pathname +is "", +.I dirfd +indicates a file descriptor and +.B AT_EMPTY_PATH +is set in +.IR flags . +The mount attached to the file descriptor is queried directly. The file +descriptor may point to any type of file, not just a directory. +.PP +.I flags +can be used to control the operation of the function and to influence a +path-based lookup. A value for +.I flags +is constructed by OR'ing together zero or more of the following constants: +.TP +.BR AT_EMPTY_PATH +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.IR dirfd +(which may have been obtained from +.BR open "(2) with" +.BR O_PATH ", from " fsmount (2) +or from another +.BR open_tree ()). +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +In this case, +.I dirfd +can refer to any type of file, not just a directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_NO_AUTOMOUNT +Don't automount the final ("basename") component of +.I pathname +if it is a directory that is an automount point. This flag allows the +automount point itself to be picked up or a mount cloned that is rooted on the +automount point. The +.B AT_NO_AUTOMOUNT +flag has no effect if the mount point has already been mounted over. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: instead pick up or clone a mount +rooted on the link itself. +.TP +.B OPEN_TREE_CLOEXEC +Set the close-on-exec flag for the new file descriptor. This will cause the +file descriptor to be closed automatically when a process exec's. +.TP +.B OPEN_TREE_CLONE +Rather than directly attaching the selected object to the file descriptor, +clone the object, set the root of the new mount object to that point and +attach the clone to the file descriptor. +.TP +.B AT_RECURSIVE +This is only permitted in conjunction with OPEN_TREE_CLONE. It causes the +entire mount subtree rooted at the selected spot to be cloned rather than just +that one mount object. +.SH RETURN VALUE +On success, the new file descriptor is returned. On error, \-1 is returned, +and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I dirfd +is not a valid open file descriptor. +.TP +.B EFAULT +.I pathname +is NULL or +.IR pathname +point to a location outside the process's accessible address space. +.TP +.B EINVAL +Reserved flag specified in +.IR flags . +.TP +.B ELOOP +Too many symbolic links encountered while traversing the pathname. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist, or +.I pathname +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +is not a directory or +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR open_tree () +was added to Linux in kernel 5.2. +.SH CONFORMING TO +.BR open_tree () +is Linux-specific. +.SH NOTES +Glibc does not (yet) provide a wrapper for the +.BR open_tree () +system call; call it using +.BR syscall (2). +.SH EXAMPLE +The +.BR open_tree () +function can be used like the following: +.PP +.RS +.nf +fd1 = open_tree(AT_FDCWD, "/mnt", 0); +fd2 = open_tree(fd1, "", + AT_EMPTY_PATH | OPEN_TREE_CLONE | AT_RECURSIVE); +move_mount(fd2, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH); +.fi +.RE +.PP +This would attach the path point for "/mnt" to fd1, then it would copy the +entire subtree at the point referred to by fd1 and attach that to fd2; lastly, +it would attach the clone to "/mnt2". +.SH SEE ALSO +.BR fsmount (2), +.BR move_mount (2), +.BR open (2) From patchwork Mon Aug 24 12:24:50 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 11733059 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 8C851739 for ; Mon, 24 Aug 2020 12:25:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 67A6921741 for ; Mon, 24 Aug 2020 12:25:24 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="MMagacSV" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727039AbgHXMZV (ORCPT ); Mon, 24 Aug 2020 08:25:21 -0400 Received: from us-smtp-1.mimecast.com ([205.139.110.61]:28346 "EHLO us-smtp-delivery-1.mimecast.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1726825AbgHXMY6 (ORCPT ); Mon, 24 Aug 2020 08:24:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1598271896; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+d95Pyxxs3w7EuizFdEpLYSASJLAlQyWQNxxnlomYro=; b=MMagacSVTGwZGzCgXqc1WTnhrm32FGVxVxZqJe9HN2d28KqOjrC7kZtxVyeqO073DEn5q8 /Dt5f+IySIBh4LDm7lZ4kkqX5DEdFjLrn/dJV0A+bxQ6SxZCk5SOk8BIibJy7INteCBAvF Prfv/UAIonkofsL/lfyxRt3R6JtxsYc= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-328-2iQFX1_IPnuZkCEVfhg__Q-1; Mon, 24 Aug 2020 08:24:54 -0400 X-MC-Unique: 2iQFX1_IPnuZkCEVfhg__Q-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6C3991084C89; Mon, 24 Aug 2020 12:24:52 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-127.rdu2.redhat.com [10.10.120.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0B06D10098AE; Mon, 24 Aug 2020 12:24:50 +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 Subject: [PATCH 2/5] Add manpages for move_mount(2) From: David Howells 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 Date: Mon, 24 Aug 2020 13:24:50 +0100 Message-ID: <159827189025.306468.4916341547843731338.stgit@warthog.procyon.org.uk> In-Reply-To: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> References: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.23 MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org Add manual pages to document the move_mount() system call. Signed-off-by: David Howells --- man2/move_mount.2 | 267 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 man2/move_mount.2 diff --git a/man2/move_mount.2 b/man2/move_mount.2 new file mode 100644 index 000000000..2ceb775d9 --- /dev/null +++ b/man2/move_mount.2 @@ -0,0 +1,267 @@ +'\" t +.\" Copyright (c) 2020 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 MOVE_MOUNT 2 2020-08-24 "Linux" "Linux Programmer's Manual" +.SH NAME +move_mount \- Move mount objects around the filesystem topology +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.BR "#include " "/* Definition of AT_* constants */" +.PP +.BI "int move_mount(int " from_dirfd ", const char *" from_pathname "," +.BI " int " to_dirfd ", const char *" to_pathname "," +.BI " unsigned int " flags ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call. +.SH DESCRIPTION +The +.BR move_mount () +call moves a mount from one place to another; it can also be used to attach an +unattached mount that was created by +.BR fsmount "() or " open_tree "() with " OPEN_TREE_CLONE . +.PP +If +.BR move_mount () +is called repeatedly with a file descriptor that refers to a mount object, +then the object will be attached/moved the first time and then moved +repeatedly, detaching it from the previous mountpoint each time. +.PP +To access the source mount object or the destination mountpoint, no +permissions are required on the object itself, but if either pathname is +supplied, execute (search) permission is required on all of the directories +specified in +.IR from_pathname " or " to_pathname . +.PP +The caller does, however, require the appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) to move or attach mounts. +.PP +.BR move_mount () +uses +.IR from_pathname ", " from_dirfd " and part of " flags +to locate the mount object to be moved and +.IR to_pathname ", " to_dirfd " and another part of " flags +to locate the destination mountpoint. Each lookup can be done in one of a +variety of ways: +.TP +[*] By absolute path. +The pathname points to an absolute path and the dirfd is ignored. The file is +looked up by name, starting from the root of the filesystem as seen by the +calling process. +.TP +[*] By cwd-relative path. +The pathname points to a relative path and the dirfd is +.IR AT_FDCWD . +The file is looked up by name, starting from the current working directory. +.TP +[*] By dir-relative path. +The pathname points to relative path and the dirfd indicates a file descriptor +pointing to a directory. The file is looked up by name, starting from the +directory specified by +.IR dirfd . +.TP +[*] By file descriptor. The pathname is an empty string (""), the dirfd +points directly to the mount object to move or the destination mount point and +the appropriate +.B *_EMPTY_PATH +flag is set. +.PP +.I flags +can be used to influence a path-based lookup. The value for +.I flags +is constructed by OR'ing together zero or more of the following constants: +.TP +.BR MOVE_MOUNT_F_EMPTY_PATH +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I from_pathname +is an empty string, operate on the file referred to by +.IR from_dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag or +.BR open_tree ()) +If +.I from_dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +In this case, +.I from_dirfd +can refer to any type of file, not just a directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B MOVE_MOUNT_T_EMPTY_PATH +As above, but operating on +.IR to_pathname " and " to_dirfd . +.TP +.B MOVE_MOUNT_F_AUTOMOUNTS +Don't automount the terminal ("basename") component of +.I from_pathname +if it is a directory that is an automount point. This allows a mount object +that has an automount point at its root to be moved and prevents unintended +triggering of an automount point. +The +.B MOVE_MOUNT_F_AUTOMOUNTS +flag has no effect if the automount point has already been mounted over. This +flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B MOVE_MOUNT_T_AUTOMOUNTS +As above, but operating on +.IR to_pathname " and " to_dirfd . +This allows an automount point to be manually mounted over. +.TP +.B MOVE_MOUNT_F_SYMLINKS +If +.I from_pathname +is a symbolic link, then dereference it. The default for +.BR move_mount () +is to not follow symlinks. +.TP +.B MOVE_MOUNT_T_SYMLINKS +As above, but operating on +.IR to_pathname " and " to_dirfd . +.SH RETURN VALUE +On success, 0 is returned. On error, \-1 is returned, and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.IR from_dirfd " or " to_dirfd +is not a valid open file descriptor. +.TP +.B EFAULT +.IR from_pathname " or " to_pathname +is NULL or either one point to a location outside the process's accessible +address space. +.TP +.B EINVAL +Reserved flag specified in +.IR flags . +.TP +.B ELOOP +Too many symbolic links encountered while traversing the pathname. +.TP +.B ENAMETOOLONG +.IR from_pathname " or " to_pathname +is too long. +.TP +.B ENOENT +A component of +.IR from_pathname " or " to_pathname +does not exist, or one is an empty string and the appropriate +.B *_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.IR from_pathname " or " to_pathname +is not a directory or one or the other is relative and the appropriate +.I *_dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR move_mount () +was added to Linux in kernel 5.2. +.SH CONFORMING TO +.BR move_mount () +is Linux-specific. +.SH NOTES +Glibc does not (yet) provide a wrapper for the +.BR move_mount () +system call; call it using +.BR syscall (2). +.SH EXAMPLES +The +.BR move_mount () +function can be used like the following: +.PP +.RS +.nf +move_mount(AT_FDCWD, "/a", AT_FDCWD, "/b", 0); +.fi +.RE +.PP +This would move the object mounted on "/a" to "/b". It can also be used in +conjunction with +.BR open_tree "(2) or " open "(2) with " O_PATH : +.PP +.RS +.nf +fd = open_tree(AT_FDCWD, "/mnt", 0); +move_mount(fd, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH); +move_mount(fd, "", AT_FDCWD, "/mnt3", MOVE_MOUNT_F_EMPTY_PATH); +move_mount(fd, "", AT_FDCWD, "/mnt4", MOVE_MOUNT_F_EMPTY_PATH); +.fi +.RE +.PP +This would attach the path point for "/mnt" to fd, then it would move the +mount to "/mnt2", then move it to "/mnt3" and finally to "/mnt4". +.PP +It can also be used to attach new mounts: +.PP +.RS +.nf +sfd = fsopen("ext4", FSOPEN_CLOEXEC); +fsconfig(sfd, FSCONFIG_SET_STRING, "source", "/dev/sda1", 0); +fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0); +fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0); +mfd = fsmount(sfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NODEV); +move_mount(mfd, "", AT_FDCWD, "/home", MOVE_MOUNT_F_EMPTY_PATH); +.fi +.RE +.PP +Which would open the Ext4 filesystem mounted on "/dev/sda1", turn on user +extended attribute support and create a mount object for it. Finally, the new +mount object would be attached with +.BR move_mount () +to "/home". +.SH SEE ALSO +.BR fsmount (2), +.BR fsopen (2), +.BR open_tree (2) From patchwork Mon Aug 24 12:24:57 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 11733065 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 534F8739 for ; Mon, 24 Aug 2020 12:26:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 35EFE2078D for ; Mon, 24 Aug 2020 12:26:07 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="QOX7hFSx" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727103AbgHXMZ4 (ORCPT ); Mon, 24 Aug 2020 08:25:56 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:49216 "EHLO us-smtp-delivery-124.mimecast.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726795AbgHXMZJ (ORCPT ); Mon, 24 Aug 2020 08:25:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1598271905; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PlDXYkMf8XCvclTdTig9DMVLeOaWXFPXZoOvIMWb/Bg=; b=QOX7hFSxcv55FHfc8PL/MIQE6s8QqcASeg3+D9LkCgkUsXc//COHbBX4OLZjRNT08fMSuj S1/2DTP5X6Kxn9TPvg40oS8oh45gmO1UCCc4SZLKcPRegzRslRE6HBnAkjwxpmTLXs2FKk c+xsrdlrMEsBYsaopY4LQTKYiLbPVIc= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-54-rTfguJBhNXu0qjvWlWWvWQ-1; Mon, 24 Aug 2020 08:25:01 -0400 X-MC-Unique: rTfguJBhNXu0qjvWlWWvWQ-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D3D6681F008; Mon, 24 Aug 2020 12:24:59 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-127.rdu2.redhat.com [10.10.120.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id 73B2F7C869; Mon, 24 Aug 2020 12:24:58 +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 Subject: [PATCH 3/5] Add manpage for fspick(2) From: David Howells 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 Date: Mon, 24 Aug 2020 13:24:57 +0100 Message-ID: <159827189767.306468.1803062787718957199.stgit@warthog.procyon.org.uk> In-Reply-To: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> References: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.23 MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org Add a manual page to document the fspick() system call. Signed-off-by: David Howells --- man2/fspick.2 | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 man2/fspick.2 diff --git a/man2/fspick.2 b/man2/fspick.2 new file mode 100644 index 000000000..72bf645dd --- /dev/null +++ b/man2/fspick.2 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2020 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 FSPICK 2 2020-08-24 "Linux" "Linux Programmer's Manual" +.SH NAME +fspick \- Select filesystem for reconfiguration +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.BR "#include " "/* Definition of AT_* constants */" +.PP +.BI "int fspick(int " dirfd ", const char *" pathname ", unsigned int " flags ); +.fi +.PP +.IR Note : +There is no glibc wrapper for this system call. +.SH DESCRIPTION +.PP +.BR fspick () +creates a new filesystem configuration context within the kernel and attaches a +pre-existing superblock to it so that it can be reconfigured (similar to +.BR mount (8) +with the "-o remount" option). The configuration context is marked as being in +reconfiguration mode and attached to a file descriptor, which is returned to +the caller. The file descriptor can be marked close-on-exec by setting +.B FSPICK_CLOEXEC +in +.IR flags . +.PP +The target is whichever superblock backs the object determined by +.IR dfd ", " pathname " and " flags . +The following can be set in +.I flags +to control the pathwalk to that object: +.TP +.B FSPICK_SYMLINK_NOFOLLOW +Don't follow symbolic links in the final component of the path. +.TP +.B FSPICK_NO_AUTOMOUNT +Don't follow automounts in the final component of the path. +.TP +.B FSPICK_EMPTY_PATH +Allow an empty string to be specified as the pathname. This allows +.I dirfd +to specify the target mount exactly. +.PP +After calling fspick(), the file descriptor should be passed to the +.BR fsconfig (2) +system call, using that to specify the desired changes to filesystem and +security parameters. +.PP +When the parameters are all set, the +.BR fsconfig () +system call should then be called again with +.B FSCONFIG_CMD_RECONFIGURE +as the command argument to effect the reconfiguration. +.PP +After the reconfiguration has taken place, the context is wiped clean (apart +from the superblock attachment, which remains) and can be reused to make +another reconfiguration. +.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). +.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 "\fP +An error message string was logged. +.TP +\fB"i "\fP +An informational message string was logged. +.TP +\fB"w "\fP +An warning message string was logged. +.PP +Messages are removed from the queue as they're read and the queue has a limited +depth of 8 messages, so it's possible for some to get lost. +.SH RETURN VALUE +On success, the function returns 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. +Additionally, 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 EFAULT +.I pathname +points outside the user address space. +.TP +.B EINVAL +.I flags +includes an undefined value. +.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 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 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 5.2. +.SH EXAMPLES +To illustrate the process, here's an example whereby this can be used to +reconfigure a filesystem: +.PP +.in +4n +.nf +sfd = fspick(AT_FDCWD, "/mnt", FSPICK_NO_AUTOMOUNT | FSPICK_CLOEXEC); +fsconfig(sfd, FSCONFIG_SET_FLAG, "ro", NULL, 0); +fsconfig(sfd, FSCONFIG_SET_STRING, "user_xattr", "false", 0); +fsconfig(sfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0); +.fi +.in +.PP +.SH NOTES +Glibc does not (yet) provide a wrapper for the +.BR fspick "()" +system call; call it using +.BR syscall (2). +.SH SEE ALSO +.BR mountpoint (1), +.BR fsconfig (2), +.BR fsopen (2), +.BR path_resolution (7), +.BR mount (8) From patchwork Mon Aug 24 12:25:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 11733063 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 31DA5739 for ; Mon, 24 Aug 2020 12:25:48 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0E07D20838 for ; Mon, 24 Aug 2020 12:25:48 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="MTCtZ0PW" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727021AbgHXMZp (ORCPT ); Mon, 24 Aug 2020 08:25:45 -0400 Received: from us-smtp-1.mimecast.com ([207.211.31.81]:47285 "EHLO us-smtp-delivery-1.mimecast.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1726972AbgHXMZO (ORCPT ); Mon, 24 Aug 2020 08:25:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1598271912; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hi1whHHeAhV121Ie5VqRINib5kFTKjdPsVRsKEDgwWg=; b=MTCtZ0PWzyZOeboJMRNqAdGOv0y4TD6u4WpRE6twAR5/bkjeLcbA35UJM6Y9rqe5n0Md9O DLAnHxPEo+79toRGXN8Kc5WlnfP6wiNVeeILx7aE02pydfpX2PE8vsOGIDm6IZu16zTMYB Ow3fFTZ3kItECkeVzHPtv9VfvQktOng= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-397-ORbl5fBGN_y1HB3YkgKZhQ-1; Mon, 24 Aug 2020 08:25:08 -0400 X-MC-Unique: ORbl5fBGN_y1HB3YkgKZhQ-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3C1F318A2245; Mon, 24 Aug 2020 12:25:07 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-127.rdu2.redhat.com [10.10.120.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id CAA9C5D9E4; Mon, 24 Aug 2020 12:25:05 +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 Subject: [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2) From: David Howells 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 Date: Mon, 24 Aug 2020 13:25:05 +0100 Message-ID: <159827190508.306468.12755090833140558156.stgit@warthog.procyon.org.uk> In-Reply-To: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> References: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.23 MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org 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 @@ +.so 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 +.\" +.\" %%%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 2020-08-07 "Linux" "Linux Programmer's Manual" +.SH NAME +fsopen, fsmount \- Filesystem parameterisation and mount creation +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.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 " mount_attrs ); +.fi +.PP +.IR Note : +There are no glibc wrappers for these system calls. +.SH DESCRIPTION +.PP +.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 +setting +.B FSOPEN_CLOEXEC +in +.IR flags . +.PP +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 +parameters. +.PP +When the parameters are all set, the +.BR fsconfig () +system call should then be called again with +.B FSCONFIG_CMD_CREATE +as the command argument to effect the creation. +.RS +.PP +.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. +.RE +.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 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. +.PP +.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. +.PP +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. See +.BR fspick (2) +for details. +.PP +To use either of these calls, the caller requires the appropriate privilege +(Linux: the +.B CAP_SYS_ADMIN +capability). +.PP +.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 "\fP +An error message string was logged. +.TP +\fB"i "\fP +An informational message string was logged. +.TP +\fB"w "\fP +An warning message string was logged. +.PP +Messages are removed from the queue as they're read. +.SH RETURN VALUE +On success, both 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 EBUSY +The context referred to by +.I fd +is not in the right state to be used by +.BR fsmount (). +.TP +.B EFAULT +One of the pointer arguments points outside the user address space. +.TP +.B EINVAL +.I flags +had an invalid flag set. +.TP +.B EINVAL +.I mount_attrs, +includes invalid +.BR MOUNT_ATTR_* +flags. +.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 ENODEV +The filesystem +.I fsname +is not available in the kernel. +.TP +.B ENOMEM +The kernel could not allocate sufficient memory to complete the call. +.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 "(), and " fsmount () +were added to Linux in kernel 5.2. +.SH NOTES +Glibc does not (yet) provide a wrapper for the +.BR fsopen "() or " fsmount "()" +system calls; call them using +.BR syscall (2). +.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. +.PP +.in +4n +.nf +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); +.fi +.in +.PP +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. +.PP +And here's an example of mounting from an NFS server and setting a Smack +security module label on it too: +.PP +.in +4n +.nf +sfd = fsopen("nfs", 0); +fsconfig(sfd, FSCONFIG_SET_STRING, "source", "example.com:/pub", 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); +.fi +.in +.PP +.SH SEE ALSO +.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) From patchwork Mon Aug 24 12:25:12 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Howells X-Patchwork-Id: 11733061 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 4B9D2739 for ; Mon, 24 Aug 2020 12:25:34 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2ADB020838 for ; Mon, 24 Aug 2020 12:25:34 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="cVxiidc/" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727063AbgHXMZc (ORCPT ); Mon, 24 Aug 2020 08:25:32 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:38191 "EHLO us-smtp-delivery-124.mimecast.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727017AbgHXMZX (ORCPT ); Mon, 24 Aug 2020 08:25:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1598271917; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=YIrUagrIHqVugLe9LDIcRiclQwViyPRhpo0ZeXWbh6s=; b=cVxiidc/ZTFldY8wazzvc3ZbWJm/j0NUpePha6UErGAyVBC/f2ybDaKmYeiekTrubJE4MU J5gIXimJM2R8x03JGkwI/syUpao4T5H4Pbop02efE/+NMSWOoXZOiKrfX1Wl+wIk4/ChbX uHIZyi07kORlP360hB81hgBaJnRzOb8= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-80-wtioiY04O42CHdMewKloVA-1; Mon, 24 Aug 2020 08:25:15 -0400 X-MC-Unique: wtioiY04O42CHdMewKloVA-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A0D3764085; Mon, 24 Aug 2020 12:25:14 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-127.rdu2.redhat.com [10.10.120.127]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3EC3F60BF1; Mon, 24 Aug 2020 12:25:13 +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 Subject: [PATCH 5/5] Add manpage for fsconfig(2) From: David Howells 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 Date: Mon, 24 Aug 2020 13:25:12 +0100 Message-ID: <159827191245.306468.4903071494263813779.stgit@warthog.procyon.org.uk> In-Reply-To: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> References: <159827188271.306468.16962617119460123110.stgit@warthog.procyon.org.uk> User-Agent: StGit/0.23 MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org Add a manual page to document the fsconfig() system call. Signed-off-by: David Howells --- 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 +.\" +.\" %%%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 +.B #include +.B #include +.B #include +.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)