Re: [PATCH] fix descriptions for AT_NO_AUTOMOUNT

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

[Added a few CCs from the relevant kernel commits]

Hi Pádraig,

On 3/10/22 14:46, Pádraig Brady wrote:
> On 10/03/2022 07:44, Andreas Schwab wrote:
>> On Mär 09 2022, Paul Eggert wrote:
>>
>>> I audited gnulib's uses of fstatat and found one fishy one that doesn't
>>> use AT_NO_AUTOMOUNT, namely, in fts.c where the follow-symlink branch
>>> uses
>>> 'stat' whereas the no-follow-symlink branch uses fstatat without
>>> AT_NO_AUTOMOUNT. I installed the first patch to cause it be
>>> consistent in
>>> using AT_NO_AUTOMOUNT, which is also consistent with what glibc does
>>
>> ??? In glibc, stat is the same as fstatat(,,,0).
> 
> Indeed. It looks like the man page for fstatat is out of date.
> After looking at the kernel code, it seems that:
>   fstatat() did _not_ imply AT_NO_AUTOMOUNT from 2.6.38 -> 4.11
>     I'm not sure it even honored the AT_NO_AUTOMOUNT flag before 4.11
>   fstatat() did imply AT_NO_AUTOMOUNT since 4.11
> 
> The attached patch clarifies this is the fstatat and statx man pages.
> 
> sorry for the confusion,
> Pádraig

---

> Subject: [PATCH] fix descriptions for AT_NO_AUTOMOUNT
> 
> Don't mention AT_NO_AUTOMOUNT for fstatat.2
> as it's implied since v4.11-rc7-14-gdeccf497d804

Even though it's implied, since code may pass it,
and especially code written based on the old manual page,
it would be good to keep the paragraph in fstatat.2,
even if the text is replaced by something like
"Before Linux x.xx, this flag was ignored.
After Linux y.yy, this flag is implied."

Does it make sense to you?

> 
> Don't mention commit v4.13-9318-g42f461482178 as it was reverted

Please also mention v4.15-rc1-50-g5d38f049cee1 as the commit in which it
was reverted.
Since it was present in some kernel releases, we might want to mention
it in the manual page?

> 
> Mention that stat(), lstat(), and fstatat()
> imply AT_NO_AUTOMOUNT, on the statx.2 man page

Please sign the patch with "Signed-off-by: ..."
<https://www.kernel.org/doc/man-pages/patches.html>

> ---
>  man2/stat.2  | 31 -------------------------------
>  man2/statx.2 | 18 +++++++++++++++---
>  2 files changed, 15 insertions(+), 34 deletions(-)
> 
> diff --git a/man2/stat.2 b/man2/stat.2
> index 016c1f47d..43ab5b777 100644
> --- a/man2/stat.2
> +++ b/man2/stat.2
> @@ -317,37 +317,6 @@ This flag is Linux-specific; define
>  .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
>  to obtain its definition.
>  .TP
> -.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
> -Don't automount the terminal ("basename") component of
> -.I pathname
> -if it is a directory that is an automount point.
> -This allows the caller to gather attributes of an automount point
> -(rather than the location it would mount).
> -Since Linux 4.14,
> -.\" commit 42f46148217865a545e129612075f3d828a2c4e4
> -also don't instantiate a nonexistent name in an
> -on-demand directory such as used for automounter indirect maps.
> -This
> -flag has no effect if the mount point has already been mounted over.
> -.IP
> -Both
> -.BR stat ()
> -and
> -.BR lstat ()
> -act as though
> -.B AT_NO_AUTOMOUNT
> -was set.
> -.IP
> -The
> -.B AT_NO_AUTOMOUNT
> -can be used in tools that scan directories
> -to prevent mass-automounting of a directory of automount points.
> -.IP
> -This flag is Linux-specific; define
> -.B _GNU_SOURCE
> -.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
> -to obtain its definition.
> -.TP
>  .B AT_SYMLINK_NOFOLLOW
>  If
>  .I pathname
> diff --git a/man2/statx.2 b/man2/statx.2
> index 04b3e5075..d4e638756 100644
> --- a/man2/statx.2
> +++ b/man2/statx.2
> @@ -195,11 +195,23 @@ Don't automount the terminal ("basename") component of
>  if it is a directory that is an automount point.
>  This allows the caller to gather attributes of an automount point
>  (rather than the location it would mount).
> -This flag can be used in tools that scan directories
> -to prevent mass-automounting of a directory of automount points.
> +This
> +flag has no effect if the mount point has already been mounted over.
> +.IP
>  The
>  .B AT_NO_AUTOMOUNT
> -flag has no effect if the mount point has already been mounted over.
> +flag can be used in tools that scan directories
> +to prevent mass-automounting of a directory of automount points.
> +.IP
> +All of
> +.BR stat () ,

s/() ,/(2),/

See man-pages(7) for when to put a number and when not:
   Formatting conventions for manual pages describing functions
       [...]

       Any reference to the subject of the current  manual  page
       should  be  written  with  the name in bold followed by a
       pair of parentheses in Roman (normal) font.  For example,
       in the fcntl(2) man page, references to  the  subject  of
       the page would be written as: fcntl().  The preferred way
       to write this in the source file is:

           .BR fcntl ()



> +.BR lstat () ,

same

> +and
> +.BR fstatat ()

s/()/(2)/

> +act as though
> +.B AT_NO_AUTOMOUNT
> +was set.
> +.IP
>  This flag is Linux-specific; define
>  .B _GNU_SOURCE
>  .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
> -- 
> 2.31.1
> 

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/