From patchwork Wed Dec 2 12:03:10 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 41256 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 1C9D9395B82A; Wed, 2 Dec 2020 12:03:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 1C9D9395B82A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1606910599; bh=4JfQJci5zifOKWa8ocnIhqSsIQ8JzXg/Yax/eH0sJe8=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=pfcbu+iHjOHcvAmIkDoW6+ypb4xNGO/sQauN1pg+nJqLTXk8HyBCYe7RN1q7AndDf ZJy1zwR9BUMzs5ZRual7h8lJb5YJ2pbaL/JVJ/98fl+YbjbQoLjablm5BKSZRd3YWD NGWvJcudpwcxvV7AZS12sjcsD/7fo5fw7OkKwbn4= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by sourceware.org (Postfix) with ESMTP id E51A63857806 for ; Wed, 2 Dec 2020 12:03:16 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org E51A63857806 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-582-0AdC-7E0Ph-vkpVTws4Qow-1; Wed, 02 Dec 2020 07:03:14 -0500 X-MC-Unique: 0AdC-7E0Ph-vkpVTws4Qow-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 2D13F185E496; Wed, 2 Dec 2020 12:03:13 +0000 (UTC) Received: from oldenburg2.str.redhat.com (ovpn-112-44.ams2.redhat.com [10.36.112.44]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 50C845D9C6; Wed, 2 Dec 2020 12:03:12 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH v2] manual: Clarify File Access Modes section and add O_PATH Date: Wed, 02 Dec 2020 13:03:10 +0100 Message-ID: <87lfeg8lfl.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.8 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Cc: "Michael Kerrisk \(man-pages\)" Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Kees Cook reported that the current text is misleading: --- Changes in v2: I picked up Michael's suggestions and tried to get it right when masking with O_ACCMODE works and when it does not. manual/llio.texi | 70 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/manual/llio.texi b/manual/llio.texi index 6db4a70836..75a2fe685c 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -3564,9 +3564,8 @@ The symbols in this section are defined in the header file @subsection File Access Modes The file access modes allow a file descriptor to be used for reading, -writing, or both. (On @gnuhurdsystems{}, they can also allow none of these, -and allow execution of the file as a program.) The access modes are chosen -when the file is opened, and never change. +writing, both, or neither. The access modes are chosen when the file +is opened, and never change. @deftypevr Macro int O_RDONLY @standards{POSIX.1, fcntl.h} @@ -3583,7 +3582,43 @@ Open the file for write access. Open the file for both reading and writing. @end deftypevr -On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and +@deftypevr Macro int O_PATH +@standards{Linux, fcntl.h} +Obtain a file descriptor for the file, but do not open this file for +reading or writing. Permission checks for the file itself are skipped +when the file is opened (but permission to access the directory that +contains it is still needed), and permissions are checked when the +descriptor is used later. + +For example, such descriptors can be used with the @code{fexecve} +function (@pxref{Executing a File}). + +This access mode is specific to Linux. On @gnuhurdsystems{}, it is +possible to use @code{O_EXEC} explicitly, or specify no access modes +at all (see below). +@end deftypevr + +The portable file access modes @code{O_RDONLY}, @code{O_WRONLY}, and +@code{O_RDWR} may not correspond to individual bits. To determine the +file access mode with @code{fcntl}, you must extract the access mode +bits from the retrieved file status flags, using the @code{O_ACCMODE} +mask. + +@deftypevr Macro int O_ACCMODE +@standards{POSIX.1, fcntl.h} + +This macro is a mask that can be bitwise-ANDed with the file status flag +value to recover the file access mode, assuming that a standard file +access mode is in use. +@end deftypevr + +If a non-standard file access mode is used (such as @code{O_PATH} or +@code{O_EXEC}), masking with @code{O_ACCMODE} may give incorrect +results. These non-standard access modes are identified by individual +bits and have to be checked directly (without masking with +@code{O_ACCMODE} first). + +On @gnuhurdsystems{} (but not on other systems), @code{O_RDONLY} and @code{O_WRONLY} are independent bits that can be bitwise-ORed together, and it is valid for either bit to be set or clear. This means that @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}. A file access @@ -3591,40 +3626,21 @@ mode of zero is permissible; it allows no operations that do input or output to the file, but does allow other operations such as @code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only'' is a misnomer, @file{fcntl.h} defines additional names for the file -access modes. These names are preferred when writing GNU-specific code. -But most programs will want to be portable to other POSIX.1 systems and -should use the POSIX.1 names above instead. +access modes. @deftypevr Macro int O_READ @standards{GNU, fcntl.h (optional)} -Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU. +Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU/Hurd. @end deftypevr @deftypevr Macro int O_WRITE @standards{GNU, fcntl.h (optional)} -Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU. +Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU/Hurd. @end deftypevr @deftypevr Macro int O_EXEC @standards{GNU, fcntl.h (optional)} -Open the file for executing. Only defined on GNU. -@end deftypevr - -To determine the file access mode with @code{fcntl}, you must extract -the access mode bits from the retrieved file status flags. On -@gnuhurdsystems{}, -you can just test the @code{O_READ} and @code{O_WRITE} bits in -the flags word. But in other POSIX.1 systems, reading and writing -access modes are not stored as distinct bit flags. The portable way to -extract the file access mode bits is with @code{O_ACCMODE}. - -@deftypevr Macro int O_ACCMODE -@standards{POSIX.1, fcntl.h} -This macro stands for a mask that can be bitwise-ANDed with the file -status flag value to produce a value representing the file access mode. -The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}. -(On @gnuhurdsystems{} it could also be zero, and it never includes the -@code{O_EXEC} bit.) +Open the file for executing. Only defined on GNU/Hurd. @end deftypevr @node Open-time Flags