bug#39613: stat(1) shouldn't call permissions "Access..."

[Pádraig Brady]

On 15/02/2020 02:15, 積丹尼 Dan Jacobson wrote:

(info "(coreutils) stat invocation") says,
• %a - Access rights in octal (note ‘#’ and ‘0’ printf flags)
• %A - Access rights in human readable form


Fair enough, as one might be confused that ACL info may be output.
This may be done in future, but until such time we can use
more accurate terminology.

I'll apply the attached later.
Marking this as done.

thanks,
Pádraig
>From 61c49d369369773b45beeac659fa32b6f481e8be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= 
Date: Sat, 15 Feb 2020 11:16:35 +
Subject: [PATCH] doc: clarify that '%a' stat format outputs mode bits

* src/stat.c (usage): Mention permission bits rather than
"access" so there is no confusion with ACLs etc.
Also indicate we output the file type with '%A'.
* doc/coreutils.texi (stat invocation): Likewise.
Also indicate '%A' is similar to `ls -ld` output.
Addresses https://bugs.gnu.org/39613
---
 doc/coreutils.texi | 4 ++--
 src/stat.c | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index cb238f087..24e424c54 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12438,8 +12438,8 @@ The valid @var{format} directives for files with @option{--format} and
 @option{--printf} are:
 
 @itemize @bullet
-@item %a - Access rights in octal (note @samp{#} and @samp{0} printf flags)
-@item %A - Access rights in human readable form
+@item %a - Permission bits in octal (note @samp{#} and @samp{0} printf flags)
+@item %A - Permission bits in symbolic form (similar to @command{ls -ld})
 @item %b - Number of blocks allocated (see @samp{%B})
 @item %B - The size in bytes of each block reported by @samp{%b}
 @item %C - The SELinux security context of a file, if available
diff --git a/src/stat.c b/src/stat.c
index 1fd83ee67..63f49d09e 100644
--- a/src/stat.c
+++ b/src/stat.c
@@ -1714,8 +1714,8 @@ The --cached MODE argument can be; always, never, or default.\n\
   fputs (_("\n\
 The valid format sequences for files (without --file-system):\n\
 \n\
-  %a   access rights in octal (note '#' and '0' printf flags)\n\
-  %A   access rights in human readable form\n\
+  %a   permission bits in octal (note '#' and '0' printf flags)\n\
+  %A   permission bits and file type in human readable form\n\
   %b   number of blocks allocated (see %B)\n\
   %B   the size in bytes of each block reported by %b\n\
   %C   SELinux security context string\n\
-- 
2.24.1

bug#39613: stat(1) shouldn't call permissions "Access..."

[積丹尼 Dan Jacobson]

(info "(coreutils) stat invocation") says,
   • %a - Access rights in octal (note ‘#’ and ‘0’ printf flags)
   • %A - Access rights in human readable form

But man find says,
   -perm mode
  File's permission bits are exactly mode (octal or symbolic).  
Since an exact match is required,  if
  you want to use this form for symbolic modes, you may have to 
specify a rather complex mode string.
  For example `-perm g=w' will only match files which have mode 
0020 (that is, ones for  which  group
  write  permission is the only permission set).  It is more likely 
that you will want to use the `/'
  or `-' forms, for example `-perm -g=w', which matches any file 
with group  write  permission.   See
  the EXAMPLES section for some illustrative examples.

   -perm -mode
  All  of  the  permission bits mode are set for the file.  
Symbolic modes are accepted in this form,
  and this is usually the way in which you would want to use them.  
You must specify `u', `g' or  `o'
  if you use a symbolic mode.  See the EXAMPLES section for some 
illustrative examples.

   -perm /mode
  Any  of  the  permission bits mode are set for the file.  
Symbolic modes are accepted in this form.
  You must specify `u', `g' or `o' if you use a symbolic mode.  See 
the EXAMPLES section for some il‐
  lustrative  examples.   If no permission bits in mode are set, 
this test matches any file (the idea
  here is to be consistent with the behaviour of -perm -000).

   -perm +mode
  This is no longer supported (and has been deprecated since 2005). 
 Use -perm /mode instead.


So stat's man and Info pages shouldn't use "Access" to talk about them.
Especially as it pretty much means something else:

   -readable
  Matches files which are readable by the current user.  This takes 
into account access control lists
  and other permissions artefacts which the -perm test ignores.  
This test makes use of the access(2)
  system call, and so can be fooled by NFS servers which do UID 
mapping  (or  root-squashing),  since
  many  systems  implement access(2) in the client's kernel and so 
cannot make use of the UID mapping
  information held on the server.