From patchwork Wed Mar 19 19:06:50 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Herrmann X-Patchwork-Id: 3860391 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id B6E0DBF540 for ; Wed, 19 Mar 2014 19:08:06 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id C9C95201FA for ; Wed, 19 Mar 2014 19:08:05 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id DDF86201F5 for ; Wed, 19 Mar 2014 19:08:04 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 3299289739; Wed, 19 Mar 2014 12:08:04 -0700 (PDT) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-bk0-f49.google.com (mail-bk0-f49.google.com [209.85.214.49]) by gabe.freedesktop.org (Postfix) with ESMTP id A93908972D for ; Wed, 19 Mar 2014 12:08:02 -0700 (PDT) Received: by mail-bk0-f49.google.com with SMTP id my13so606352bkb.8 for ; Wed, 19 Mar 2014 12:08:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=DIx7FHQfhA3aAN5Tfon1RMlNANx4TH0iBxlesWwoGFU=; b=MYG78xcY1JffFyPzOCKPgJWWTIJUi4QQxp8nnXZKFyaZDYXlb1s1qM+9RQqebpdd8X 6ncaJ6vCGjy4P1wadljV3QGWtIpyJoVrOwf0K8mCu+92lfRAtKx/rTqA9T/lbgB9n8Ji eBWOirbaGU+pjLmYvtEO4RGFXDUPrF0Behdkrh3R5+n+vMLcPdP8EuEXXfrVWDYGJbBN RVzsBAJpjW/s0L2NVmEtBH7jFP0xEPRCDc+Zt9TwgNWSTlFTQ2VfCW3EudpP7ay3oCHc gOh+J8B/Cakdk+sk0464Oi/OUtH2/GSjJBv1USIdTjxdDWbEsxcLXXir6kPRz7FKysrQ IWqw== X-Received: by 10.204.165.207 with SMTP id j15mr66399bky.45.1395256081885; Wed, 19 Mar 2014 12:08:01 -0700 (PDT) Received: from david-tp.localdomain (stgt-5f71aff2.pool.mediaWays.net. [95.113.175.242]) by mx.google.com with ESMTPSA id c15sm20566146bky.13.2014.03.19.12.07.59 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 19 Mar 2014 12:08:00 -0700 (PDT) From: David Herrmann To: linux-kernel@vger.kernel.org Subject: [PATCH man-pages 5/6] fcntl.2: document SHMEM_SET/GET_SEALS commands Date: Wed, 19 Mar 2014 20:06:50 +0100 Message-Id: <1395256011-2423-6-git-send-email-dh.herrmann@gmail.com> X-Mailer: git-send-email 1.9.0 In-Reply-To: <1395256011-2423-1-git-send-email-dh.herrmann@gmail.com> References: <1395256011-2423-1-git-send-email-dh.herrmann@gmail.com> Cc: Matthew Wilcox , Ryan Lortie , Hugh Dickins , Johannes Weiner , Kay Sievers , dri-devel@lists.freedesktop.org, Daniel Mack , linux-mm@kvack.org, linux-fsdevel@vger.kernel.org, Karol Lewandowski , Lennart Poettering , Greg Kroah-Hartman , Tejun Heo , "Michael Kerrisk \(man-pages\)" , Andrew Morton , Linus Torvalds , Alexander Viro X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_MED, T_DKIM_INVALID, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The SHMEM_GET_SEALS and SHMEM_SET_SEALS commands allow retrieving and modifying the active set of seals on a file. They're only supported on selected file-systems (currently shmfs) and are linux-only. Signed-off-by: David Herrmann --- man2/fcntl.2 | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/man2/fcntl.2 b/man2/fcntl.2 index c010a49..53d55a5 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -57,6 +57,8 @@ .\" Document F_SETOWN_EX and F_GETOWN_EX .\" 2010-06-17, Michael Kerrisk .\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. +.\" 2014-03-19, David Herrmann +.\" Document SHMEM_SET_SEALS and SHMEM_GET_SEALS .\" .TH FCNTL 2 2014-02-20 "Linux" "Linux Programmer's Manual" .SH NAME @@ -1064,6 +1066,94 @@ of buffer space currently used to store data produces the error .BR F_GETPIPE_SZ " (\fIvoid\fP; since Linux 2.6.35)" Return (as the function result) the capacity of the pipe referred to by .IR fd . +.SS File Sealing +Sealing files limits the set of allowed operations on a given file. For each +seal that is set on a file, a specific set of operations will fail with +.B EPERM +on this file from now on. The file is said to be sealed. A file does not have +any seals set by default. Moreover, most filesystems do not support sealing +(only shmfs implements it right now). The following seals are available: +.RS +.TP +.BR SHMEM_SEAL_SHRINK +If this seal is set, the file in question cannot be reduced in size. This +affects +.BR open (2) +with the +.B O_TRUNC +flag and +.BR ftruncate (2). +They will fail with +.B EPERM +if you try to shrink the file in question. Increasing the file size is still +possible. +.TP +.BR SHMEM_SEAL_GROW +If this seal is set, the size of the file in question cannot be increased. This +affects +.BR write (2) +if you write across size boundaries, +.BR ftruncate (2) +and +.BR fallocate (2). +These calls will fail with +.B EPERM +if you use them to increase the file size or write beyond size boundaries. If +you keep the size or shrink it, those calls still work as expected. +.TP +.BR SHMEM_SEAL_WRITE +If this seal is set, you cannot modify data contents of the file. Note that +shrinking or growing the size of the file is still possible and allowed. Thus, +this seal is normally used in combination with one of the other seals. This seal +affects +.BR write (2) +and +.BR fallocate (2) +(only in combination with the +.B FALLOC_FL_PUNCH_HOLE +flag). Those calls will fail with +.B EPERM +if this seal is set. Furthermore, trying to create new memory-mappings via +.BR mmap (2) +in combination with +.B MAP_SHARED +will also fail with +.BR EPERM . +.RE +.TP +.BR SHMEM_SET_SEALS " (\fIint\fP; since Linux TBD)" +Change the set of seals of the file referred to by +.I fd +to +.IR arg . +You are required to own an exclusive reference to the file in question in order +to modify the seals. Otherwise, this call will fail with +.BR EPERM . +There is one exception: If no seals are set, this restriction does not apply and +you can set seals even if you don't own an exclusive reference. However, in any +case there may not exist any shared writable mapping or this call will always +fail with +.BR EPERM . +These semantics guarantee that once you verified a specific set of seals is set +on a given file, nobody besides you (in case you own an exclusive reference) can +modify the seals, anymore. + +You own an exclusive reference to a file if, and only if, the file-descriptor +passed to +.BR fcntl (2) +is the only reference to the underlying inode. There must not be any duplicates +of this file-descriptor, no other open files to the same underlying inode, no +hard-links or any active memory mappings. +.TP +.BR SHMEM_GET_SEALS " (\fIvoid\fP; since Linux TBD)" +Return (as the function result) the current set of seals of the file referred to +by +.IR fd . +If no seals are set, 0 is returned. If the file does not support sealing, -1 is +returned and +.I errno +is set to +.BR EINVAL . .SH RETURN VALUE For a successful call, the return value depends on the operation: .TP 0.9i