perldoc for waitpid missing description for argument value -1

[p5pRT]

Migrated from rt.perl.org#127080 (status was 'open')

Searchable as RT127080$

[p5pRT]

From bharat.pahalwani@gmail.com

Perl5's documentation for function waitpid (http​://perldoc.perl.org/functions/waitpid.html) lacks proper description​:

  $kid = waitpid(-1, WNOHANG);

It is not described :
  1. what's the use of -1
  2. and return value of waitpid(-1, WNOHANG) for different phases of child process

Refer​: http​://stackoverflow.com/questions/34494242/what-does-1-mean-in-waitpid-1-wnohang

It is described in more detail in c manuals http​://linux.die.net/man/2/waitpid
  1) -1 will cause the parent to wait for any child process.
  2) waitpid()​: on success, returns the process ID of the child whose state has changed; if WNOHANG was specified and one or more child(ren) specified by pid exist, but have not yet changed state, then 0 is returned. On error, -1 is returned.

---

Bharat Pahalwani
(If you are able to feel pain of others then u r religious else you are just
following the useless rules which are of no use )

[p5pRT]

From @mauke

On Tue Dec 29 23​:04​:50 2015, bharat.pahalwani@​gmail.com wrote​:

Perl5's documentation for function waitpid
(http​://perldoc.perl.org/functions/waitpid.html) lacks proper
description​:

$kid = waitpid(-1, WNOHANG);

It is not described :
1. what's the use of -1
2. and return value of waitpid(-1, WNOHANG) for different phases of
child process

Refer​: http​://stackoverflow.com/questions/34494242/what-does-1-mean-
in-waitpid-1-wnohang

It is described in more detail in c manuals
http​://linux.die.net/man/2/waitpid
1) -1 will cause the parent to wait for any child process.
2) waitpid()​: on success, returns the process ID of the child whose
state has changed; if WNOHANG was specified and one or more child(ren)
specified by pid exist, but have not yet changed state, then 0 is
returned. On error, -1 is returned.

Proposed documentation patches attached. Comments?

[p5pRT]

From @mauke

0001-explain-meaning-of-negative-PIDs-in-waitpid-perl-127.patch

From aa47d762b463d299c556709813c136aab41b973b Mon Sep 17 00:00:00 2001
From: Lukas Mai <l.mai@web.de>
Date: Fri, 1 Jan 2016 15:35:58 +0100
Subject: [PATCH 1/2] explain meaning of negative PIDs in waitpid [perl
 #127080]

---
 pod/perlfunc.pod | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 72e62a5..d27806c 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -9052,8 +9052,15 @@ X<waitpid>
 
 Waits for a particular child process to terminate and returns the pid of
 the deceased process, or C<-1> if there is no such child process.  On some
-systems, a value of 0 indicates that there are processes still running.
-The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>.  If you say
+systems, a return value of 0 indicates that there are processes still running.
+The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>.
+
+A PID of C<0> indicates to wait for any child process whose process group ID is
+equal to that of the current process.  A PID of less than C<-1> indicates to
+wait for any child process whose process group ID is equal to -PID.  A PID of
+C<-1> indicates to wait for any child process.
+
+If you say
 
     use POSIX ":sys_wait_h";
     #...
@@ -9061,7 +9068,8 @@ The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>.  If you say
         $kid = waitpid(-1, WNOHANG);
     } while $kid > 0;
 
-then you can do a non-blocking wait for all pending zombie processes.
+then you can do a non-blocking wait for all pending zombie processes (see
+L<POSIX/WAIT>).
 Non-blocking wait is available on machines supporting either the
 waitpid(2) or wait4(2) syscalls.  However, waiting for a particular
 pid with FLAGS of C<0> is implemented everywhere.  (Perl emulates the
-- 
2.6.4

[p5pRT]

From @mauke

0002-clarify-meaning-of-waitpid-returning-0-perl-127080.patch

From 0ef71ba3b249f97aa915942f0937b05aa71a67f1 Mon Sep 17 00:00:00 2001
From: Lukas Mai <l.mai@web.de>
Date: Fri, 1 Jan 2016 15:45:47 +0100
Subject: [PATCH 2/2] clarify meaning of waitpid returning 0 [perl #127080]

---
 pod/perlfunc.pod | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d27806c..1dba05a 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -9051,8 +9051,9 @@ X<waitpid>
 =for Pod::Functions wait for a particular child process to die
 
 Waits for a particular child process to terminate and returns the pid of
-the deceased process, or C<-1> if there is no such child process.  On some
-systems, a return value of 0 indicates that there are processes still running.
+the deceased process, or C<-1> if there is no such child process.  A
+non-blocking wait (with L<WNOHANG|POSIX/WNOHANG> in FLAGS) can return 0 if
+there are child processes matching PID but none have terminated yet.
 The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>.
 
 A PID of C<0> indicates to wait for any child process whose process group ID is
-- 
2.6.4

[p5pRT]

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

[p5pRT]

From preaction@me.com

On Jan 1, 2016, at 8​:50 AM, l.mai@​web.de via RT <perlbug-followup@​perl.org> wrote​:

On Tue Dec 29 23​:04​:50 2015, bharat.pahalwani@​gmail.com wrote​:

Perl5's documentation for function waitpid
(http​://perldoc.perl.org/functions/waitpid.html) lacks proper
description​:

$kid = waitpid(-1, WNOHANG);

It is not described :
1. what's the use of -1
2. and return value of waitpid(-1, WNOHANG) for different phases of
child process

Proposed documentation patches attached. Comments?

Looks good to me.

Would it be also prudent to explain how `waitpid` relates to `wait` and why someone would choose one or the other? Until I started digging through wait(2) (and even after the first read-through of that page), I thought `waitpid -1` and `wait` were equivalent. I can add that in a patch on top of yours once it's ready.

[p5pRT]

From @mauke

On Fri Jan 01 06​:50​:33 2016, mauke- wrote​:

On Tue Dec 29 23​:04​:50 2015, bharat.pahalwani@​gmail.com wrote​:

Perl5's documentation for function waitpid
(http​://perldoc.perl.org/functions/waitpid.html) lacks proper
description​:

$kid = waitpid(-1, WNOHANG);

It is not described :
1. what's the use of -1
2. and return value of waitpid(-1, WNOHANG) for different phases of
child process

Refer​: http​://stackoverflow.com/questions/34494242/what-does-1-mean-
in-waitpid-1-wnohang

It is described in more detail in c manuals
http​://linux.die.net/man/2/waitpid
1) -1 will cause the parent to wait for any child process.
2) waitpid()​: on success, returns the process ID of the child whose
state has changed; if WNOHANG was specified and one or more child(ren)
specified by pid exist, but have not yet changed state, then 0 is
returned. On error, -1 is returned.

Proposed documentation patches attached. Comments?

Now merged as commit a6b6b8e and commit 237516c.

[p5pRT]

From @tonycoz

On Fri Jan 01 13​:50​:25 2016, preaction@​me.com wrote​:

Would it be also prudent to explain how `waitpid` relates to `wait`
and why someone would choose one or the other? Until I started digging
through wait(2) (and even after the first read-through of that page),
I thought `waitpid -1` and `wait` were equivalent. I can add that in a
patch on top of yours once it's ready.

How is waitpid(-1, 0) different from wait() ?

The Linux (Debian) man page for wait, waitpid says​:

wait() and waitpid()
  The wait() system call suspends execution of the calling process until
  one of its children terminates. The call wait(&status) is equivalent
  to​:

  waitpid(-1, &status, 0);

Tony