From patchwork Mon May 18 07:49:45 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 39281 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 4CAAF386F828; Mon, 18 May 2020 07:49:54 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 4CAAF386F828 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1589788194; bh=8lH+4KfiXeiRktA6w2z0cOsEKqM3ge3SjXrqH0MZKQ8=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=j0U+jvn9QpSlKjiePXX1q8XZyon/ZF/kEC5gvaQPwCoZmoIE/zUsK9omdxYAodx0H DZb2IqwLCY//6CVrVphMeHQD1/smOHQ5MaPtGPxUwlfJz8dYC8Arml+8JdC9dys3mh VNIX3UTZfZSbf5yaKoQBgWREVBJvb//GL+7CxCdU= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by sourceware.org (Postfix) with ESMTP id C0C75386F002 for ; Mon, 18 May 2020 07:49:51 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org C0C75386F002 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-282-boWoINsmNNyi3AR9jFkBXA-1; Mon, 18 May 2020 03:49:49 -0400 X-MC-Unique: boWoINsmNNyi3AR9jFkBXA-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id BD4528014D7; Mon, 18 May 2020 07:49:48 +0000 (UTC) Received: from oldenburg2.str.redhat.com (ovpn-112-142.ams2.redhat.com [10.36.112.142]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E31FA6298C; Mon, 18 May 2020 07:49:47 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH] manual: Clarify File Access Modes section and add O_PATH Date: Mon, 18 May 2020 09:49:45 +0200 Message-ID: <878shpfzs6.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.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, 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: Kees Cook , "Michael Kerrisk \(man-pages\)" Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Kees Cook reported that the current text is misleading: --- manual/llio.texi | 68 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/manual/llio.texi b/manual/llio.texi index 6db4a70836..dd206b1b91 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,6 +3582,42 @@ Open the file for write access. Open the file for both reading and writing. @end deftypevr +@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 + +To determine the file access mode with @code{fcntl}, you must extract +the access mode bits from the retrieved file status 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. Usually, The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or +@code{O_RDWR}. +@end deftypevr + +If the mode is zero, it means that a non-standard access mode has been +used. See @code{O_PATH} above and @code{O_EXEC} below. These +non-standard access modes are identified by individual bits can +therefore be checked directly (without masking with @code{O_ACCMODE} +first). + On @gnuhurdsystems{} (and 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 @@ -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