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

[Chris Marusich]

Hi,

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:

scheme@(guile-user)> (system "true")
$1 = 0
scheme@(guile-user)> (pair? $1)
$2 = #f
scheme@(guile-user)> (system* "true")
$3 = 0
scheme@(guile-user)> (pair? $3)
$4 = #f
scheme@(guile-user)>

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

Is the documentation incorrect? I checked the Guile source for the
system procedure, and it seemed to me like the documentation is
incorrect, but I'm not 100% sure, since I'm not very familiar with the
Guile source code, so I thought I'd ask here to make sure.

Thank you for your help!

[Mark H Weaver]

Hi Chris,

Post by Chris Marusich
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
-- 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.
[...]
-- Scheme Procedure: waitpid pid [options]
-- C Function: scm_waitpid (pid, options)
[...]
1. The process ID of the child process, or 0 if ‘WNOHANG’ was
specified and no process was collected.
2. The integer status value.

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.

Post by Chris Marusich
In spite of this, the procedures like status:exit-val do seem to work as
$5 = 0
$6 = 0

Right, these procedures are meant to operate on the status value.

Post by Chris Marusich
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

[Chris Marusich]

Hi Mark!

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.

Post by Chris Marusich
$5 = 0
$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.

Post by Chris Marusich
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.

[Chris Vine]

On Sun, 14 Oct 2018 00:59:03 -0700

Post by Chris Marusich
Hi Mark!

Post by Mark H Weaver
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.

Post by Mark H Weaver

Post by Chris Marusich
$5 = 0
$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.

Post by Chris Marusich

Post by Mark H Weaver

Post by Chris Marusich
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.

[Mark H Weaver]

Hi Chris,

Post by Chris Marusich

Post by Mark H Weaver

Post by Chris Marusich
$5 = 0
$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.

Post by Chris Marusich
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.

Post by Chris Marusich

Post by Mark H Weaver

Post by Chris Marusich
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.

[...]

Post by Chris Marusich
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
+functions take an integer as input and can be used to decode the integer
@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

[Chris Marusich]

Hi Mark,

Thank you for the reply!

Post by Mark H Weaver

Post by Chris Marusich
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.

I didn't realize that additional information was encoded in the integer
status value. That explains why I was confused.

Post by Mark H Weaver

Post by Chris Marusich
I'm having trouble thinking of a case where one would use
status:exit-val instead of simply using 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.

This makes sense now.

Post by Mark H Weaver
[...] I wonder if it would be enough to simply change "process status
code" to "integer status value" [...].

I agree. I've attached a new patch that makes the change. It also adds
a cross-reference that I think is helpful. How does it look?

[Mark H Weaver]

Hi Chris,

Post by Chris Marusich

Post by Mark H Weaver
[...] I wonder if it would be enough to simply change "process status
code" to "integer status value" [...].

I agree. I've attached a new patch that makes the change. It also adds
a cross-reference that I think is helpful. How does it look?

Looks good to me. I pushed it to the stable-2.2 branch.

Thanks!
Mark

[Chris Marusich]

Hi Mark,

Post by Mark H Weaver
Looks good to me. I pushed it to the stable-2.2 branch.

Great, thank you very much!