diff options
authorRichard Ipsum <>2017-05-09 22:14:24 +0100
committerRichard Ipsum <>2017-05-10 22:54:40 +0100
commitf0c02f7a872103a5c28287922ab06db2a8d6ef68 (patch)
parentc1ae7a18bd9cb0b174de38f0ae0a46fe8f5c05fc (diff)
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