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

Owner: Nobody
Requestors: tlhackque <tlhackque [at] yahoo.com>
Cc:
AdminCc:

Operating System: Linux
PatchStatus: (no value)
Severity: low
Type: core
Perl Version: 5.14.3
Fixed In: (no value)

Attachments
0001-mention-perldoc-warnings-in-perlfunc.patch
0001-perlfunc-remove-stray-plus-from-start-of-line.patch



Subject: Doc issues for system, exec, qx
Date: Thu, 13 Dec 2012 10:18:56 -0500
To: perlbug [...] perl.org
From: tlhackque [...] yahoo.com
Download (untitled) / with headers
text/plain 5.3k
This is a bug report for perl from tlhackque@yahoo.com, generated with the help of perlbug 1.39 running under perl 5.14.3. ----------------------------------------------------------------- [Please describe your issue here] Functions using 'exec' (at least exec, system qx) generate warnings if 'use warnings;' is in effect. This isn't a bad thing - but the fact that the documentation for these functions doesn't mention this is. Especially since the documentation emphasizes that one really should 'use warnings' everywhere. (And one should. And I do.) The only documented exception from these functions is 'die' on tainted input. Please update these functions to indicate that: o They generate call warn() on errors running the command if 'use warnings' is in effect; and o The category to disable these warnings (if, for example one is checking the return status & expects failures in some environments) is "no warnings 'exec';" Actually, it would be really helpful if every function that registers with 'use warnings' would include similar info in its documentation. It took rather some tracking down - and some guesswork - to solve an issue caused by this behavior. Even though I did read the manual (and the book and the perldoc and the perl website...) Thanks. [Please do not change anything below this line] ----------------------------------------------------------------- --- Flags: category=core severity=low --- This perlbug was built using Perl 5.14.3 in the Fedora build system. It is being executed now by Perl 5.14.3 - Thu Oct 18 13:30:29 UTC 2012. Site configuration information for perl 5.14.3: Configured by Red Hat, Inc. at Thu Oct 18 13:30:29 UTC 2012. Summary of my perl5 (revision 5 version 14 subversion 3) configuration: Platform: osname=linux, osvers=2.6.32-279.9.1.el6.x86_64, archname=x86_64-linux-thread-multi uname='linux buildvm-03.phx2.fedoraproject.org 2.6.32-279.9.1.el6.x86_64 #1 smp fri aug 31 09:04:24 edt 2012 x86_64 x86_64 x86_64 gnulinux ' config_args='-des -Doptimize=-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector --param=ssp-buffer-size=4 -m64 -mtune=generic -Dccdlflags=-Wl,--enable-new-dtags -Dlddlflags=-shared -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector --param=ssp-buffer-size=4 -m64 -mtune=generic -Wl,-z,relro -DDEBUGGING=-g -Dversion=5.14.3 -Dmyhostname=localhost -Dperladmin=root@localhost -Dcc=gcc -Dcf_by=Red Hat, Inc. -Dprefix=/usr -Dvendorprefix=/usr -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl5 -Dsitearch=/usr/local/lib64/perl5 -Dprivlib=/usr/share/perl5 -Dvendorlib=/usr/share/perl5/vendor_perl -Darchlib=/usr/lib64/perl5 -Dvendorarch=/usr/lib64/perl5/vendor_perl -Darchname=x86_64-linux-thread-multi -Dlibpth=/usr/local/lib64 /lib64 /usr/lib64 -Duseshrplib -Dusethreads -Duseithreads -Dusedtrace=/usr/bin/dtrace -Duselargefiles -Dd_semctl_semun -Di_db -Ui_ndbm -Di_gdbm -Di_shadow -Di_syslog -Dman3ext=3pm -Duseperlio -Dinstallusrbin! perl=n -Ubincompat5005 -Uversiononly -Dpager=/usr/bin/less -isr -Dd_gethostent_r_proto -Ud_endhostent_r_proto -Ud_sethostent_r_proto -Ud_endprotoent_r_proto -Ud_setprotoent_r_proto -Ud_endservent_r_proto -Ud_setservent_r_proto -Dscriptdir=/usr/bin' hint=recommended, useposix=true, d_sigaction=define useithreads=define, usemultiplicity=define useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef use64bitint=define, use64bitall=define, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='gcc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64', optimize='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector --param=ssp-buffer-size=4 -m64 -mtune=generic', cppflags='-D_REENTRANT -D_GNU_SOURCE -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include' ccversion='', gccversion='4.7.2 20120921 (Red Hat 4.7.2-2)', gccosandvers='' intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16 ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8 alignbytes=8, prototype=define Linker and Libraries: ld='gcc', ldflags =' -fstack-protector' libpth=/usr/local/lib64 /lib64 /usr/lib64 libs=-lresolv -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lpthread -lc -lgdbm_compat perllibs=-lresolv -lnsl -ldl -lm -lcrypt -lutil -lpthread -lc libc=, so=so, useshrplib=true, libperl=libperl.so gnulibc_version='2.15' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,--enable-new-dtags -Wl,-rpath,/usr/lib64/perl5/CORE' cccdlflags='-fPIC', lddlflags='-shared -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector --param=ssp-buffer-size=4 -m64 -mtune=generic -Wl,-z,relro ' Locally applied patches: --- @INC for perl 5.14.3: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 . --- Environment for perl 5.14.3: HOME=/root LANG=en_US.UTF-8 LANGUAGE (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/usr/lib64/qt-3.3/bin:/usr/lib64/ccache:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/root/bin PERL_BADLANG (unset) SHELL=/bin/bash
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 1.6k
On Thu Dec 13 07:19:45 2012, tlhackque wrote: Show quoted text
> > This is a bug report for perl from tlhackque@yahoo.com, > generated with the help of perlbug 1.39 running under perl 5.14.3. > > > ----------------------------------------------------------------- > [Please describe your issue here] > > Functions using 'exec' (at least exec, system qx) generate warnings if > 'use warnings;' is in effect. > > This isn't a bad thing - but the fact that the documentation for these > functions doesn't mention this is.
My impression is that for most of the built-in functions there is no specific discussion of how they work under "use warnings" -- nor would I expect there to be. So it's not clear to me why this is somehow a bigger documentation problem for 'system' and 'exec' than for other built-ins. Show quoted text
> Especially since the documentation emphasizes that one really should > 'use warnings' everywhere. > (And one should. And I do.) > > The only documented exception from these functions is 'die' on tainted > input. > > Please update these functions to indicate that: > o They generate call warn() on errors running the command if 'use > warnings' is in effect; and > o The category to disable these warnings (if, for example one is > checking the return status & expects failures in some environments) > is "no warnings 'exec';" > > Actually, it would be really helpful if every function that registers > with 'use warnings' would include similar info in its > documentation. > > It took rather some tracking down - and some guesswork - to solve an > issue caused by this behavior. Even though I did read the manual > (and the book and the perldoc and the perl website...) > > Thanks.
CC: perl5-porters [...] perl.org
Subject: Re: [perl #116080] Doc issues for system, exec, qx
Date: Thu, 13 Dec 2012 21:06:35 -0600
To: James E Keenan via RT <perlbug-followup [...] perl.org>
From: Jesse Luehrs <doy [...] tozt.net>
Download (untitled) / with headers
text/plain 2.1k
On Thu, Dec 13, 2012 at 07:02:04PM -0800, James E Keenan via RT wrote: Show quoted text
> On Thu Dec 13 07:19:45 2012, tlhackque wrote:
> > > > This is a bug report for perl from tlhackque@yahoo.com, > > generated with the help of perlbug 1.39 running under perl 5.14.3. > > > > > > ----------------------------------------------------------------- > > [Please describe your issue here] > > > > Functions using 'exec' (at least exec, system qx) generate warnings if > > 'use warnings;' is in effect. > > > > This isn't a bad thing - but the fact that the documentation for these > > functions doesn't mention this is.
> > My impression is that for most of the built-in functions there is no > specific discussion of how they work under "use warnings" -- nor would I > expect there to be. > > So it's not clear to me why this is somehow a bigger documentation > problem for 'system' and 'exec' than for other built-ins. >
> > Especially since the documentation emphasizes that one really should > > 'use warnings' everywhere. > > (And one should. And I do.) > > > > The only documented exception from these functions is 'die' on tainted > > input. > > > > Please update these functions to indicate that: > > o They generate call warn() on errors running the command if 'use > > warnings' is in effect; and > > o The category to disable these warnings (if, for example one is > > checking the return status & expects failures in some environments) > > is "no warnings 'exec';" > > > > Actually, it would be really helpful if every function that registers > > with 'use warnings' would include similar info in its > > documentation. > > > > It took rather some tracking down - and some guesswork - to solve an > > issue caused by this behavior. Even though I did read the manual > > (and the book and the perldoc and the perl website...) > > > > Thanks.
These sorts of things are all documented in 'perldoc perllexwarn' and 'perldoc perldiag', but it's quite true that that's not a particularly obvious place for people who are unaware of those documents. I don't think that every builtin that warns needs to have a pointer to the perldiag pod, but I'm not sure where a good place to mention it is. -doy
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 4.6k
I think it's a problem for all built-ins; it just happened that exec was the one that wasted a couple of hours of my time yesterday. As a user of functions, I expect the man/perldoc page for a function to document its API. (Not just built-ins, BTW.) Exception (and WARN is an exception) conditions are part of the API spec of a function. The functions doc in the camel book have standard anotation symbols for "$_", "$!", "$@", "$?" "T": and the exception conditions: "XARG", "XRO" "XT" and "XU". Why not add a "XW" for warnings? It doesn't have to be a detailed pointer with every function. Just (as in the camel book), a glossary of the standard annotations in perlfunc, and annotate the individual functions. I'd prefer to see "XW:category" - that doesn't take much space, and it seems more likely that the function will be kept up-to-date than the general warnings doc. (BTW, I saw the 'exec' category there, but no list of what functions are in that category.) perldoc warnings doesn't tell me what I need to know. perllexwarn (hardly ovbious) has the taxonomy, and tells me to see perldiag for the categories. But perldiag has a list of error error messages, severity and category. But: it doesn't say what functions generate them. So even inverting it doesn't tell me the consequences of using a function - and what conditions my code has to be prepared to handle. From a user's point of view: I select a function that does what I want. Then when I invoke it, I need to know about the inputs, outputs and side effects. Do I need an eval to trap die? Will it signal a warn (that I need to trap - e.g. in a CGI app? Or under Assert?) In my case, I had code that "worked" - until someone enabled an Assert variant that did $SIG{__WARN__} = sub { die $@ }; Oops. If context helps, the code attempted to run selinuxenabled to see if it was on a SELinux system. It carefully checked the return value of system(). But it had no reason to expect an exception. (Or output on stderr, but I handled that.) Several projects that I've been involved with are leary of running with warnings trapped because of these pitfalls. That's not a good thing. So I do think this needs to be addressed. We do want people to write robust code - and knowing what a function can do is essential. On Thu Dec 13 19:07:09 2012, doy@tozt.net wrote: Show quoted text
> On Thu, Dec 13, 2012 at 07:02:04PM -0800, James E Keenan via RT wrote:
> > On Thu Dec 13 07:19:45 2012, tlhackque wrote:
> > > > > > This is a bug report for perl from tlhackque@yahoo.com, > > > generated with the help of perlbug 1.39 running under perl 5.14.3. > > > > > > > > > ----------------------------------------------------------------- > > > [Please describe your issue here] > > > > > > Functions using 'exec' (at least exec, system qx) generate
warnings if Show quoted text
> > > 'use warnings;' is in effect. > > > > > > This isn't a bad thing - but the fact that the documentation for
these Show quoted text
> > > functions doesn't mention this is.
> > > > My impression is that for most of the built-in functions there is no > > specific discussion of how they work under "use warnings" -- nor
would I Show quoted text
> > expect there to be. > > > > So it's not clear to me why this is somehow a bigger documentation > > problem for 'system' and 'exec' than for other built-ins. > >
> > > Especially since the documentation emphasizes that one really
should Show quoted text
> > > 'use warnings' everywhere. > > > (And one should. And I do.) > > > > > > The only documented exception from these functions is 'die' on
tainted Show quoted text
> > > input. > > > > > > Please update these functions to indicate that: > > > o They generate call warn() on errors running the command
if 'use Show quoted text
> > > warnings' is in effect; and > > > o The category to disable these warnings (if, for example one is > > > checking the return status & expects failures in some
environments) Show quoted text
> > > is "no warnings 'exec';" > > > > > > Actually, it would be really helpful if every function that
registers Show quoted text
> > > with 'use warnings' would include similar info in its > > > documentation. > > > > > > It took rather some tracking down - and some guesswork - to solve
an Show quoted text
> > > issue caused by this behavior. Even though I did read the
manual Show quoted text
> > > (and the book and the perldoc and the perl website...) > > > > > > Thanks.
> > These sorts of things are all documented in 'perldoc perllexwarn' and > 'perldoc perldiag', but it's quite true that that's not a particularly > obvious place for people who are unaware of those documents. I don't > think that every builtin that warns needs to have a pointer to the > perldiag pod, but I'm not sure where a good place to mention it is. > > -doy >
To: perl5-porters [...] perl.org
Date: Tue, 12 Dec 2017 22:31:48 +0000
Subject: Re: [perl #116080] Doc issues for system, exec, qx
From: Zefram <zefram [...] fysh.org>
Download (untitled) / with headers
text/plain 414b
In perldiag we already have systematic documentation of all the warnings, listing category and describing in what circumstances they can arise. Attempting to list the warnings from the other end, in the form of which warnings can arise from each function and operator, would be crazy, because internal code factoring means that a lot of warnings can arise from many places. This ticket should be closed. -zefram
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 667b
On Tue, 12 Dec 2017 14:32:06 -0800, zefram@fysh.org wrote: Show quoted text
> In perldiag we already have systematic documentation of all the warnings, > listing category and describing in what circumstances they can arise. > Attempting to list the warnings from the other end, in the form of which > warnings can arise from each function and operator, would be crazy, > because internal code factoring means that a lot of warnings can arise > from many places. This ticket should be closed.
We could add a small blurb to "perlfunc" that any warnings produced by keywords are described in "warnings.pm". Otherwise, let's not duplicate documentation, only point to the right ones.
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 423b
Show quoted text
> We could add a small blurb to "perlfunc" that any warnings produced by > keywords are described in "warnings.pm". Otherwise, let's not > duplicate documentation, only point to the right ones.
The patch attached should do this, hopefully using minimal language. $ ./perl t/porting/podcheck.t | grep perlfunc ok 191 - POD of pod/perlfunc.pod The POD looks all right with this change, according to the test. HTH, -marco-
Subject: 0001-mention-perldoc-warnings-in-perlfunc.patch
From ad327d1510783d7fddb102531dad153ea51d2bd4 Mon Sep 17 00:00:00 2001 From: Marco Fontani <MFONTANI@cpan.org> Date: Wed, 13 Dec 2017 11:11:44 +0100 Subject: [PATCH] mention "perldoc warnings" in perlfunc RT # 116080 Rather than duplicating information as to which keyword, function, or operator generates which warning, point the reader to the proper place to read about which warnings Perl generates in which scenario, which are well described in the POD for "warnings". --- pod/perlfunc.pod | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git pod/perlfunc.pod pod/perlfunc.pod index 18a52113be..41a5c8e35b 100644 --- pod/perlfunc.pod +++ pod/perlfunc.pod @@ -104,7 +104,8 @@ X<function> Here are Perl's functions (including things that look like functions, like some keywords and named operators) arranged by category. Some functions appear in more -than one place. +than one place. Any warnings, including those produced by +keywords, are described in C<perldoc warnings>. =over 4 -- 2.15.1
From: Zefram <zefram [...] fysh.org>
Subject: Re: [perl #116080] Doc issues for system, exec, qx
To: perl5-porters [...] perl.org
Date: Thu, 14 Dec 2017 19:58:45 +0000
Download (untitled) / with headers
text/plain 178b
Marco Fontani via RT wrote: Show quoted text
>The patch attached should do this, hopefully using minimal language.
Applied with edit as commit e135ff695231a81e2a70a739e8d813525432fd4d. -zefram
From: Marco Fontani <mfontani [...] cpan.org>
Subject: Re: [perl #116080] Doc issues for system, exec, qx
To: Zefram <zefram [...] fysh.org>
CC: perl5-porters [...] perl.org
Date: Fri, 15 Dec 2017 13:22:19 +0100
Download (untitled) / with headers
text/plain 336b
On Thu, Dec 14, 2017 at 8:58 PM, Zefram <zefram@fysh.org> wrote: Show quoted text
>>The patch attached should do this, hopefully using minimal language.
> Applied with edit as commit e135ff695231a81e2a70a739e8d813525432fd4d.
The edit looks to have added a stray "plus sign" at the start of the line. Attached patch to correct that. -- Marco Fontani

Message body is not shown because sender requested not to inline it.

From: Karl Williamson <public [...] khwilliamson.com>
Subject: Re: [perl #116080] Doc issues for system, exec, qx
Date: Fri, 15 Dec 2017 10:25:36 -0700
To: Marco Fontani <mfontani [...] cpan.org>, Zefram <zefram [...] fysh.org>
CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 451b
On 12/15/2017 05:22 AM, Marco Fontani wrote: Show quoted text
> On Thu, Dec 14, 2017 at 8:58 PM, Zefram <zefram@fysh.org> wrote:
>>> The patch attached should do this, hopefully using minimal language.
>> Applied with edit as commit e135ff695231a81e2a70a739e8d813525432fd4d.
> > The edit looks to have added a stray "plus sign" at the start of the line. > > Attached patch to correct that. >
Sorry, and thanks. Applied as 3cd7355842a93fd631e01d9a1d60806b4cdbf5f0


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