From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.2 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 8DDA41F55B for ; Mon, 18 May 2020 19:58:13 +0000 (UTC) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6CBE13892027; Mon, 18 May 2020 19:58:12 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6CBE13892027 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1589831892; bh=gj938n41ByeJtRVvJdb5uadF7jAYBG5KZURM5AnJIqY=; h=Subject:To:References:Date:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=IP5LGpweKHZ8dxR1pKDlx3mcLUhvHAtq4NwdG2LsR9f62gDUIpilI824VAPbh1flM BMwLhjlIrmkrKnenW52xrwxkg4OR956dvosT/vTfOQfS6Yy/J+lDpvXTq9+EJvIFoW 36jrbpb1Sc46pBNy0UE3nOaJSCULg2Jz4ZCuahEI= Received: from mail-wr1-x444.google.com (mail-wr1-x444.google.com [IPv6:2a00:1450:4864:20::444]) by sourceware.org (Postfix) with ESMTPS id 234ED3851C0B for ; Mon, 18 May 2020 19:58:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 234ED3851C0B Received: by mail-wr1-x444.google.com with SMTP id y3so13318750wrt.1 for ; Mon, 18 May 2020 12:58:01 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:cc:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=gj938n41ByeJtRVvJdb5uadF7jAYBG5KZURM5AnJIqY=; b=nE5jAiCLQ8CmuRq55hfmc2uBZZuOvE+rdEIAcuwePKTt0R1Xuw4GoGZIEisUCsPmRR klzyRH1xrRjR1CTxsX5NTnRd+VfVZKNbbbXCCyscJezKDt3wefMsX0yyhERmoq3jztL2 SJOF6GDVK6yTN/EWkyrvY7HFFcPqtp1QUybqcZjIPEZuzYV11Gsj3cFME2Nn5o0umHxk 57dqfGOFRiip+yo7rGu3jzCqq9JWhX+NICZamj3wH2ikQfnf3xbjSdKPjwOFLiaKfzyW zmKDzMwhX1o2FeSIMhX2HvunyqgQrIfNJJpDRRgCzkhyjUNBxcIscFUB1uQjXoFHCPKO +OoQ== X-Gm-Message-State: AOAM530YtTvral6cxyVdaGv9CeEUZ9+iB54W0UwO/k3ardyO/NyukTPf Bc/0RfGiINfLCAWyh3p/JOs= X-Google-Smtp-Source: ABdhPJzDL5XZ6EZ5B5dh1bQcf3lOAj+4VF8aLN2cRMl88eYxxI1dqE8+HcRMO6pTf8muE6Bu2IHGUw== X-Received: by 2002:a5d:4ed0:: with SMTP id s16mr22960870wrv.166.1589831880174; Mon, 18 May 2020 12:58:00 -0700 (PDT) Received: from ?IPv6:2001:a61:2482:101:a081:4793:30bf:f3d5? ([2001:a61:2482:101:a081:4793:30bf:f3d5]) by smtp.gmail.com with ESMTPSA id m13sm756142wmi.42.2020.05.18.12.57.59 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 18 May 2020 12:57:59 -0700 (PDT) Subject: Re: [PATCH] manual: Clarify File Access Modes section and add O_PATH To: Florian Weimer , libc-alpha@sourceware.org References: <878shpfzs6.fsf@oldenburg2.str.redhat.com> Message-ID: Date: Mon, 18 May 2020 21:57:58 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.7.0 MIME-Version: 1.0 In-Reply-To: <878shpfzs6.fsf@oldenburg2.str.redhat.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit 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: , From: "Michael Kerrisk \(man-pages\) via Libc-alpha" Reply-To: "Michael Kerrisk \(man-pages\)" Cc: mtk.manpages@gmail.com, Kees Cook Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Hi Florian, On 5/18/20 9:49 AM, Florian Weimer wrote: > 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 s/stands for a mask/is a mask/ ? > +status flag value to produce a value representing the file access s/produce a value representing the/extract the bits representing the/ ? > +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. Either I misunderstand the previous sentence, or I think it is wrong. O_RDONLY has the value 0; that's a standard access mode. > 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 Not a problem with your patch, but in the above, better would be: s/and/but/ > @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. I do think removing this advice about POSIX is a bad move. Why do you want to advise people to use GNU-specific names? (I suspect I must be missing something...) > @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 Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/