bug#45258: closed (mkdir man page unclear in describing -m flag)

[GNU bug Tracking System]

Your message dated Tue, 15 Dec 2020 12:00:49 -0800
with message-id <38f8d820-9eb9-fb6c-c7cb-e86c3c7bb667@cs.ucla.edu>
and subject line Re: bug#45258: mkdir man page unclear in describing -m flag
has caused the debbugs.gnu.org bug report #45258,
regarding mkdir man page unclear in describing -m flag
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs@gnu.org.)


-- 
45258: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=45258
GNU Bug Tracking System
Contact help-debbugs@gnu.org with problems

--- Begin Message --- Subject: mkdir man page unclear in describing -m flag Date: Tue, 15 Dec 2020 09:48:04 -0800

I like to present a challenge to my software engineer friends:  can you tell me what this command does on Linux, if run in an empty directory?

mkdir -m 0755 -p ./usr/bin/foo

If they read the mkdir man page (https://man7.org/linux/man-pages/man1/mkdir.1.html), they almost always say the answer is:

- create the directory ./usr, with the mode 0755

- create the directory ./usr/bin, with the mode 0755

- create the directory ./usr/bin/foo, with the mode 0755

They are wrong.  (Side note -- this misunderstanding contributed to one of the scariest outages Google has ever seen, https://www.pdl.cmu.edu/SDI/2012/083012b.html).

What it actually does:

- create the directory ./usr, with the mode based on the umask

- create the directory ./usr/bin, with the mode based on the umask

- create the directory ./usr/bin/foo, with the mode 0755

I tried at the time to get the man page corrected, but I was told at the time that nobody reads man pages, and the info page is correct, so it won't be fixed.

I figured after almost 10 years, perhaps thinking has evolved.  Can we fix the man page?

I have a suggested fix:  the current man page reads:

       -p, --parents
              no error if existing, make parent directories as needed

I can be updated to read:

       -p, --parents
              no error if existing, make parent directories as needed, setting

              their file permission bits to the umask modified by ‘u+wx’.

I copied the new text from the info page.

Thanks!

Chris

--- End Message ---

--- Begin Message --- Subject: Re: bug#45258: mkdir man page unclear in describing -m flag Date: Tue, 15 Dec 2020 12:00:49 -0800 User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.5.0 Thanks for your bug report. I installed the attached patch; although it doesn't use the exact wording you proposed, I hope it works well enough.

0001-doc-document-mkdir-m-p-better.patch
Description: Text Data

--- End Message ---