GNU bug report logs - #29069
info coreutils file permissions: improvements/bug-report

Previous Next

To reply to this bug, email your comments to 29069 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: bug-coreutils <at> gnu.org
Subject: info coreutils file permissions: improvements/bug-report
Date: Mon, 30 Oct 2017 21:38:06 +0100

hello,
here some improvement proposals/bug report on info coreutils file
permissions:

-in my opinion it would be good to explain the general idea bihind the
file permissions a bit more. what the issues are etc. Elese one doesn't
really understand, what all the detailed fuss is about.
-why is running a file considered different  from reading one? Fact is,
that this point underlies the concept of symbolic mode with it's `rwx'.
-27.1,end of the first section: add the sentence "They have a different
meaning, according to wether they are directories or not"
-27.2.4, part "or already had execute permission": had execute
permission for which user category? for the one in question or for any?
-explain more fundamentally the relationship between file permission
rights and the rights of the corresponding directory , for example
regarding to deletion: who has the right to delete file /b/a? users with
writing permission on a AND those withrmission on b?
27.4: wouldn't it be better to talk about 'operators _in_ numeric mode'
rather than from an 'operator numeric mode', since "numeric mode" is an
atrribute?
-27.3: is there an info/man-document, where binary, octal, hex-numbers
are explained? If, it should be referred to. If not, shouldn't there be
one (and where would it fit in? ) ?-- I could write the text...Since
this documentation assumes the knowledge of it..
-27.5: it is said, that "a command like `chmod' does not affect the
set-user-id, unless […] sets them in a numeric mode".But also, the
example states that `chmod 0755' or `mkdir -m 0755' doesn't change
set-user/group-id- bits. For me, this doesn't fit together,since the `0'
in `0755' explicitly sets all special mode bits to zero.
-27.5,last section, it says: "this behavior is a GNU extension". Which
behavior is meant? And if it concerns the whole section 27.5, it should
be put right at the beginning.

greetings,
kalle

Message #8 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: kalle <kalle <at> projektwerkstatt.de>, 29069 <at> debbugs.gnu.org,
 control <at> debbugs.gnu.org
Subject: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Mon, 30 Oct 2017 13:35:32 -0600

tag 29069 notabug
stop

Hello,

On 2017-10-30 02:38 PM, kalle wrote:
> here some improvement proposals/bug report on info coreutils file 
> permissions:
> 
> -in my opinion it would be good to explain the general idea bihind 
> the file permissions a bit more. what the issues are etc. Elese one 
> doesn't really understand, what all the detailed fuss is about. -why
> is running a file considered different  from reading one? Fact is,
> that this point underlies the concept of symbolic mode with it's 
> `rwx'. -

There is a trade-off between being a full-blown unix tutorial and a
manual for coreutils.

There are many good tutorials and guides available in books and online,
e.g. https://wiki.debian.org/Permissions .

To make this discussion more concrete, it would help if you send 
specific patches for the paragraph you'd like to change, with suggested 
wording.

> 27.1,end of the first section: add the sentence "They have a 
> different meaning, according to wether they are directories or not"

Each relevant bullet points in that page end with "... for Directories,
this means [...]".

https://www.gnu.org/software/coreutils/manual/html_node/Mode-Structure.html

> 27.2.4, part "or already had execute permission": had execute 
> permission for which user category? for the one in question or for 
> any?

Any category.

The last sentence in that page says:
"gives all users permission [...]  if anyone could execute them before".

https://www.gnu.org/software/coreutils/manual/html_node/Conditional-Executability.html

> -explain more fundamentally the relationship between file permission
> rights and the rights of the corresponding directory , for example
> regarding to deletion: who has the right to delete file /b/a? users
> with writing permission on a AND those withrmission on b?

I think this is a good suggestion (though perhaps not specific to
coreutils).

We recently had a related discussion about that in 'sed',
where users were surprised that "sed --inplace" can modify a read-only file.
https://lists.gnu.org/archive/html/bug-sed/2017-06/msg00000.html

Similarly on gawk:
https://lists.gnu.org/archive/html/bug-gawk/2015-06/msg00000.html


> 27.4: wouldn't it be better to talk about 'operators _in_ numeric
> mode' rather than from an 'operator numeric mode', since "numeric
> mode" is an atrribute?

(I'll leave this to native English speakers)

> -27.3: is there an info/man-document, where binary,
> octal, hex-numbers are explained? If, it should be referred to. If 
> not, shouldn't there be one (and where would it fit in? ) ?-- I
> could write the text...Since this documentation assumes the knowledge
> of it..

Not sure this belongs in the coreutils manual,
however if you send a patch that would go a long way towards considering 
it for inclusion.

For comparison, I see that "chmod" manual page in OpenBSD, FreeBSD and
POSIX mention octal code values but do not explain with octal is.
The reader is expected to either use them as-is, or search for more 
details elsewhere.

https://man.openbsd.org/chmod.1
https://www.freebsd.org/cgi/man.cgi?query=chmod
http://pubs.opengroup.org/onlinepubs/9699919799/utilities/chmod.html

>
-27.5: it is said, that "a command like `chmod' does not
> affect the set-user-id, unless […] sets them in a numeric mode".But
> also, the example states that `chmod 0755' or `mkdir -m 0755'
> doesn't change set-user/group-id- bits.
>
> For me, this doesn't fit 
> together,since the `0' in `0755' explicitly sets all special mode 
> bits to zero.

There is some subtlety here, which perhaps can be explained better 
(patches are welcomed!).

Setting (=turning on) sticky/setuid/setgid bits using the 4th octal 
digit works as expected (i.e. chmod 4775 DIR).

In GNU's chmod(1), setting the 4th digit to zero *does not* clear those 
bits, it preserves them (i.e. does not change them if they are set).
To clear them, one needs to specify *five* octal digits: 00755.

This is explained in the second paragraph of section 27.5:
"Therefore, a command like chmod does not affect the set-user-ID or 
set-group-ID bits of a directory unless the user specifically mentions 
them in a symbolic mode, or uses an operator numeric mode such as 
‘=755’, or sets them in a numeric mode, or clears them in a numeric mode 
that has **five or more** octal digits."
https://www.gnu.org/software/coreutils/manual/html_node/Directory-Setuid-and-Setgid.html

The last paragraph on said page also mentions:
"The GNU behavior with numeric modes of four or fewer digits is intended 
for scripts portable to systems that preserve these bits; the behavior 
with numeric modes of five or more digits is for scripts portable to 
systems that do not preserve the bits."

The wording could also be improved in section "27.3 Numeric Modes", 
which only mentions this in passing:
  "However, modes of five digits or more, such as ‘00055’,
   are sometimes special. See Directory Setuid and Setgid."
https://www.gnu.org/software/coreutils/manual/html_node/Numeric-Modes.html



> -27.5,last section, it says: "this behavior is a GNU 
> extension". Which behavior is meant?

This refers to the preceding paragraph, dealing with "if you want to 
clear these bits".

The behavior differs from other systems (e.g. FreeBSD),
where "chmod 0775" indeed clears the suid bit.


> greetings, kalle

Thank you for raising these issues.

If you'd like to suggest better wordings, please do send a patches
(preferably one patch for each section/topic).

I'm marking this as "not-a-bug", but keeping it open
until we either improve these items or decide to keep them as-is.

regards,
 - assaf

Message #13 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: assafgordon <at> gmail.com, 29069 <at> debbugs.gnu.org, 
 control <at> debbugs.gnu.org
Subject: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Wed, 08 Nov 2017 11:31:20 +0100

hi,
the parts concerning 27.3 (numeric modes) have been put into a different
e-mail by me.



>On 2017-10-30 02:38 PM, kalle wrote:
>> here some improvement proposals/bug report on info coreutils file
permissions:
>>
>> -in my opinion it would be good to explain the general idea bihind
the file permissions a bit more. what the issues are etc. Elese one
doesn't really understand, what all the detailed fuss is about. -why
>> is running a file considered different  from reading one? Fact is,
>> that this point underlies the concept of symbolic mode with it's `rwx'. -

>There is a trade-off between being a full-blown unix tutorial and a
>manual for coreutils.

I thought that `man' does the short reference part and info was a bit
more detailed. The wiki.debian.org/Permissions-tutorial is even shorter
than this texinfo-document actually is and also doesn't motivate the
permission concept.

>There are many good tutorials and guides available in books and online,
>e.g. https://wiki.debian.org/Permissions .

IMO the advantage of texinfo is, that it is nearly always by the hand
and is a standard documentation. The disadvantage of the
debian-wiki-tutorial is, that it uses a debian-specific platform while
handling general content, thus unnecessarily wasting resources in form
of human time and restricting accessability, in the sense that not all
GNU-users would look at this site.
It by the way has a wrong description about unsetting special mode bits
by doing e.g. `chmod '0755'' (see at "Case 4"), which I will correct as
soon as possible -> more users, less mistakes..

What do YOU think should be the character of an info-file?

>To make this discussion more concrete, it would help if you send
specific patches for the paragraph you'd like to change, with suggested
wording.

As it's about the motivation of the concept I would prefer to not help
out with a patch since I myself am a learner.

>> 27.1,end of the first section: add the sentence "They have a
different meaning, according to wether they are directories or not"

>Each relevant bullet points in that page end with "... for Directories,
>this means [...]".

I think it is better to write this before the bullet points to make it
clear, that the concept  of "read"/"write"/etc. is different whether it
is a regualar file or a directory rather than you have to interprete
these terms differently according to whether the target file is a
regular file or a directory.



>> 27.2.4, part "or already had execute permission": had execute
permission for which user category? for the one in question or for any?

>Any category.

>The last sentence in that page says:
>"gives all users permission [...]  if anyone could execute them before".

yes, it says this, but it relates to the example `a+X', where also
_any_one would get executability.
my patch: Add "for anyone" to the sentence "already had execute permission".


>> -explain more fundamentally the relationship between file permission
>> rights and the rights of the corresponding directory , for example
>> regarding to deletion: who has the right to delete file /b/a? users
>> with writing permission on a AND those withrmission on b?

>I think this is a good suggestion (though perhaps not specific to
>coreutils).

Where else would be the place to write about this?

>We recently had a related discussion about that in 'sed',
>where users were surprised that "sed --inplace" can modify a read-only
file.
>https://lists.gnu.org/archive/html/bug-sed/2017-06/msg00000.html

>Similarly on gawk:
>https://lists.gnu.org/archive/html/bug-gawk/2015-06/msg00000.html


>> 27.4: wouldn't it be better to talk about 'operators _in_ numeric
>> mode' rather than from an 'operator numeric mode', since "numeric
>> mode" is an atrribute?

>(I'll leave this to native English speakers)

No native English speakers answering...


>>
>-27.5: it is said, that "a command like `chmod' does not
>> affect the set-user-id, unless […] sets them in a numeric mode".But
>> also, the example states that `chmod 0755' or `mkdir -m 0755'
>> doesn't change set-user/group-id- bits.
>>
>> For me, this doesn't fit together,since the `0' in `0755' explicitly
sets all special mode bits to zero.

>There is some subtlety here, which perhaps can be explained better
(patches are welcomed!).

>Setting (=turning on) sticky/setuid/setgid bits using the 4th octal
digit works as expected (i.e. chmod 4775 DIR).

>In GNU's chmod(1), setting the 4th digit to zero *does not* clear those
bits, it preserves them (i.e. does not change them if they are set).
>To clear them, one needs to specify *five* octal digits: 00755.

>This is explained in the second paragraph of section 27.5:
>"Therefore, a command like chmod does not affect the set-user-ID or
set-group-ID bits of a directory unless the user specifically mentions
them in a symbolic mode, or uses an operator numeric mode such as
‘=755’, or sets them in a numeric mode, or clears them in a numeric mode
that has **five or more** octal digits."
>https://www.gnu.org/software/coreutils/manual/html_node/Directory-Setuid-and-Setgid.html

"does not affect" should be replaced by "does not clear" (because chmod
does affect special mode bits when setting them), "mentions" replaced by
"clears", "or sets them in a numeric mode" has to be taken away (this is
what I wanted to tell by saying that 0755 is an explicit mentioning in
numeric mode -> because this shouldn't  work, numeric mode shouldn't
work for clearing special mode bits).

>The last paragraph on said page also mentions:
>"The GNU behavior with numeric modes of four or fewer digits is
intended for scripts portable to systems that preserve these bits; the
behavior with numeric modes of five or more digits is for scripts
portable to systems that do not preserve the bits."

I don't really understand this paragraph.

>The wording could also be improved in section "27.3 Numeric Modes",
which only mentions this in passing:
>  "However, modes of five digits or more, such as ‘00055’,
>   are sometimes special. See Directory Setuid and Setgid."
>https://www.gnu.org/software/coreutils/manual/html_node/Numeric-Modes.html

My improvement proposal:
Modes of five digits or more, such as `00055', have a special meaning
for directories (see Directory Setuid and Setgid)

The sentence before, "mode `0055' is the same as `55'", is also not very
neat, since it doesn't explain why it is so and if it has something to
do with putting `0' in front when using the language `C'.


>> -27.5,last section, it says: "this behavior is a GNU extension".
Which behavior is meant?

>This refers to the preceding paragraph, dealing with "if you want to
clear these bits".

I propose to replace "This behavior" by "This last behavior" to make it
clearer.


>The behavior differs from other systems (e.g. FreeBSD),
>where "chmod 0775" indeed clears the suid bit.

I think it should also be explained in chapter 27, what the default
permissions are, when creating a file etc.And also: who can change the
permissions, and how?There has to be at least a reference

In the menu 27, there is written about "ANDing" and "ORing".These terms
doesn't appear in the appropriate section, namely 27.4.

>> greetings, kalle

>Thank you for raising these issues.

>If you'd like to suggest better wordings, please do send a patches
>(preferably one patch for each section/topic).

>I'm marking this as "not-a-bug", but keeping it open
>until we either improve these items or decide to keep them as-is.

>regards,
> - assaf

Message #16 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: assafgordon <at> gmail.com, 29069 <at> debbugs.gnu.org, 
 control <at> debbugs.gnu.org
Subject: improvement proposals texinfo-coreutils,27.3 (numeric modes)
Date: Wed, 08 Nov 2017 11:31:24 +0100

[Message part 1 (text/plain, inline)]

hello there,
this e-mail continues the discussion about improvement proposals about
info coreutils,section "File permissions". '>>' was me
(kalle <at> projektwerkstatt.de writing, '>' was assafgordon <at> gmail.com
This mail continues the specialized debate about `27.3 (numeric modes)'.



>> -27.3: is there an info/man-document, where binary,
>> octal, hex-numbers are explained? If, it should be referred to. If
not, shouldn't there be one (and where would it fit in? ) ?-- I
>> could write the text...Since this documentation assumes the knowledge
>> of it..

>Not sure this belongs in the coreutils manual,
>however if you send a patch that would go a long way towards
considering it for inclusion.

I wrote some text,attached to this mail. I think man 7 would be an
appropriate place for this.

>For comparison, I see that "chmod" manual page in OpenBSD, FreeBSD and
>POSIX mention octal code values but do not explain with octal is.
>The reader is expected to either use them as-is, or search for more
details elsewhere.

>https://man.openbsd.org/chmod.1
>https://www.freebsd.org/cgi/man.cgi?query=chmod
>http://pubs.opengroup.org/onlinepubs/9699919799/utilities/chmod.html

In the introduction of the coreutils-texinfo-document, it says: "many
sections make no attempt to explain basic concepts in a way suitable for
novices. […] get involved in improving this manual"


>  "However, modes of five digits or more, such as ‘00055’,
>   are sometimes special. See Directory Setuid and Setgid."
>https://www.gnu.org/software/coreutils/manual/html_node/Numeric-Modes.html

My improvement proposal:
Modes of five digits or more, such as `00055', have a special meaning
for directories (see Directory Setuid and Setgid)


REMARK: the below section is my improvement proposal of the section
27.3. I left the two first paragraphs unchanged here.The above
transformations are not incorporated yet for your better overview, since
the below part is only a different explanation of the octal model. The
above correction proposals thus still have to be worked in.

27.3 Numeric Modes
==================

As an alternative to giving a symbolic mode, you can give an octal
(base8) number that represents the mode.  This number is always
interpretedin octal; you do not have to add a leading ‘0’, as you do in
C. Mode‘0055’ is the same as mode ‘55’.  (However, modes of five digits
ormore, such as ‘00055’, are sometimes special.  *Note Directory
Setuidand Setgid::.)

A numeric mode is usually shorter than the corresponding symbolicmode,
but it is limited in that normally it cannot take into account
theprevious file mode bits; it can only set them absolutely.
Theset-user-ID and set-group-ID bits of directories are an exception
tothis general limitation.  *Note Directory Setuid and Setgid::.
Also,operator numeric modes can take previous file mode bits into
account.*Note Operator Numeric Modes::.

The octal notation can be derived from the symbolic one,as an
intermediate step transforming it into a binary string (1), which is
then easily changed into octal base (2):

(1)For the intermediate step the `r',`w' and `x'-symbols of the symbolic
notation are changed out at the corresponding place by a `0' or a `1',
according to whether the bits are clear or set  (this works as long as
there are no special mode bits, because every place belongs specifically
to one kind of bit), thus transforming e.g. the string `rwxr-xr--' into
`111101100'.Then instead of overriding the `x'-bits, the special mode
bits are represented by grouping them at the beginning, in the order
suid|guid|sticky/restricted_deletion, thus e.g. describing symbolic
`rwsr-xr-t' as `101111101101'.

(2)Every 3 digits can then be grouped together and described as octal
digits, following the logic that three binary digits `abc' are
translated into an octal number a*2^2+b*2^1+c*2^0=a*4+b*2+c*1, e.g.:

binary	octal
101	5
111	7
011	3

thus transforming the binary `101111101101' from the last example into
octal `5755',

[man_number-rep (text/plain, attachment)]

Message #19 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: assafgordon <at> gmail.com, 29069 <at> debbugs.gnu.org
Subject: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Thu, 09 Nov 2017 15:13:11 +0100

>> There are many good tutorials and guides available in books and online,
>> e.g. https://wiki.debian.org/Permissions .

>It by the way has a wrong description about unsetting special mode bits
> by doing e.g. `chmod '0755'' (see at "Case 4"), which I will correct as
> soon as possible -> more users, less mistakes..

No. Since it is not standard documentation I am a bit exhausted by
discussion about corrections in free software community in difficult
english just now. I would prefer to not correct this mistake now. What
about you?

greetings,
kalle

Message #22 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: Assaf Gordon <assafgordon <at> gmail.com>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Fri, 19 Jan 2018 22:25:22 +0100

[Message part 1 (text/plain, inline)]

Am 16.12.2017 um 22:14 schrieb Assaf Gordon:
> Hello,
> 
> On 2017-12-16 01:52 PM, kalle wrote:
>> did you plan to respond my mail?
> 
> Please remember GNU coreutils is maintained by volunteers.
> We aim for best effort in incorporating improvement suggestions
> from contributors, but there is no "dead line" for such things.
> 
> You wrote many good suggestions and text improvements.
> 
> If you'd like to see them through, the best way is to
> offer a patch suitable for inclusion.
> For instructions on how to send such patch, please see
>   https://git.savannah.gnu.org/cgit/coreutils.git/tree/HACKING
>   https://git.savannah.gnu.org/cgit/coreutils.git/tree/README-hacking

I made a patch for chapter 27.3 (Numeric modes) in texinfo coreutils. it
is attached to this mail.
> 
> As your contribution is significant (more than 10 lines),
> it'll also require copyright assignment (see
> https://www.gnu.org/licenses/why-assign.html ).

I hereby assign the copyright on the attached text to the FSF.

Is that enough?

> 
> If you prefer not to spend time on making such a patch, that is of
> course completely fine. In that case, this will have to wait until
> one of the maintainers (or another volunteer) decides to
> spend the time required to incorporate these improvements.
> 
> Also,
> It is best to keep these communications public by sending emails to the
> mailing list, even if it is a simple question of "what's the status?" or
> "any progress?".
> 
> 
> 
> regards,
>  - assaf

greetings,
kalle

[patch_numeric_modes (text/plain, attachment)]

Message #25 received at submit <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: bug-coreutils <at> gnu.org
Subject: Fwd: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Wed, 31 Jan 2018 00:55:31 +0100

[Message part 1 (text/plain, inline)]

I have a patch for chapter 27.3, coreutils texinfo-document.

greetings,
kalle

[patch_numeric_modes (text/plain, attachment)]

Message #28 received at submit <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: bug-coreutils <at> gnu.org
Subject: Fwd: Fwd: Re: bug#29069: info coreutils file permissions:
 improvements/bug-report
Date: Tue, 13 Mar 2018 00:24:50 +0100

[Message part 1 (text/plain, inline)]

until now, no one responded to my patch proposal neither  encorporated
it as I see.
why not?
kalle


-------- Weitergeleitete Nachricht --------
Betreff: Fwd: Re: bug#29069: info coreutils file permissions:
improvements/bug-report
Datum: Wed, 31 Jan 2018 00:55:31 +0100
Von: kalle <kalle <at> projektwerkstatt.de>
An: bug-coreutils <at> gnu.org

I have a patch for chapter 27.3, coreutils texinfo-document.

greetings,
kalle

[patch_numeric_modes (text/plain, attachment)]

Message #31 received at submit <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: bug-coreutils <at> gnu.org, assafgordon <at> gmail.com, 29069 <at> debbugs.gnu.org
Subject: bug#29069
Date: Sun, 25 Mar 2018 16:43:55 +0000

hello people.
I once wrote some improvement proposals to the list.

assafgordon <at> gmail.com wrote to me

"
You wrote many good suggestions and text improvements.

If you'd like to see them through, the best way is to
offer a patch suitable for inclusion.
For instructions on how to send such patch, please see
  https://git.savannah.gnu.org/cgit/coreutils.git/tree/HACKING
  https://git.savannah.gnu.org/cgit/coreutils.git/tree/README-hacking

As your contribution is significant (more than 10 lines),
it'll also require copyright assignment (see
https://www.gnu.org/licenses/why-assign.html ).

If you prefer not to spend time on making such a patch, that is of
course completely fine. In that case, this will have to wait until
one of the maintainers (or another volunteer) decides to
spend the time required to incorporate these improvements.
"

Since then I extra learned git, to be able to give in the patches
myself. But for my last 2 mails sending in my patch proposals, no
response came...

here now for the 4th time again my patch proposal for chapter 27.3:

>From b250dcdaba02083a0174d9157c655f0dbb586ef6 Mon Sep 17 00:00:00 2001
From: kalle <kalle <at> projektwerkstatt.de>
Date: Wed, 3 Jan 2018 20:56:07 +0100
Subject: [PATCH] changed presentation in 'File permissions' in 'numeric
modes'

I described the numeric modes explaining it's octal representation and
how it is obtained from the symbolic notation.
---
 doc/perm.texi | 64
++++++++++++++---------------------------------------------
 1 file changed, 15 insertions(+), 49 deletions(-)

diff --git a/doc/perm.texi b/doc/perm.texi
index c94c483..a514998 100644
--- a/doc/perm.texi
+++ b/doc/perm.texi
@@ -491,59 +491,25 @@ the file to all users.
 @cindex numeric modes
 @cindex file mode bits, numeric
 @cindex octal numbers for file modes
-As an
-alternative to giving a symbolic mode, you can give an octal (base 8)
-number that represents the mode.
-This number is always interpreted in octal; you do not have to add a
-leading @samp{0}, as you do in C.  Mode @samp{0055} is the same as
-mode @samp{55}.  (However, modes of five digits or more, such as
-@samp{00055}, are sometimes special.  @xref{Directory Setuid and Setgid}.)
-
-A numeric mode is usually shorter than the corresponding symbolic
-mode, but it is limited in that normally it cannot take into account the
-previous file mode bits; it can only set them absolutely.
-The set-user-ID and set-group-ID bits of directories are an exception
-to this general limitation.  @xref{Directory Setuid and Setgid}.
-Also, operator numeric modes can take previous file mode bits into
-account.  @xref{Operator Numeric Modes}.
-
-The permissions granted to the user,
-to other users in the file's group,
-and to other users not in the file's group each require three
-bits, which are represented as one octal digit.  The three special
-mode bits also require one bit each, and they are as a group
-represented as another octal digit.  Here is how the bits are arranged,
-starting with the lowest valued bit:
+As an alternative to giving a symbolic mode, you can give an octal
(with base 8) number that represents the mode.This number is always
interpreted in octal; you do not have to add a leading @samp{0}, as you
do in C. Mode @samp{0055} is the same as mode @samp{55}.  Modes of five
digits or more, such as @samp{00055}, have a special meaning for
directories  @xref{Directory Setuid and Setgid}.)
+
+A numeric mode is usually shorter than the corresponding symbolic mode,
but it is limited in that normally it cannot take into account the
previous file mode bits; it can only set them absolutely.  The
set-user-ID and set-group-ID bits of directories are an exception to
this general limitation.   @xref{Directory Setuid and Setgid}.  Also,
operator numeric modes can take previous file mode bits into account. 
@xref{Operator Numeric Modes}.
+
+The octal notation can be derived from the symbolic one, as an
intermediate step transforming it into a binary string (1), which is
then easily changed into octal base (2):
+
+(1)For the intermediate step the @samp{r},@samp{w} and @samp{x}-symbols
of the symbolic notation are changed out at the corresponding place by a
@samp{0} or a @samp{1}, according to whether the bits are clear or set 
(this works as long as there are no special mode bits, because every
place belongs specifically to one kind of bit), thus transforming e.g.
the string @samp{rwxr-xr--} into @samp{111101100}.Then instead of
overriding the @samp{x}-bits, the special mode bits are represented by
grouping them at the beginning, in the order
suid|guid|sticky/restricted_deletion, thus e.g. describing symbolic
@samp{rwsr-xr-t} as @samp{101111101101}.
+
+(2)Every 3 digits can then be grouped together and described as an
octal digit, following the logic that three binary digits @samp{abc} are
translated into an octal number a*2^2+b*2^1+c*2^0=a*4+b*2+c*1, e.g.:
 
 @example
-Value in  Corresponding
-Mode      Mode Bit
-
-          Other users not in the file's group:
-   1      Execute/search
-   2      Write
-   4      Read
-
-          Other users in the file's group:
-  10      Execute/search
-  20      Write
-  40      Read
-
-          The file's owner:
- 100      Execute/search
- 200      Write
- 400      Read
-
-          Special mode bits:
-1000      Restricted deletion flag or sticky bit
-2000      Set group ID on execution
-4000      Set user ID on execution
+binary    octal
+101    5
+111    7
+011    3
 @end example
 
-For example, numeric mode @samp{4755} corresponds to symbolic mode
-@samp{u=rwxs,go=rx}, and numeric mode @samp{664} corresponds to
symbolic mode
-@samp{ug=rw,o=r}.  Numeric mode @samp{0} corresponds to symbolic mode
-@samp{a=}.
+thus transforming the binary @samp{101111101101} from the last example
into octal @samp{5755}.
+
 
 @node Operator Numeric Modes
 @section Operator Numeric Modes
-- 
1.9.1

Message #39 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: kalle <kalle <at> projektwerkstatt.de>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#31043: [PATCH] changed presentation in 'File permissions' in
 'numeric, modes'
Date: Tue, 3 Apr 2018 08:45:06 -0700

[Message part 1 (text/plain, inline)]

Thanks for mentioning the problem. However, I found the proposed rewrite 
to be more confusing than the original. I think part of the problem is 
that this is not really the place to explain octal notation; any reader 
who doesn't know octal before reading the manual is not likely to 
understand it even with the proposed rewrite. I think we should just 
give up and assume that the reader knows octal (if they don't they 
should be using symbolic modes). That being said, we could briefly give 
an example of how the individual bits are combined into an octal digit, 
and rearrange the description to make it more intuitive. I installed the 
attached patch to try to improve things.

I also merged Bug#31043 with Bug#29069 since they're the same topic.

[0001-doc-Clarify-octal-bits-in-permissions.patch (text/x-patch, attachment)]

Message #42 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#31043: [PATCH] changed presentation in 'File permissions' in
 'numeric, modes'
Date: Tue, 3 Apr 2018 21:29:35 +0200

hello,


Am 03.04.2018 um 17:45 schrieb Paul Eggert:
> Thanks for mentioning the problem.
so you see a problem there too?

 However, I found the proposed rewrite
> to be more confusing than the original. 
It may me that my way of building sentences is quite amendable. I'm not
a native english writer.
But what do you think of my teaching concept, to try to explain why a
`7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
self-evident or intuitive in both the original text and your patch?			

I think part of the problem is
> that this is not really the place to explain octal notation;
maybe. But where would be a place, to formulate the problem `7=4+2+1'
more generally? and then to just refer to it?

 any reader
> who doesn't know octal before reading the manual is not likely to
> understand it even with the proposed rewrite.
Because of what, do you think?

 I think we should just
> give up and assume that the reader knows octal (if they don't they
> should be using symbolic modes) 
if they don't miss any important features..
but why already giving up? does it seem so impossible to find a more
newbie-friendly solution?

. That being said, we could briefly give
> an example of how the individual bits are combined into an octal digit,
> and rearrange the description to make it more intuitive. I installed the
> attached patch to try to improve things.
Why didn't you take over my correction from "are sometimes special" to
"have a special meaning for directories" ?
> 
> I also merged Bug#31043 with Bug#29069 since they're the same topic.
The problem was, that when writing  "Bug#29069" in the subject, nobody
responded to my patch proposal, which at the end was nearly to frustrating.

greetings,
kalle

Message #45 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: kalle <kalle <at> projektwerkstatt.de>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#31043: [PATCH] changed presentation in 'File permissions' in
 'numeric, modes'
Date: Tue, 3 Apr 2018 15:10:21 -0700

On 04/03/2018 12:29 PM, kalle wrote:
>
> But what do you think of my teaching concept, to try to explain why a
> `7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
> self-evident or intuitive in both the original text and your patch?

I think it's out of place in the coreutils manual, just as (for example) 
the manual need not mention computer keyboard layouts in order to tell 
users how to type 'sort -r'. Assuming basic computer concepts simplifies 
the manual and makes it easier for typical users to read, which is a win.

> 		
> where would be a place, to formulate the problem `7=4+2+1'
> more generally?

One place would be:

https://en.wikipedia.org/wiki/Octal


> Why didn't you take over my correction from "are sometimes special" to
> "have a special meaning for directories" ?

I didn't think that was necessary, since the parenthesized 
cross-reference already mentioned "Directory". The main point here is 
that the leading "0" is not necessary, not that excess leading "0"s 
sometimes have special meanings.

Message #48 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: kalle <kalle <at> projektwerkstatt.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#31043: [PATCH] changed presentation in 'File permissions' in
 'numeric, modes'
Date: Wed, 11 Apr 2018 14:44:36 +0200

Am 04.04.2018 um 00:10 schrieb Paul Eggert:
> On 04/03/2018 12:29 PM, kalle wrote:
>>
>> But what do you think of my teaching concept, to try to explain why a
>> `7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
>> self-evident or intuitive in both the original text and your patch?
> 
> I think it's out of place in the coreutils manual, just as (for example)
> the manual need not mention computer keyboard layouts in order to tell
> users how to type 'sort -r'. Assuming basic computer concepts simplifies
> the manual and makes it easier for typical users to read, which is a win.

I find your example far away from the actual problem: computer keyboard
layouts and how to define them is important but much more  general than
'sort -r' and in my opinion it should be described somewhere (actually
keymaps(5),loadkeys(1) and so forth) and be referred to at crucial moments.
While for `File Permission', I don't even know if this methodology of
encoding information (I mean "symbolical notation rwx for owner =
symbolical notation rwx = symbolical notation 111= interpreting 111
numerically in binary = transforming to numerical octal 7") is just used
in this special case or is used more generally throughout the GNU
programs. In any case it is _not_ just octal, but a specific way of
translating numerical octal to a symbolic notation (and that's what I
tried to explain in my patch) even if some nerds knew it's meaning by
experience.
At least it should be referred to the place, where the concept is
explained. And referencing to the internet is non an elegant way, as it
could be the case, that the person doesn't have any access to it.

Assuming that new users necessarily know about this special way of using
octal numbers is simply newbie-unfriendly. Imagine someone starting to
learn `ls' or `mv' or just 'File Permissions' now directly being stuck
with this methodology.

What is this person expected to have read before starting learning how
to work with the CLI through documentation-systems as `info' or `man'
apart from complicated imperialist english language?


after my patch proposal, paul eggert wrote:
"I think part of the problem is that this is not really the place to
explain octal notation; any reader who doesn't know octal before reading
the manual is not likely to understand it even with the proposed
rewrite. I think we should just give up and assume that the reader knows
octal (if they don't they should be using symbolic modes)."

The more appropriate way imo would be to look up for a good place for a
explanation rather than "giving up" so quickly.

kalle

Message #51 received at 29069 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: kalle <kalle <at> projektwerkstatt.de>, 29069 <at> debbugs.gnu.org
Subject: Re: bug#29069: bug#31043: [PATCH] changed presentation in 'File
 permissions' in 'numeric, modes'
Date: Fri, 13 Apr 2018 12:55:19 -0700

On 04/11/2018 05:44 AM, kalle wrote:
> I don't even know if this methodology of
> encoding information (I mean "symbolical notation rwx for owner =
> symbolical notation rwx = symbolical notation 111= interpreting 111
> numerically in binary = transforming to numerical octal 7") is just used
> in this special case or is used more generally throughout the GNU
> programs.

The symbolic notation's primary use is in the core GNU (and POSIX) 
utilities. It was introduced in Unix (a predecessor to GNU/Linux) and is 
standardized by POSIX. The symbolic notation is not generally used 
elsewhere, so it's good to document it in the coreutils manual. In 
contrast, octal numbers are generally used throughout computing and 
mathematics, and we shouldn't have to explain them here.

I'd be more sympathetic if octal numbers were required. But users don't 
have to use them; they can use symbolic modes. That's what symbolic 
modes were invented for: to help users who don't understand or like 
octal. The documentation should exploit this, not fight it.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.