From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x542.google.com (mail-ed1-x542.google.com [IPv6:2a00:1450:4864:20::542]) by sourceware.org (Postfix) with ESMTPS id A1105385AC19 for ; Mon, 4 May 2020 10:03:05 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org A1105385AC19 Received: by mail-ed1-x542.google.com with SMTP id p16so12983378edm.10 for ; Mon, 04 May 2020 03:03:05 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:reply-to :from:date:message-id:subject:to:cc:content-transfer-encoding; bh=Y5v8Nyvg8fSODsKYHNiLYFT1wsVTWIZ/D1nBogyGcmM=; b=BDLhUZSXjDK2r9+xyse1itqG/wV1jyaGVSffkFKOcnCl3rf2Xn+HzBPJa6TIa9q2Jj YKnY0QnFQX5BKbji/sZRclCW6IKLv15dkJM0zpuuwmpVPR59zcc8jVqtNnU71AXAFNo4 K6x+P/fF7O+kToGjpGAHvI9tO0Don9jK7f8mlFnKVNsr2juBPsKRajO1c55LNKkvwq3s d+paZFo31NJM/OQFD/7G6ywOdw31UQ+hzVXDJ2einbgXc72Y/ym8yMa+Nt20OZvOGKaJ y88cEaigDJZZTWxX3KmnFbBhEMxBdG655GJF/UBfw8GFn13Fhg3nXk4mFvP+ep4GxGXW csXg== X-Gm-Message-State: AGi0PuZE+quGZn7gwooQ3D/ajMJwoBac8SarKyKt+2nybk7pPXll6OtU hGWBB3lvNu5C9jbgnX6pUa27qtP2ZX4CbYV0Ejg= X-Google-Smtp-Source: APiQypJIwJprfLlSAfmInqivSsQCob4AcLc/ORU4S78j2h9FhV6AyhBwGFwc4i32UlOobZGFyUgUe4saAVpl1Wx7bcI= X-Received: by 2002:a50:9e6a:: with SMTP id z97mr13127102ede.375.1588586584574; Mon, 04 May 2020 03:03:04 -0700 (PDT) MIME-Version: 1.0 References: <87d07p9v73.fsf@mid.deneb.enyo.de> <87zhaoxnt4.fsf@mid.deneb.enyo.de> <65c7dd0a-bfc8-7a23-6503-1f813947e5fa@gmail.com> <87wo5suku5.fsf@mid.deneb.enyo.de> In-Reply-To: <87wo5suku5.fsf@mid.deneb.enyo.de> Reply-To: mtk.manpages@gmail.com From: "Michael Kerrisk (man-pages)" Date: Mon, 4 May 2020 12:02:53 +0200 Message-ID: Subject: Re: [PATCH] manual: Add Descriptor-Relative Access section To: Florian Weimer Cc: libc-alpha Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-16.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, 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-List-Received-Date: Mon, 04 May 2020 10:03:10 -0000 Hi Florian, On Mon, 4 May 2020 at 11:10, Florian Weimer wrote: > > * Michael Kerrisk: > > >>>> +@end vtable > >>>> + > >>>> +There is no relationship between these flags and the type argument = to > >>> > >>> Formatting for 'type'? > >> > >> You mean, as in @var{type}? I think this is frowned upon because it > >> would be a dangling meta-syntactic variable in this context. > > > > I don't quite understand your explanation, but yet I meant formatting > > as you suggest. Without it, it's not so obvious to the reader that > > 'type' refers to an argument. > > The context is this: > > There is no relationship between these flags and the type argument to > the @code{getauxval} function (with @code{AT_@dots{}} constants defined > in @file{elf.h}). > > I think it's reasonable clear? I think I'm following the advice in > the Texinfo documentation: > > | Use the @var command to indicate metasyntactic variables. A > | metasyntactic variable is something that stands for another piece of > | text. For example, you should use a metasyntactic variable in the > | documentation of a function to describe the arguments that are > | passed to that function. > | > | Do not use @var for the names of normal variables in computer > | programs. These are specific names, so @code is correct for them > | (@code). For example, the Emacs Lisp variable texinfo-tex-command is > | not a metasyntactic variable; it is properly formatted using @code. > > =E2=80=9Ctype=E2=80=9D does not stand for any other text in the quoted se= ntence, it > refers to the single function argument. Okay. (Obviously, I don't really know the GNU guidelines.) [...] > 8<------------------------------------------------------------------8< > And document the functions openat, openat64, fstatat, fstatat64. > (The safety assessment for fstatat was already obsolete because > current glibc assumes kernel support for the underlying system call.) > > ----- > manual/filesys.texi | 187 ++++++++++++++++++++++++++++++++++++++++++++++= +++--- > manual/llio.texi | 28 ++++++++ > manual/startup.texi | 7 +- > 3 files changed, 210 insertions(+), 12 deletions(-) > > diff --git a/manual/filesys.texi b/manual/filesys.texi > index 73e630842e..ad11dc2b26 100644 > --- a/manual/filesys.texi > +++ b/manual/filesys.texi > @@ -15,6 +15,7 @@ access permissions and modification times. > @menu > * Working Directory:: This is used to resolve relative > file names. > +* Descriptor-Relative Access:: Ways to control file name lookup. > * Accessing Directories:: Finding out what files a directory > contains. > * Working with Directory Trees:: Apply actions to all files or a selecta= ble > @@ -206,6 +207,148 @@ An I/O error occurred. > @end table > @end deftypefun > > +@node Descriptor-Relative Access > +@section Descriptor-Relative Access > +@cindex file name lookup based on descriptors > +@cindex pathname resolution based on descriptors > +@cindex descriptor-based file name resolution > +@cindex @code{@dots{}at} functions > + > +Many functions that accept file names have @code{@dots{}at} variants > +which accept a file descriptor and a file name argument instead of just > +a file name argument. For example, @code{fstatat} is the > +descriptor-based variant of the @code{fstat} function. Most such > +functions also accept an additional flags argument which changes the > +behavior of the file name lookup based on the @code{AT_@dots{}} flags > +specified. > + > +There are several reasons to use descriptor-relative access: > + > +@itemize @bullet > +@item > +The working directory is a process-wide resource, so individual threads > +cannot change it without affecting other threads in the process. > +Explicitly specifying the directory against which relative paths are > +resolved can be a thread-safe alternative to changing the working > +directory. > + > +@item > +If a progrem wishes to access a directory tree which is being modified > +concurrently, perhaps even by a different user on the system, the > +program typically must avoid following symbolic links. With POSIX > +interfaces, this can be done using the @code{O_NOFOLLOW} flag > +(@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag > +(described below), but these flags affect only the final component of a > +file name (the basename). Symbolic links in the parent directory part > +are still followed. Therefore, without directory-relative access, it is > +necessary to use the @code{fchdir} function to change the working > +directory (@pxref{Working Directory}) and use the basename for file > +system access. As explained before, this is not thread-safe. Keeping a > +file descriptor of the directory is also required to be able to return Maybe better: s/of/that refers to/ > +to it later, so descriptor-based access is a natural fit. s/descriptor-relativebased/descriptor-relative/ ? Thanks, Michael