Re: Incorrect documentation for system, system*, and/or waitpid?

[Mark H Weaver]

Hi Chris,

Chris Marusich <address@hidden> writes:

> Mark H Weaver <address@hidden> 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