GNU bug report logs - #45258
mkdir man page unclear in describing -m flag

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Chris Colohan <chris <at> colohan.com>
Subject: bug#45258: closed (Re: bug#45258: mkdir man page unclear in
 describing -m flag)
Date: Tue, 15 Dec 2020 20:01:01 +0000

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

Your bug report

#45258: mkdir man page unclear in describing -m flag

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 45258 <at> debbugs.gnu.org.

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

[Message part 2 (message/rfc822, inline)]

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Chris Colohan <chris <at> colohan.com>
Cc: 45258-done <at> debbugs.gnu.org
Subject: Re: bug#45258: mkdir man page unclear in describing -m flag
Date: Tue, 15 Dec 2020 12:00:49 -0800

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

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 (text/x-patch, attachment)]

[Message part 5 (message/rfc822, inline)]

From: Chris Colohan <chris <at> colohan.com>
To: bug-coreutils <at> gnu.org
Subject: mkdir man page unclear in describing -m flag
Date: Tue, 15 Dec 2020 09:48:04 -0800

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

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

[Message part 7 (text/html, inline)]

Previous Next

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