Re: [PATCH] manual: Add Descriptor-Relative Access section

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Florian

On 5/4/20 7:37 AM, Florian Weimer wrote:
> * Michael Kerrisk:
> 
>> Somewhere around here, do you want to say anything about use-cases for
>> the *at() functions? Here, I think of:
>>
>> (1) implementing the equivalent of per-thread CWD
>> (2) avoiding race conditions that can occur when using performing
>> operations on  files in directories other than the current working
>> directory.
> 
> Thank you for your comments.  I tried to address them.  I also
> replaced pathname with file name in most places.
> 
> I also added a few bullets that provide some motivation for the *at
> functions:
> 
> @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 must avoid looking up file names with multiple components, in
> order to detect symbolic links, using the @code{O_NOFOLLOW} flag
> (@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag
> (described below).  Without directory-relative access, it is necessary
> to use the @code{fchdir} function to change the working directory
> (@pxref{Working Directory}), which is not thread-safe.
> 
> @item
> Listing directory contents using the @code{readdir} or @code{readdir64}
> functions (@pxref{Reading and Closing a Directory Stream}) does not
> provide full file name paths.  Using @code{@dots{}at} functions, it is
> possible to use the file names directly, without having to construct
> such full paths.
> 
> @item
> Additional flags available with some of the @code{@dots{}at} functions
> provide access to functionality which is not available otherwise.
> @end itemize
> 
>>> +@cindex pathname resolution flags
>>> +@cindex @code{AT_*} pathname resolution flags
>>> +The flags argument in @code{@dots{}at} functions can be a combination of
>>> +the following flags, defined in @file{fcntl.h}.  Not all such functions
>>> +support all flags, and some (such as @code{openat}) do not accept a
>>> +flags argument at all.
>>
>> This last is slightly confusing for the reader. As you note later,
>> openat() does have a flags argument; it just doesn't allow for any of
>> these flags.
>>
>> Better: and some ... do not accept any of the flags.
> 
> I changed it to this:
> 
> Not all such functions support all flags.  Some of the functions (such
> as @code{openat}) completely lack an argument for the @code{AT_*}
> flags.
> 
>>> +@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.

> 
> New patch below.  I'm going to send a patch documenting O_NOFOLLOW
> separately.
> 
> 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 | 183 +++++++++++++++++++++++++++++++++++++++++++++++++---
>  manual/llio.texi    |  28 ++++++++
>  manual/startup.texi |   7 +-
>  3 files changed, 206 insertions(+), 12 deletions(-)
> 
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 73e630842e..03a893c5f9 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 selectable
> @@ -206,6 +207,144 @@ 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 variants have

Wording issue: have... 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 must avoid looking up file names with multiple components, in
> +order to detect symbolic links, using the @code{O_NOFOLLOW} flag
> +(@pxref{Open-time Flags}) or the @code{AT_SYMLINK_FOLLOW} flag
> +(described below).  Without directory-relative access, it is necessary
> +to use the @code{fchdir} function to change the working directory
> +(@pxref{Working Directory}), which is not thread-safe.

I find the above a little hard to grok. I think it would be helpful
to more explicitly point out that the problem is that the components
in the dirname part of the pathname could be symlinks whose targets
may change, which is a problem if the application will use the
pathname in a series of syscalls.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/