Bug#703569: libipc-run-perl: full_result is buggy or confusing

[Vincent Lefevre]

Package: libipc-run-perl
Version: 0.92-1
Severity: normal

The IPC::Run(3pm) man page says:

      result
             $h->result;

          Returns the first non-zero result code (ie $? >> 8).  See
          "full_result" to get the $? value for a child process.

          To get the result of a particular child, do:

             $h->result( 0 );  # first child's $? >> 8
             $h->result( 1 );  # second child

So, one has the impression that "full_result" is equivalent to "result"
except that it considers $? instead of $? >> 8. But this is apparently
not the case when one gives an argument:

      full_result
             $h->full_result;

          Returns the first non-zero $?.  See "result" to get the first
          $? >> 8 value for a child process.

          To get the result of a particular child, do:

             $h->full_result( 0 );  # first child's $? >> 8
                                      ^^^^^^^^^^^^^^^^^^^^^
             $h->full_result( 1 );  # second child

I first thought that this was an error in the man page, but this is
really the behavior, as this can be seen on the following script:

------------------------------------------------------------
#!/usr/bin/env perl

use strict;
use IPC::Run qw(start);

my ($out,$err);
my $h = start \@ARGV, \*STDIN, \$out, \$err;

while (1)
  {
    eval { $h->pump };
    last if $@ ne '';
    foreach (split /\n/, $out)
      { printf "OUT: $_\n" }
    foreach (split /\n/, $err)
      { printf "ERR: $_\n" }
    undef $out, $err;
  }

if ($@ !~ /^process ended prematurely/)
  { die $@ }

$h->finish;

my $r = $h->full_result;
my $s = $h->full_result(0);
print "$r $s\n";
------------------------------------------------------------

$ ./ipcrun.pl sh -c 'kill $$'
15 0
$ ./ipcrun.pl sh -c 'exit 2'
512 2

I'm wondering whether this is the wanted behavior.

* If it is, then it seems that one cannot get the $? of the next
children (in scripts where there are such children), i.e. to know
whether they have been terminated by a signal.

In such a case, the man page should be modified to say:

  See "full_result" to get the first non-zero $? value for a child
  process.

and for "full_result", it should say that with an argument,
"full_result" is equivalent to "result" (so that the user isn't
surprised).

* It it isn't, then the behavior and the man page should be fixed.

-- System Information:
Debian Release: 7.0
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 3.8-trunk-amd64 (SMP w/2 CPU cores)
Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages libipc-run-perl depends on:
ii  libio-pty-perl  1:1.08-1+b2
ii  perl            5.14.2-20

libipc-run-perl recommends no packages.

libipc-run-perl suggests no packages.

-- no debconf information