Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

mkdir documentation: MASK -> MODE? #16278

Closed
p5pRT opened this issue Nov 25, 2017 · 11 comments
Closed

mkdir documentation: MASK -> MODE? #16278

p5pRT opened this issue Nov 25, 2017 · 11 comments

Comments

@p5pRT
Copy link

p5pRT commented Nov 25, 2017

Migrated from rt.perl.org#132505 (status was 'resolved')

Searchable as RT132505$

@p5pRT
Copy link
Author

p5pRT commented Nov 25, 2017

From @eserte

This is a bug report for perl from slaven@​rezic.de,
generated with the help of perlbug 1.40 running under perl 5.26.1.


perlfunc.pod names the second argument of mkdir() "MASK". I think
this is not correct, it should be "MODE".

Note also that "man 2 mkdir" also names the second argument "mode"
(checked on Debian Linux & FreeBSD).



Flags​:
  category=docs
  severity=low


This perlbug was built using Perl 5.20.2 - Mon Sep 18 18​:13​:32 UTC 2017
It is being executed now by Perl 5.26.1 - Sat Sep 23 09​:36​:11 CEST 2017.

Site configuration information for perl 5.26.1​:

Configured by eserte at Sat Sep 23 09​:36​:11 CEST 2017.

Summary of my perl5 (revision 5 version 26 subversion 1) configuration​:
 
  Platform​:
  osname=linux
  osvers=3.16.0-4-amd64
  archname=x86_64-linux
  uname='linux cabulja 3.16.0-4-amd64 #1 smp debian 3.16.39-1+deb8u2 (2017-03-07) x86_64 gnulinux '
  config_args='-ds -e -Dprefix=/opt/perl-5.26.1 -Dcf_email=srezic@​cpan.org'
  hint=recommended
  useposix=true
  d_sigaction=define
  useithreads=undef
  usemultiplicity=undef
  use64bitint=define
  use64bitall=define
  uselongdouble=undef
  usemymalloc=n
  default_inc_excludes_dot=define
  bincompat5005=undef
  Compiler​:
  cc='cc'
  ccflags ='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -D_FORTIFY_SOURCE=2'
  optimize='-O2'
  cppflags='-fwrapv -fno-strict-aliasing -pipe -fstack-protector-strong -I/usr/local/include'
  ccversion=''
  gccversion='4.9.2'
  gccosandvers=''
  intsize=4
  longsize=8
  ptrsize=8
  doublesize=8
  byteorder=12345678
  doublekind=3
  d_longlong=define
  longlongsize=8
  d_longdbl=define
  longdblsize=16
  longdblkind=3
  ivtype='long'
  ivsize=8
  nvtype='double'
  nvsize=8
  Off_t='off_t'
  lseeksize=8
  alignbytes=8
  prototype=define
  Linker and Libraries​:
  ld='cc'
  ldflags =' -fstack-protector-strong -L/usr/local/lib'
  libpth=/usr/local/lib /usr/lib/gcc/x86_64-linux-gnu/4.9/include-fixed /usr/include/x86_64-linux-gnu /usr/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib
  libs=-lpthread -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc -lgdbm_compat
  perllibs=-lpthread -lnsl -ldl -lm -lcrypt -lutil -lc
  libc=libc-2.19.so
  so=so
  useshrplib=false
  libperl=libperl.a
  gnulibc_version='2.19'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs
  dlext=so
  d_dlsymun=undef
  ccdlflags='-Wl,-E'
  cccdlflags='-fPIC'
  lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector-strong'


@​INC for perl 5.26.1​:
  /opt/perl-5.26.1/lib/site_perl/5.26.1/x86_64-linux
  /opt/perl-5.26.1/lib/site_perl/5.26.1
  /opt/perl-5.26.1/lib/5.26.1/x86_64-linux
  /opt/perl-5.26.1/lib/5.26.1


Environment for perl 5.26.1​:
  HOME=/home/eserte
  LANG=en_US.UTF-8
  LANGUAGE (unset)
  LD_LIBRARY_PATH (unset)
  LOGDIR (unset)
  PATH=/usr/local/bin​:/usr/bin​:/bin​:/usr/local/sbin​:/usr/sbin​:/sbin​:/home/eserte/bin/linux-gnu​:/home/eserte/bin/sh​:/home/eserte/bin​:/home/eserte/bin/pistachio-perl/bin​:/usr/games​:/home/eserte/devel
  PERLDOC=-MPod​::Perldoc​::ToTextOverstrike
  PERL_BADLANG (unset)
  SHELL=/bin/zsh

@p5pRT
Copy link
Author

p5pRT commented Nov 25, 2017

From @Tux

On Sat, 25 Nov 2017 06​:35​:42 -0800, "slaven@​rezic.de (via RT)"
<perlbug-followup@​perl.org> wrote​:

perlfunc.pod names the second argument of mkdir() "MASK". I think
this is not correct, it should be "MODE".

Agree

Note also that "man 2 mkdir" also names the second argument "mode"
(checked on Debian Linux & FreeBSD).

HP-UX

SYNOPSIS
  mkdir [-p] [-m mode] dirname ...

AIX

Syntax

  mkdir [ -m Mode ] [ -p ] Directory ...

--
H.Merijn Brand http​://tux.nl Perl Monger http​://amsterdam.pm.org/
using perl5.00307 .. 5.27 porting perl5 on HP-UX, AIX, and openSUSE
http​://mirrors.develooper.com/hpux/ http​://www.test-smoke.org/
http​://qa.perl.org http​://www.goldmark.org/jeff/stupid-disclaimers/

@p5pRT
Copy link
Author

p5pRT commented Nov 25, 2017

The RT System itself - Status changed from 'new' to 'open'

@p5pRT
Copy link
Author

p5pRT commented Nov 25, 2017

From @cpansprout

On Sat, 25 Nov 2017 06​:35​:41 -0800, slaven@​rezic.de wrote​:

This is a bug report for perl from slaven@​rezic.de,
generated with the help of perlbug 1.40 running under perl 5.26.1.

-----------------------------------------------------------------
perlfunc.pod names the second argument of mkdir() "MASK". I think
this is not correct, it should be "MODE".

Note also that "man 2 mkdir" also names the second argument "mode"
(checked on Debian Linux & FreeBSD).

The second argument *is* a bitmask, and MASK is more specific than MODE. Don’t forget "rwxr-xr-x" is a mode, but not one that mkdir will support.

--

Father Chrysostomos

@p5pRT
Copy link
Author

p5pRT commented Nov 26, 2017

From @jhi

The second argument *is* a bitmask, and MASK is more specific than
MODE. Don’t forget "rwxr-xr-x" is a mode, but not one that mkdir will
support.

Sorry, but this is not true.

http​://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdir.html

It is the mode (positive bits), not a mask (negative bits). It is *modified* by the process umask.

The reference to "rwxr-xr-x" is somewhat irrelevant, since that is for the command line utilities,
Perl's mkdir() is a system call. But for completeness' sake, it's "mode" there too.

http​://pubs.opengroup.org/onlinepubs/9699919799/utilities/mkdir.html

@p5pRT
Copy link
Author

p5pRT commented Nov 26, 2017

From @cpansprout

On Sun, 26 Nov 2017 02​:33​:56 -0800, jhi wrote​:

It is the mode (positive bits), not a mask (negative bits).

Thank you for the clarification.

--

Father Chrysostomos

@p5pRT
Copy link
Author

p5pRT commented Nov 28, 2017

From @mfontani

The attached patch should resolve this

@p5pRT
Copy link
Author

p5pRT commented Nov 28, 2017

From @mfontani

0001-second-arg-to-mkdir-is-MODE-not-MASK.patch
From 03ef34ccdc68742ab2024e720042b32b5b6a1872 Mon Sep 17 00:00:00 2001
From: Marco Fontani <MFONTANI@cpan.org>
Date: Tue, 28 Nov 2017 13:43:36 +0100
Subject: [PATCH] second arg to mkdir is MODE, not MASK

RT# 132505
---
 pod/perlfunc.pod | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git pod/perlfunc.pod pod/perlfunc.pod
index ee8ec3d9f2..6b96f99e04 100644
--- pod/perlfunc.pod
+++ pod/perlfunc.pod
@@ -241,7 +241,7 @@ L<C<chroot>|/chroot FILENAME>,
 L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>, L<C<glob>|/glob EXPR>,
 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>,
 L<C<link>|/link OLDFILE,NEWFILE>, L<C<lstat>|/lstat FILEHANDLE>,
-L<C<mkdir>|/mkdir FILENAME,MASK>, L<C<open>|/open FILEHANDLE,EXPR>,
+L<C<mkdir>|/mkdir FILENAME,MODE>, L<C<open>|/open FILEHANDLE,EXPR>,
 L<C<opendir>|/opendir DIRHANDLE,EXPR>, L<C<readlink>|/readlink EXPR>,
 L<C<rename>|/rename OLDNAME,NEWNAME>, L<C<rmdir>|/rmdir FILENAME>,
 L<C<select>|/select FILEHANDLE>, L<C<stat>|/stat FILEHANDLE>,
@@ -4148,7 +4148,7 @@ or to force an anon hash constructor use C<+{>:
 
 to get a list of anonymous hashes each with only one entry apiece.
 
-=item mkdir FILENAME,MASK
+=item mkdir FILENAME,MODE
 X<mkdir> X<md> X<directory, create>
 
 =item mkdir FILENAME
@@ -4158,19 +4158,19 @@ X<mkdir> X<md> X<directory, create>
 =for Pod::Functions create a directory
 
 Creates the directory specified by FILENAME, with permissions
-specified by MASK (as modified by L<C<umask>|/umask EXPR>).  If it
+specified by MODE (as modified by L<C<umask>|/umask EXPR>).  If it
 succeeds it returns true; otherwise it returns false and sets
 L<C<$!>|perlvar/$!> (errno).
-MASK defaults to 0777 if omitted, and FILENAME defaults
+MODE defaults to 0777 if omitted, and FILENAME defaults
 to L<C<$_>|perlvar/$_> if omitted.
 
-In general, it is better to create directories with a permissive MASK
+In general, it is better to create directories with a permissive MODE
 and let the user modify that with their L<C<umask>|/umask EXPR> than it
 is to supply
-a restrictive MASK and give the user no way to be more permissive.
+a restrictive MODE and give the user no way to be more permissive.
 The exceptions to this rule are when the file or directory should be
 kept private (mail files, for instance).  The documentation for
-L<C<umask>|/umask EXPR> discusses the choice of MASK in more detail.
+L<C<umask>|/umask EXPR> discusses the choice of MODE in more detail.
 
 Note that according to the POSIX 1003.1-1996 the FILENAME may have any
 number of trailing slashes.  Some operating and filesystems do not get
-- 
2.15.0

@p5pRT
Copy link
Author

p5pRT commented Nov 29, 2017

From @eserte

Dana Tue, 28 Nov 2017 04​:51​:53 -0800, mfontani reče​:

The attached patch should resolve this

Looks fine to me.

@p5pRT
Copy link
Author

p5pRT commented Nov 29, 2017

@arc - Status changed from 'open' to 'resolved'

@p5pRT p5pRT closed this as completed Nov 29, 2017
@p5pRT
Copy link
Author

p5pRT commented Nov 29, 2017

From @arc

Marco Fontani via RT <perlbug-followup@​perl.org> wrote​:

The attached patch should resolve this

Thanks, applied as c6841f3 (with one
minor fixup to make t/porting/podcheck.t pass).

You are now a Perl author — welcome!

--
Aaron Crane

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant