Return signal value if session loop is terminated by signal and improve documentation

5 files changed, 46 insertions, 16 deletions

diff --git a/ChangeLog.rst b/ChangeLog.rst
index ed9ca06..c7cee9f 100644
--- a/ChangeLog.rst
+++ b/ChangeLog.rst
@@ -9,11 +9,12 @@ UNRELEASED CHANGES
   `struct fuse_conn_info` fields.
 
 * fuse_loop(), fuse_loop_mt(), fuse_session_loop() and
-  fuse_session_loop_mt() now return -errno instead of -1 in case of
-  failure.
+  fuse_session_loop_mt() now return more detailed error codes instead
+  of just -1. See the documentation of fuse_session_loop() for details.
 
 * The FUSE main loop is now aborted if the file-system requests
-  capabilities that are not supported by the kernel.
+  capabilities that are not supported by the kernel. In this case, the
+  session loop is exited with a return code of ``-EPROTO``.
 
 * Most file-system capabilities that were opt-in in libfuse2 are now
   enabled by default. Filesystem developers are encouraged to review
diff --git a/include/fuse.h b/include/fuse.h
index 56539f1..a9e569e 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -839,8 +839,12 @@ void fuse_destroy(struct fuse *f);
  * Requests from the kernel are processed, and the appropriate
  * operations are called.
  *
+ * For a description of the return value and the conditions when the
+ * event loop exits, refer to the documentation of
+ * fuse_session_loop().
+ *
  * @param f the FUSE handle
- * @return 0 if no error occurred, -errno otherwise
+ * @return see fuse_session_loop()
  *
  * See also: fuse_loop_mt()
  */
@@ -863,8 +867,9 @@ void fuse_exit(struct fuse *f);
  * operations are called.  Request are processed in parallel by
  * distributing them between multiple threads.
  *
- * Calling this function requires the pthreads library to be linked to
- * the application.
+ * For a description of the return value and the conditions when the
+ * event loop exits, refer to the documentation of
+ * fuse_session_loop().
  *
  * Note: using fuse_loop() instead of fuse_loop_mt() means you are running in
  * single-threaded mode, and that you will not have to worry about reentrancy,
@@ -883,7 +888,7 @@ void fuse_exit(struct fuse *f);
  * @param f the FUSE handle
  * @param clone_fd whether to use separate device fds for each thread
  *                 (may increase performance)
- * @return 0 if no error occurred, -errno otherwise
+ * @return see fuse_session_loop()
  *
  * See also: fuse_loop()
  */
diff --git a/include/fuse_common.h b/include/fuse_common.h
index 27d3819..7c2e86f 100644
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -692,8 +692,8 @@ ssize_t fuse_buf_copy(struct fuse_bufvec *dst, struct fuse_bufvec *src,
  * Stores session in a global variable.	 May only be called once per
  * process until fuse_remove_signal_handlers() is called.
  *
- * Once either of the POSIX signals arrives, the fuse_session_exit()
- * is called.
+ * Once either of the POSIX signals arrives, the signal handler calls
+ * fuse_session_exit().
  *
  * @param se the session to exit
  * @return 0 on success, -1 on failure
diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 2cebb30..af3063f 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -1788,22 +1788,38 @@ int fuse_session_mount(struct fuse_session *se, const char *mountpoint);
 /**
  * Enter a single threaded, blocking event loop.
  *
- * Using POSIX signals this event loop can be exited but the session
- * needs to be configued by issuing:
- *   fuse_set_signal_handlers() first.
+ * When the event loop terminates because the connection to the FUSE
+ * kernel module has been closed, this function returns zero. This
+ * happens when the filesystem is unmounted regularly (by the
+ * filesystem owner or root running the umount(8) or fusermount(1)
+ * command), or if connection is explicitly severed by writing ``1``
+ * to the``abort`` file in ``/sys/fs/fuse/connections/NNN``. The only
+ * way to distinguish between these two conditions is to check if the
+ * filesystem is still mounted after the session loop returns.
+ *
+ * When some error occurs during request processing, the function
+ * returns a negated errno(3) value.
+ *
+ * If the loop has been terminated because of a signal handler
+ * installed by fuse_set_signal_handlers(), this function returns the
+ * (positive) signal value that triggered the exit.
  *
  * @param se the session
- * @return 0 on success, -errno on failure
+ * @return 0, -errno, or a signal value
  */
 int fuse_session_loop(struct fuse_session *se);
 
 /**
- * Enter a multi-threaded event loop
+ * Enter a multi-threaded event loop.
+ *
+ * For a description of the return value and the conditions when the
+ * event loop exits, refer to the documentation of
+ * fuse_session_loop().
  *
  * @param se the session
  * @param clone_fd whether to use separate device fds for each thread
  *                 (may increase performance)
- * @return 0 on success, -errno on failure
+ * @return see fuse_session_loop()
  */
 int fuse_session_loop_mt(struct fuse_session *se, int clone_fd);
 
diff --git a/lib/fuse_signals.c b/lib/fuse_signals.c
index 0163783..a1bf1d5 100644
--- a/lib/fuse_signals.c
+++ b/lib/fuse_signals.c
@@ -10,18 +10,26 @@
 
 #include "config.h"
 #include "fuse_lowlevel.h"
+#include "fuse_i.h"
 
 #include <stdio.h>
 #include <string.h>
 #include <signal.h>
+#include <stdlib.h>
 
 static struct fuse_session *fuse_instance;
 
 static void exit_handler(int sig)
 {
 	(void) sig;
-	if (fuse_instance)
+	if (fuse_instance) {
 		fuse_session_exit(fuse_instance);
+		if(sig <= 0) {
+			fprintf(stderr, "assertion error: signal value <= 0\n");
+			abort();
+		}
+		fuse_instance->error = sig;
+	}
 }
 
 static int set_one_signal_handler(int sig, void (*handler)(int), int remove)