Skip Menu |
Report information
Id: 132505
Status: resolved
Priority: 0/
Queue: perl5

Owner: Nobody
Requestors: slaven [at] rezic.de
Cc:
AdminCc:

Operating System: (no value)
PatchStatus: (no value)
Severity: low
Type: unknown
Perl Version: (no value)
Fixed In: (no value)

Attachments


From: slaven [...] rezic.de
Subject: mkdir documentation: MASK -> MODE?
Date: Sat, 25 Nov 2017 15:34:39 +0100
To: perlbug [...] perl.org
CC: srezic [...] cpan.org
Download (untitled) / with headers
text/plain 3.3k
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
From: "H.Merijn Brand" <h.m.brand [...] xs4all.nl>
Subject: Re: [perl #132505] mkdir documentation: MASK -> MODE?
To: perl5-porters [...] perl.org
Date: Sat, 25 Nov 2017 16:17:50 +0100
Download (untitled) / with headers
text/plain 731b
On Sat, 25 Nov 2017 06:35:42 -0800, "slaven@rezic.de (via RT)" <perlbug-followup@perl.org> wrote: Show quoted text
> perlfunc.pod names the second argument of mkdir() "MASK". I think > this is not correct, it should be "MODE".
Agree Show quoted text
> 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/
Download (untitled)
application/pgp-signature 473b

Message body not shown because it is not plain text.

RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 658b
On Sat, 25 Nov 2017 06:35:41 -0800, slaven@rezic.de wrote: Show quoted text
> > 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
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 619b
Show quoted text
> 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
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 169b
On Sun, 26 Nov 2017 02:33:56 -0800, jhi wrote: Show quoted text
> It is the mode (positive bits), not a mask (negative bits).
Thank you for the clarification. -- Father Chrysostomos
RT-Send-CC: perl5-porters [...] perl.org
The attached patch should resolve this
Subject: 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
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 114b
Dana Tue, 28 Nov 2017 04:51:53 -0800, mfontani reče: Show quoted text
> The attached patch should resolve this
Looks fine to me.
Subject: Re: [perl #132505] mkdir documentation: MASK -> MODE?
Date: Wed, 29 Nov 2017 08:47:08 +0000
CC: Perl5 Porters <perl5-porters [...] perl.org>
To: James E Keenan via RT <perlbug-followup [...] perl.org>
From: Aaron Crane <arc [...] cpan.org>
Download (untitled) / with headers
text/plain 273b
Marco Fontani via RT <perlbug-followup@perl.org> wrote: Show quoted text
> The attached patch should resolve this
Thanks, applied as c6841f364f3bce268876ec3511ee74a818605277 (with one minor fixup to make t/porting/podcheck.t pass). You are now a Perl author — welcome! -- Aaron Crane


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org