From patchwork Wed Dec 2 12:40:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 41267 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 30C99395BC4C; Wed, 2 Dec 2020 12:40:16 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 30C99395BC4C DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1606912816; bh=UM/Nt7SlY399XTYUHnSNUDSxGPwgdORBA+IoGoPIjAU=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=ECzSGKDQ/YXaeo5t0DpzCnWT44GU89CcOMSTo2kSpwPX/9tuIamP3Y2I8WwO1Ypci a19/zFYPeb+t1fvYh72TLd4JPHfQkkmHuLqTUEoShdc0qLik9vqkvTMM3AtTdw6WsE CM4/lfE1S0IftPnwyw0Vfr8h8JYnStsAXHLOe8vc= 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 EA2B63857805 for ; Wed, 2 Dec 2020 12:40:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org EA2B63857805 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-306-Djdp1lCENhu31s0rz1ZEPQ-1; Wed, 02 Dec 2020 07:40:12 -0500 X-MC-Unique: Djdp1lCENhu31s0rz1ZEPQ-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 3244E803654; Wed, 2 Dec 2020 12:40:11 +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 55CF310013C1; Wed, 2 Dec 2020 12:40:10 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH v3] manual: Clarify File Access Modes section and add O_PATH Date: Wed, 02 Dec 2020 13:40:08 +0100 Message-ID: <878sag8jpz.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.84 on 10.5.11.22 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: --- v3: Use singular in the introduction. Other minor tweaks suggested by Michael. manual/llio.texi | 72 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/manual/llio.texi b/manual/llio.texi index 6db4a70836..c0a53e1a6e 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -3563,10 +3563,9 @@ The symbols in this section are defined in the header file @node Access Modes @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. +The file access mode allows a file descriptor to be used for reading, +writing, both, or neither. The access mode is determined 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 the 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 on. + +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