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

[Mark H Weaver]

Hi Chris,

Chris Marusich <address@hidden> writes:

> I was reading about the "system" and "system*" procedures in the Guile
> manual, and it seems like the actual behavior of Guile seems to
> contradict what the manual says.  I'm using Guile version 2.2.4.
>
> The Guile manual says that these procedures return the exit status as
> returned by waitpid:
>
>  -- Scheme Procedure: system [cmd]
>  -- C Function: scm_system (cmd)
>      Execute CMD using the operating system’s “command processor”.
>      Under Unix this is usually the default shell ‘sh’.  The value
>      returned is CMD’s exit status as returned by ‘waitpid’ [...].
>
>  -- Scheme Procedure: system* arg1 arg2 ...
>  -- C Function: scm_system_star (args)
>      [...]
>
>      This function returns the exit status of the command as provided by
>      ‘waitpid’.  This value can be handled with ‘status:exit-val’ and
>      the related functions.
>
>      [...]
>
> And the documentation for "waitpid" says:
>
>  -- Scheme Procedure: waitpid pid [options]
>  -- C Function: scm_waitpid (pid, options)
>      [...]
>
>      The return value is a pair containing:
>
>        1. The process ID of the child process, or 0 if ‘WNOHANG’ was
>           specified and no process was collected.
>        2. The integer status value.
>
> However, the return value doesn't appear to be a pair:

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.

In other words, the manual is using the phrase "as returned by" in a
broader sense than your interpretation, merely meaning that it's among
the information returned by 'waitpid'.

This is based on the idea that 'waitpid' conceptually has two return
values, one of which is the status value.  If we designed this API
today, we would likely have it return two separate values, but 'waitpid'
predates the (somewhat controversial) addition of multiple return values
to Scheme in 1998, and so it returns the two values as a pair instead.

> In spite of this, the procedures like status:exit-val do seem to work as
> expected:
>
>     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.

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

    Regards,
      Mark