Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

perldoc for waitpid missing description for argument value -1 #15108

Closed
p5pRT opened this issue Dec 30, 2015 · 8 comments · Fixed by #21821
Closed

perldoc for waitpid missing description for argument value -1 #15108

p5pRT opened this issue Dec 30, 2015 · 8 comments · Fixed by #21821
Assignees

Comments

@p5pRT
Copy link

p5pRT commented Dec 30, 2015

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

Searchable as RT127080$

@p5pRT
Copy link
Author

p5pRT commented Dec 30, 2015

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
Copy link
Author

p5pRT commented Jan 1, 2016

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
Copy link
Author

p5pRT commented Jan 1, 2016

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
Copy link
Author

p5pRT commented Jan 1, 2016

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
Copy link
Author

p5pRT commented Jan 1, 2016

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

@p5pRT
Copy link
Author

p5pRT commented Jan 1, 2016

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
Copy link
Author

p5pRT commented Jan 5, 2016

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
Copy link
Author

p5pRT commented Mar 3, 2016

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

@xenu xenu removed the Severity Low label Dec 29, 2021
tonycoz added a commit to tonycoz/perl5 that referenced this issue Jan 11, 2024
Finally fixes Perl#15108, which was mostly fixed by mauke in a6b6b8e
and 237516c.
@tonycoz tonycoz self-assigned this Jan 11, 2024
tonycoz added a commit to tonycoz/perl5 that referenced this issue Jan 14, 2024
Finally fixes Perl#15108, which was mostly fixed by mauke in a6b6b8e
and 237516c.
tonycoz added a commit that referenced this issue Feb 14, 2024
Finally fixes #15108, which was mostly fixed by mauke in a6b6b8e
and 237516c.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants