Hi Chris, Chris Marusich <cmmarus...@gmail.com> writes:
> Mark H Weaver <m...@netris.org> writes: > >>> scheme@(guile-user)> (status:exit-val $1) >>> $5 = 0 >>> scheme@(guile-user)> (status:exit-val $3) >>> $6 = 0 >> >> Right, these procedures are meant to operate on the status value. > > I see. Then what's the intended use of status:exit-val? I've read its > documentation and viewed its source a few times, and it seems like this > procedure basically behaves like the identity function. I'm not sure where you got that idea, but it's definitely not the identity function. It uses standard POSIX macros from <sys/wait.h> to interpret the status value and extract information from bit fields within. The details of how the status value is represented are platform specific, but on GNU/Linux, in the case where the program exited normally, the low 7 bits are zeroes and bits 8-15 contain the program's exit value. Other representations are used when the program was terminated or stopped by a signal. See the macro definitions in <sys/wait.h> and <bits/waitstatus.h> for the full details. > I'm having > trouble thinking of a case where one would use status:exit-val instead > of simply using the integer status value directly. There's one case where you can use the integer status value directly: you can check if it's zero, and if it is, that indicates that the program exited normally with zero exit value. If the status value is non-zero, and you want to know more information about what happened, then you must use the status:* procedures. >>> Is the documentation incorrect? >> >> I'm not sure I'd call it "incorrect", but I agree that it's somewhat >> confusing and could use clarification. Would you like to propose a >> patch? > > I'm still a little confused about the intended use of status:exit-val, > but how does the attached patch look to you? It's a small change, but I > think this would have been enough to dispel my confusion. [...] > diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi > index 5cb68a292..e39ea119c 100644 > --- a/doc/ref/posix.texi > +++ b/doc/ref/posix.texi > @@ -1749,8 +1749,8 @@ The integer status value. > @end deffn > > The following three > -functions can be used to decode the process status code returned > -by @code{waitpid}. > +functions take an integer as input and can be used to decode the integer > +status value returned by @code{waitpid}. > > @deffn {Scheme Procedure} status:exit-val status > @deffnx {C Function} scm_status_exit_val (status) It sounds a bit repetitive to me. I wonder if it would be enough to simply change "process status code" to "integer status value", since those are the same three words used in the immediately preceding description of waitpid's return value, and it also clarifies that it's an integer. What do you think? Thanks, Mark