Doc issues for system, exec, qx

[p5pRT]

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

Searchable as RT116080$

[p5pRT]

From tlhackque@yahoo.com

Created by tlhackque@yahoo.com

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.

Perl Info

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

[p5pRT]

From @jkeenan

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.

[p5pRT]

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

[p5pRT]

From @doy

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

[p5pRT]

From tlhackque@yahoo.com

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​:

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

[p5pRT]

From zefram@fysh.org

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

[p5pRT]

From @xsawyerx

On Tue, 12 Dec 2017 14​:32​:06 -0800, zefram@​fysh.org wrote​:

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.

[p5pRT]

From @mfontani

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-

[p5pRT]

From @mfontani

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

[p5pRT]

From zefram@fysh.org

Marco Fontani via RT wrote​:

The patch attached should do this, hopefully using minimal language.

Applied with edit as commit e135ff6.

-zefram

[p5pRT]

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

[p5pRT]

From @mfontani

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

The edit looks to have added a stray "plus sign" at the start of the line.

Attached patch to correct that.

--
Marco Fontani

[p5pRT]

From @mfontani

0001-perlfunc-remove-stray-plus-from-start-of-line.patch

From 08131fc9b2e119850578529dfe1ea857bb31a083 Mon Sep 17 00:00:00 2001
From: Marco Fontani <MFONTANI@cpan.org>
Date: Fri, 15 Dec 2017 13:17:48 +0100
Subject: [PATCH] perlfunc: remove stray plus from start of line

Looks to be an artifact of applying my original patch, which was amended
as part of e135ff695231a81e2a70a739e8d813525432fd4d, whereby the text
was slightly amended.
---
 pod/perlfunc.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git pod/perlfunc.pod pod/perlfunc.pod
index 78773e944b..3fcd437085 100644
--- pod/perlfunc.pod
+++ pod/perlfunc.pod
@@ -105,7 +105,7 @@ 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.  Any warnings, including those produced by
-+keywords, are described in L<perldiag> and L<warnings>.
+keywords, are described in L<perldiag> and L<warnings>.
 
 =over 4
 
-- 
2.15.1

[p5pRT]

From @khwilliamson

On 12/15/2017 05​:22 AM, Marco Fontani wrote​:

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

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
3cd7355