docs: Signals and Timer operations

Add more details to Signals section and Timer operations section.

1 files changed, 45 insertions, 2 deletions

diff --git a/luxio.c b/luxio.c
index 30fd88b..205cc92 100644
--- a/luxio.c
+++ b/luxio.c
@@ -394,6 +394,12 @@ luxio__exit(lua_State *L) /* 3.2.2 */
 }
 
 /*** Signals.  Functions related to sending signals.
+
+All signals are defined
+symbolically: `luxio.SIGKILL`, `luxio.SIGINT` etc,
+for a complete list of signals consult `signal(2)` or `signal(7)`
+man pages.
+
 @section signals
 */
 
@@ -401,7 +407,34 @@ luxio__exit(lua_State *L) /* 3.2.2 */
  *  retval = kill(pid, sig);
  *  retval, errno = kill(pid, sig)
  */
-/*** Send signal to a process.
+/*** Send signal to a process or a group of processes.
+
+This function sends a signal to a process or a group of processes
+based on the value of the `pid` parameter. The signal sent is specified
+by the `signal` parameter.
+
+If `pid` is positive, then `signal` is sent to the process with the ID
+specified by `pid`.
+
+If `pid` equals 0, then `signal` is sent to all processes
+whose process group ID is equal to the process group ID of the caller,
+and for which the caller has permission to send a signal
+(excluding an unspecified set of system processes).
+
+If `pid` equals -1, then `signal` is sent to every process for which the calling
+process has permission to send signals (excluding an unspecified set of
+system processes).
+
+If `pid` is less than -1, then `signal` is sent to every process
+(excluding an unspecified set of system processes) whose process
+group ID is equal to the absolute value of `pid`.
+
+If `signal` is 0 then no signal is sent, but error checking is still performed.
+This may be used to check for the existence of a process ID or process group ID.
+
+Return 0 on success (at least one signal was sent).
+On error -1 is returned and errno will be set.
+
 @tparam number pid signal destination
 @tparam number signal signal to send
 @treturn number return value
@@ -435,7 +468,9 @@ luxio_kill(lua_State *L) /* 3.3.2 */
 @section timer
 */
 
-/*** Set an alarm clock for delivery of a signal.
+/*** Arranges for a SIGALRM signal to be delivered to the calling process in
+`seconds` seconds.
+
 @tparam number seconds How long to wait before signal delivery
 @treturn number return value
 @function alarm
@@ -450,6 +485,14 @@ luxio_alarm(lua_State *L) /* 3.4.1 */
 }
 
 /*** Wait for a signal.
+
+`pause()` causes the caller to suspend execution until either
+a signal is caught or a signal is received which terminates the process.
+
+`pause()` returns only when a signal is caught and the signal catching
+function returns. In which case `pause()` will return -1 and errno will
+be set to EINTR.
+
 @treturn number return value
 @function pause
 */