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

[Chris Vine]

On Sun, 14 Oct 2018 00:59:03 -0700
Chris Marusich <address@hidden> wrote:
> Hi Mark!
> 
> Mark H Weaver <address@hidden> writes:
> 
> > When the manual says "exit status as returned by ‘waitpid’", it's
> > referring to the "status value" portion of what 'waitpid' returns,
> > i.e. the CDR of 'waitpid's return value.
> 
> Thank you for the clarification!  It makes more sense now.
> 
> >>     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 having
> trouble thinking of a case where one would use status:exit-val instead
> of simply using the integer status value directly.

According to the documentation, status:exit-val returns #f if the
process did not end normally (that is, it did not end by main()
returning or by a call to exit()); otherwise if the process did end
normally it returns the process's exit status (that is, 0 if main()
returned otherwise the value passed to exit()).  It does this by
applying the WIFEXITED and WEXITSTATUS macros to POSIX waitpid()'s
wstatus out parameter (that out parameter being the cdr of guile's
waitpid procedure).  Note that the exit status provided by WEXITSTATUS
(and returned by status:exit-val where it doesn't return #f) is not
necessarily the integer comprising the wstatus out parameter. According
to POSIX it is in fact the lower 8 bits of that value.

So status:exit-val definitely is not an identity function.  The
documentation is correct, though perhaps it needs knowledge of POSIX
waitpid() to fully understand it.  Perhaps it would be better if "The
integer status value" was replaced by "The process status code" so the
same expression is used for it in both contexts, thus also helping
avoid confusion with "the exit status value" returned by
status:exit-val.

As "the process status code" is opaque, you don't really need to know
what is in it at all.  You just need to pass it to one or more of the
three procedures which decode it.

> >> 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.