Description:
------------
The documentation of proc_close states that the function "Returns the termination status of the process that was run. In case of an error then -1 is returned."
The documentation of pclose() goes even further and recommends to use pcntl_wexitstatus() in a (unix only) note.

What the functions return can be seen in ext/standard/proc_open.c, proc_open_rsrc_dtor(), with status being the status parameter of waitpid:

                if (WIFEXITED(wstatus))
                        wstatus = WEXITSTATUS(wstatus);
                FG(pclose_ret) = wstatus;

The return code this is either the exitstatus of the process, if it didn't die by a signal, or the status returned by waitpid, but the caller can't tell anymore, because exit(1) and a SIGHUP are both mapped to 1.
This reduces the value of the exit code to a trinary (-1, 0, all other).

I propose to fix this mess by:
1) remove the first two lines above in PHP 7 (do it fast, do it *now*), and
2) document that the return code of the two functions is unusable before that, and
3) document that the return code has to be treated the very same as the status parameter of waitpid (unless an error happened, of course), and
4) remove the note in pclose, and 
5) have someone with windows knowledge look into it, too.

That might be seen as breaking backwards compatibility, but code using the exit status of the two functions is broken anyway.

If the proposed change can or will not be done, then at least please document the current behaviour clearly, as any misunderstanding can cause a very inappropriate error handling.

This problem has been reported already (#53518) in 2010 for PHP 5.3. I report it again because PHP 7 seems to be a very good point to change the behaviour, and because the documentation should be changed.

Test script:
---------------
<?php
$p1 = proc_open ("exit 1", array(), $pipes);
$x1 = proc_close($p1);
print "$x1\n";

$p2 = proc_open ('kill -HUP $$', array(), $pipes);
$x2 = proc_close($p2);
print "$x2\n";
?>