16.1.7     Other ways to evaluate pcntl_waitpid()'s return value: pcntl_wifexited(), pcntl_wifsignaled(), pcntl_wifstopped(), pcntl_wtermsig(), and pcntl_wstopsig()

This is NOT the latest copy of this book; click here for the latest version.

When a parent discovers through a call to pcntl_waitpid() that one of its children was terminated, the return value is a combination of how the child was terminated and the child's exit code. We have already looked at the function pcntl_wexitstatus(), which extracts the exit code from the return value of pcntl_waitpid(), however there are a selection of other functions that perform similar tasks and each take the same single parameter (the return value of pcntl_waitpid):

• pcntl_wifexited(): returns true if the child process exited normal

• pcntl_wifsignaled(): returns true if the child process exited as a result of it being sent a signal that was not handled

• pcntl_wifstopped(): returns true if the child process is currently stopped.

Only one of the above will be true about a given child process at a time, and each of these has a matching function to determine why the state is how it is. The why function for pcntl_wifexited() is, of course, pcntl_wexitstatus(), and indeed that function has no meaning if used when pcntl_wifsignaled() returns true - a child process that did not exit normally will not send back an error code.

If you want to read the signal type that caused a child process to terminate, you would use the function pcntl_wtermsig(). Again, this only has meaning if pcntl_wifsignaled() returned true.

Finally, to read the signal type that caused a child process to stop, you would use the function pcntl_wstopsig(). This only has meaning if pcntl_wifstopped() returned true. Furthermore, as you can only read the status of stopped processes when WUNTRACED is specified as the third parameter to pcntl_waitpid(), both of these functions are meaningless if you call pcntl_waitpid() with just two parameters.