docs: Process management

Add more details to Process creation and execution
and Process termination sections.

1 files changed, 100 insertions, 12 deletions

diff --git a/luxio.c b/luxio.c
index 4b7b707..30fd88b 100644
--- a/luxio.c
+++ b/luxio.c
@@ -101,7 +101,8 @@ programs.
 @section process
 */
 
-/*** Create a child process.
+/*** Fork a child process. Return 0 in the child and the child's process id
+in the parent.
 
 @treturn number return value
 @treturn errno errno
@@ -150,8 +151,13 @@ luxio__exec(lua_State *L, bool usep)
 	return 2;
 }
 
-/*** Execute a file.
-Calls execv().
+/*** Execute a new program, replacing the current process.
+This function will not return when it succeeds, because
+the calling program is replaced by the new program.
+This function will only return if an error has occurred,
+the return value will be -1 and errno will be set to indicate the error.
+
+This function is implemented with execv().
 
 @tparam string path absolute path to executable
 @tparam string ... parameters to pass to executatable
@@ -165,8 +171,18 @@ luxio_exec(lua_State *L) /* 3.1.2 */
 	return luxio__exec(L, false);
 }
 
-/*** Execute a file, searching PATH.
-Calls execp().
+/*** Execute a new program, replacing the current process.
+This function will not return when it succeeds, because
+the calling program is replaced by the new program.
+This function will only return if an error has occurred,
+the return value will be -1 and errno will be set to indicate the error.
+
+The difference between this function and exec, is that
+this function will search for the name of the executable
+in the colon-separated list of directories specified
+in the PATH environment variable.
+
+This function is implemented with execp()
 
 @tparam string path name of executable
 @tparam string ... parameters to pass to executatable
@@ -189,11 +205,39 @@ Functions to do with the termination of processes.
 
 /*** Wait for a process to change state.
 
-@tparam number pid pid to wait on
+This function obtains status information for one of the caller's
+child processes. `waitpid()` will suspend execution of the calling thread
+until status information becomes available
+(unless `luxio.WNOHANG` is specified). If status information is available
+prior to the call to `waitpid()` then the function shall return immediately.
+
+The pid argument specifies a set of child processes for which the status
+is requested. The `waitpid()` function shall only return the status of
+a child process from the following set:
+
+- If `pid` is -1, status is requested for any child process.
+- If `pid` is greater than 0, it specifies the process of a single
+  process for which status is requested.
+- If `pid` is 0, status is requested for any child process whose process
+  group ID is equal to that of the calling process.
+- If `pid` is less than -1, status is requested for any child process
+  whose process group ID is equal to absolute value of `pid`.
+
+The options argument is constructed from the bitwise OR of zero
+or more of the following flags:
+
+- `luxio.WCONTINUED`: report the status of any child process whose status
+  has not been reported since it continued from a job control stop
+- `luxio.WNOHANG`: return immediately, do not wait for status to become available
+- `luxio.WUNTRACED`: return the status of any child process whose status
+  has not been reported since it was stopped
+
+@tparam number pid process id to wait on
 @tparam number options options for call
 @treturn number return value
 @treturn number|errno status code or errno if error
 @function waitpid
+
 */
 static int
 luxio_waitpid(lua_State *L) /* 3.2.1 */
@@ -221,6 +265,9 @@ luxio_waitpid(lua_State *L) /* 3.2.1 */
 	}
 
 /*** Check status macro for WIFEXITED.
+
+Returns true for status of a child process that terminated normally.
+
 @tparam number status code from `waitpid`()
 @treturn number true or false
 @function WIFEXITED
@@ -231,7 +278,11 @@ WAITPID_STATUS(WIFEXITED)
  *  retval = WEXITSTATUS(status);
  *  retval = WIFEXITED(status)
  */
-/*** Obtain exit status code from child
+/*** Obtain exit status code from child.
+
+If the value of `WIFEXITED(status)` is true, return the exit code
+of the child process.
+
 @tparam number status code from `waitpid`()
 @treturn number exit status code
 @function WEXITSTATUS
@@ -239,6 +290,10 @@ WAITPID_STATUS(WIFEXITED)
 WAITPID_STATUS(WEXITSTATUS)
 
 /*** Check status macro for WIFSIGNALED.
+
+Returns true for status of a child process that was terminated
+by an uncaught signal.
+
 @tparam number status code from `waitpid`()
 @treturn number true or false
 @function WIFSIGNALLED
@@ -246,26 +301,43 @@ WAITPID_STATUS(WEXITSTATUS)
 WAITPID_STATUS(WIFSIGNALED)
 
 /*** Obtain signal used to kill child.
+
+If the value of `WIFSIGNALED(status)` is true, return the number
+of the signal that terminated the child process.
+
 @tparam number status code from `waitpid`()
 @treturn number signal number
 @function WTERMSIG
 */
 WAITPID_STATUS(WTERMSIG)
 
-#ifdef WCOREDUMP
+
 /**% WCOREDUMP
  *  retval = WCOREDUMP(status);
  *  retval = WCOREDUMP(status)
  */
-/*** Check status macro for WCOREDUMP.
+/*** Check for core dump.
+
+  Returns true if the child process produced a core dump.
+  This should only be used if `WIFSIGNALED(status)` returns true.
+
+__WCOREDUMP is not specified in POSIX.1-2001 and is not available
+  on some platforms, e.g. AIX and Solaris.__
+
 @tparam number status code from `waitpid`()
 @treturn number true or false
 @function WCOREDUMP
 */
+#ifdef WCOREDUMP
 WAITPID_STATUS(WCOREDUMP)
 #endif
 
-/*** Check status macro for WIFSTOPPED.
+/*** Check whether process was stopped by delivery of a signal.
+
+Returns true if the child process was stopped by delivery of a signal.
+This can only return true if `waitpid()` was called with the `luxio.WUNTRACED`
+option.
+
 @tparam number status code from `waitpid`()
 @treturn number true or false
 @function WIFSTOPPED
@@ -273,6 +345,10 @@ WAITPID_STATUS(WCOREDUMP)
 WAITPID_STATUS(WIFSTOPPED)
 
 /*** Obtain signal number used to stop child.
+
+If the value of `WIFSTOPPED(status)` is true, return the number of the signal
+that caused the child to stop.
+
 @tparam number status code from `waitpid`()
 @treturn number signal number
 @function WSTOPSIG
@@ -280,8 +356,12 @@ WAITPID_STATUS(WIFSTOPPED)
 WAITPID_STATUS(WSTOPSIG)
 
 #ifdef WIFCONTINUED
-/*** Check status macro for WIFCONTINUED.
-Linux 2.6.10.
+/*** Check status for WIFCONTINUED.
+
+Returns true if child process was resumed by SIGCONT.
+
+_(since Linux 2.6.10)._
+
 @tparam number status code from `waitpid`()
 @treturn number true or false
 @function WIFCONTINUED
@@ -292,6 +372,14 @@ WAITPID_STATUS(WIFCONTINUED)
 #undef WAITPID_STATUS
 
 /*** Terminate calling process.  Does not return.
+
+Terminates calling process "immediately", this differs from `exit(3)`
+in that any functions registered via `atexit(3)` or `on_exit(3)` are
+__not__ called when the process exits.
+
+Any open file descriptors are closed, any children of the process are
+inherited by pid 1 (init), and the process's parent is sent a `SIGCHLD` signal.
+
 @tparam[opt=0] number exit status code.
 @function _exit
 */