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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 45258 in the body.
You can then email your comments to 45258 AT debbugs.gnu.org in the normal way.

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

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

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 1 (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 2 (text/html, inline)]

Message #10 received at 45258-done <at> debbugs.gnu.org (full text, mbox):

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 1 (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 #13 received at 45258 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: 45258 <at> debbugs.gnu.org, eggert <at> cs.ucla.edu, chris <at> colohan.com
Subject: Re: bug#45258: mkdir man page unclear in describing -m flag
Date: Tue, 15 Dec 2020 20:42:07 +0000

On 15/12/2020 20:00, Paul Eggert wrote:
> 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.

I agree with adding the clarification to the man page,
thanks for doing that.

I also added an entry to:
http://www.pixelbeat.org/docs/coreutils-gotchas.html#mkdir

cheers,
Pádraig

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

From: Chris Colohan <chris <at> colohan.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
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:26:06 -0800

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

Looks great, thank you so much!

Chris

On Tue, Dec 15, 2020 at 12:00 PM Paul Eggert <eggert <at> cs.ucla.edu> wrote:

> 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.
>

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

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: 45258 <at> debbugs.gnu.org, eggert <at> cs.ucla.edu, chris <at> colohan.com
Subject: Re: bug#45258: mkdir man page unclear in describing -m flag
Date: Wed, 16 Dec 2020 09:28:52 +0100

On 12/15/20 9:00 PM, Paul Eggert wrote:
> 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.

Thanks for clarifying.

> +If the @option{-m} option is also given, it does not affect
> +file permission bits of any newly-created parent directories.
> +To control these bits, set the
>  umask before invoking @command{mkdir}. [...]

Some further thoughts on this - maybe just for my reference:

One aspect of using -p is that the user doesn't want to get an error if
the target or any of its parent directories already exists.

If changing the umask before invoking mkdir is not that easy - maybe
because not called via a shell -, then an alternative to the above
umask method is to reference each of the target directories separately,
e.g.:
  $ mkdir -pm 0700  dir1  dir1/dir2  dir1/dir2/dir3

But it is important to know that 'mkdir' does not adjust the permission
bits of any of those already existing directories.

Therefore, if one does not want to get a failure for already existing
intermediate directories, and still wants their permission bits to get
adjusted, then one can use 'install' instead of 'mkdir' (still passing
each directory level as separate argument!):

  $ install -dm 0700  dir1  dir1/dir2  dir1/dir2/dir3

Have a nice day,
Berny

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

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>, 45258 <at> debbugs.gnu.org,
 eggert <at> cs.ucla.edu, chris <at> colohan.com
Subject: Re: bug#45258: mkdir man page unclear in describing -m flag
Date: Wed, 16 Dec 2020 13:34:38 +0000

On 16/12/2020 08:28, Bernhard Voelker wrote:
> On 12/15/20 9:00 PM, Paul Eggert wrote:
>> 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.
> 
> Thanks for clarifying.
> 
>> +If the @option{-m} option is also given, it does not affect
>> +file permission bits of any newly-created parent directories.
>> +To control these bits, set the
>>   umask before invoking @command{mkdir}. [...]
> 
> Some further thoughts on this - maybe just for my reference:
> 
> One aspect of using -p is that the user doesn't want to get an error if
> the target or any of its parent directories already exists.
> 
> If changing the umask before invoking mkdir is not that easy - maybe
> because not called via a shell -, then an alternative to the above
> umask method is to reference each of the target directories separately,
> e.g.:
>    $ mkdir -pm 0700  dir1  dir1/dir2  dir1/dir2/dir3
> 
> But it is important to know that 'mkdir' does not adjust the permission
> bits of any of those already existing directories.
> 
> Therefore, if one does not want to get a failure for already existing
> intermediate directories, and still wants their permission bits to get
> adjusted, then one can use 'install' instead of 'mkdir' (still passing
> each directory level as separate argument!):
> 
>    $ install -dm 0700  dir1  dir1/dir2  dir1/dir2/dir3

Insightful comments. I've updated the gotchas note with them:
https://www.pixelbeat.org/docs/coreutils-gotchas.html#mkdir

cheers,
Pádraig

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

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>, 45258 <at> debbugs.gnu.org, 
 eggert <at> cs.ucla.edu, chris <at> colohan.com
Subject: Re: bug#45258: mkdir man page unclear in describing -m flag
Date: Wed, 16 Dec 2020 23:42:05 +0100

On 12/16/20 2:34 PM, Pádraig Brady wrote:
> Insightful comments. I've updated the gotchas note with them:
> https://www.pixelbeat.org/docs/coreutils-gotchas.html#mkdir

Nice, and also better wording than mine, thanks!

Have a nice day,
Berny

Previous Next

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