Skip Menu |
Report information
Id: 127080
Status: open
Priority: 0/
Queue: perl5

Owner: Nobody
Requestors: bharat.pahalwani [at] gmail.com
Cc: ajgough <alex [at] rcon.org>
AdminCc:

Operating System: (no value)
PatchStatus: (no value)
Severity: low
Type: unknown
Perl Version: (no value)
Fixed In: (no value)

Attachments
0001-explain-meaning-of-negative-PIDs-in-waitpid-perl-127.patch
0002-clarify-meaning-of-waitpid-returning-0-perl-127080.patch



Subject: perldoc for waitpid missing description for argument value -1
CC: robert [...] perl.org, alex [...] rcon.org
Download (untitled) / with headers
text/plain 916b
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 )
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 916b
On Tue Dec 29 23:04:50 2015, bharat.pahalwani@gmail.com wrote: Show quoted text
> 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?
Subject: 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
Subject: 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
To: perlbug-followup [...] perl.org
From: Douglas Bell <preaction [...] me.com>
CC: perl5-porters [...] perl.org
Date: Fri, 01 Jan 2016 15:49:47 -0600
Subject: Re: [perl #127080] perldoc for waitpid missing description for argument value -1
Download (untitled) / with headers
text/plain 858b
Show quoted text
> 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.
RT-Send-CC: perl5-porters [...] perl.org
On Fri Jan 01 06:50:33 2016, mauke- wrote: Show quoted text
> 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 a6b6b8ec1b4 and commit 237516c9c19.
RT-Send-CC: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 700b
On Fri Jan 01 13:50:25 2016, preaction@me.com wrote: Show quoted text
> 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


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