1.1 --- a/reference.txt	Sun Jun 11 01:27:52 2017 +0200
     1.2 +++ b/reference.txt	Sun Jun 11 03:50:28 2017 +0200
     1.3 @@ -299,6 +299,15 @@
     1.4  listed below.
     1.5  
     1.6  
     1.7 +### moonbridge_io.catch_sigterm()
     1.8 +
     1.9 +This function installs a signal handler for SIGTERM. Instead of causing
    1.10 +immediate process termination, the behavior of moonbridge_io.poll(...) is
    1.11 +modified.
    1.12 +
    1.13 +See moonbridge_io.poll(...) for further information.
    1.14 +
    1.15 +
    1.16  ### moonbridge_io.exec(command, arg1, arg2, ...)
    1.17  
    1.18  Executes the given command and returns a handle with three sockets named
    1.19 @@ -390,35 +399,34 @@
    1.20  which does evaluate to true, e.g. input_set = {[socketA] = true}. If a set is
    1.21  nil, it is treated as being empty.
    1.22  
    1.23 -Returns false (plus a notice as second return value) in case of timeout. If the
    1.24 -4th parameter is set to true, also returns false (plus a notice) when a SIGTERM
    1.25 -has been received since a corresponding signal handler has been installed with
    1.26 -moonbridge_io.sigterm_setup().
    1.27 +If the 4th parameter (wakeup_on_sigterm) is set to true, then the function
    1.28 +returns immediately if the process received at least one SIGTERM signal after
    1.29 +moonbridge_io.catch_sigterm() has been called for the first time.
    1.30 +
    1.31 +The function returns true when at least one file descriptor or handle is ready
    1.32 +for reading or writing respectively. The function may also return true (for
    1.33 +technical reasons) if signals other than SIGTERM have been received during
    1.34 +waiting.
    1.35  
    1.36 -Returns true when at least one file descriptor or handle is ready for reading
    1.37 -or writing respectively. The function may also return true if signals have been
    1.38 -received during waiting (unless the 4th parameter is set to true and a SIGTERM
    1.39 -was received).
    1.40 +If the 4th parameter (wakeup_on_sigterm) is omitted or set to false, then the
    1.41 +function only returns false as first return value if a timeout happened. In
    1.42 +this case, the second return value will be set to an appropriate message string
    1.43 +such that assert(moonbridge_io.poll(...)) can be used to throw an error.
    1.44 +
    1.45 +If the 4th parameter (wakeup_on_sigterm) is set to true, then three values are
    1.46 +returned if a timeout happened or a SIGTERM has been received: false as first
    1.47 +return value, a message string as second return value (that may, for example,
    1.48 +be used for assert(...)), and a boolean as third return value which indicates
    1.49 +whether the function prematurely returned because of SIGTERM.
    1.50 +
    1.51 +this case a corresponding message will be provided as second return value such
    1.52 +that it is possible to call assert(moonbride_io.poll(...)) to raise an error if
    1.53 +a timeout occurs.
    1.54  
    1.55  Note that the function is not thread-safe when the 4th parameter is set to
    1.56  true.
    1.57  
    1.58  
    1.59 -### moonbridge_io.sigterm_received()
    1.60 -
    1.61 -Returns true if a SIGTERM was received after moonbridge_io.sigterm_setup() has
    1.62 -installed a corresponding signal handler. The function will then always return
    1.63 -true until the process terminates.
    1.64 -
    1.65 -
    1.66 -### moonbridge_io.sigterm_setup()
    1.67 -
    1.68 -This function installs a signal handler for SIGTERM. Use the function
    1.69 -moonbridge_io.sigterm_received() to check whether the signal has been received.
    1.70 -In addition, moonbridge_io.poll(...) will wakeup prematurely if the
    1.71 -4th parameter is set to true.
    1.72 -
    1.73 -
    1.74  ### moonbridge_io.tcpconnect(hostname, port)
    1.75  
    1.76  Tries to open a TCP connection with the given host and TCP port number. Returns