From 102546f99f2efbc21f9e0860c66f2c3ae714352f Mon Sep 17 00:00:00 2001
From: teor <teor@torproject.org>
Date: Tue, 24 Sep 2019 15:03:17 +1000
Subject: [PATCH 1/3] doc: Document the signal-safe log behaviour in the tor
 man page

Part of 31389.
---
 doc/tor.1.txt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 8359623625..6ba23ac62a 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -663,7 +663,16 @@ GENERAL OPTIONS
     debug, info, notice, warn, and err. We advise using "notice" in most cases,
     since anything more verbose may provide sensitive information to an
     attacker who obtains the logs. If only one severity level is given, all
-    messages of that level or higher will be sent to the listed destination.
+    messages of that level or higher will be sent to the listed destination. +
+ +
+    Some low-level logs may be sent from signal handlers, so their destination
+    logs must be signal-safe. These low-level logs include backtraces,
+    logging function errors, and errors in code called by logging functions.
+    Signal-safe logs are always sent to stderr or stdout. They are also sent to
+    a limited number of log files that are configured to log messages at error
+    severity from the bug or general domains. They are never sent as syslogs,
+    android logs, control port log events, or to any API-based log
+    destinations.
 
 [[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__::
     As above, but send log messages to the listed filename. The

From dfea789203a83a05176bd590a04d91c13da44ef6 Mon Sep 17 00:00:00 2001
From: teor <teor@torproject.org>
Date: Tue, 24 Sep 2019 15:04:03 +1000
Subject: [PATCH 2/3] log: Improve the documentation for
 tor_log_update_sigsafe_err_fds()

Part of 31839.
---
 src/lib/log/log.c | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/lib/log/log.c b/src/lib/log/log.c
index be6f459554..a5db085c30 100644
--- a/src/lib/log/log.c
+++ b/src/lib/log/log.c
@@ -687,8 +687,9 @@ tor_log_update_sigsafe_err_fds(void)
   n_fds = 1;
 
   for (lf = logfiles; lf; lf = lf->next) {
-     /* Don't try callback to the control port, or syslogs: We can't
-      * do them from a signal handler. Don't try stdout: we always do stderr.
+     /* Don't try callback to the control port, syslogs, android logs, or any
+      * other non-file descriptor log: We can't call arbitrary functions from a
+      * signal handler.
       */
     if (lf->is_temporary || logfile_is_external(lf)
         || lf->seems_dead || lf->fd < 0)
@@ -720,7 +721,10 @@ tor_log_update_sigsafe_err_fds(void)
 
   if (!found_real_stderr &&
       int_array_contains(log_fds, n_fds, STDOUT_FILENO)) {
-    /* Don't use a virtual stderr when we're also logging to stdout. */
+    /* Don't use a virtual stderr when we're also logging to stdout.
+     * If we reached max_fds logs, we'll now have (max_fds - 1) logs.
+     * That's ok, max_fds is large enough that most tor instances don't exceed
+     * it. */
     raw_assert(n_fds >= 2); /* Don't tor_assert inside log fns */
     --n_fds;
     log_fds[0] = log_fds[n_fds];

From 0c07cd24d43a19c02333eb5a031df80ef00c891a Mon Sep 17 00:00:00 2001
From: teor <teor@torproject.org>
Date: Tue, 24 Sep 2019 15:22:57 +1000
Subject: [PATCH 3/3] changes: file for 31839

---
 changes/ticket31839 | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 changes/ticket31839

diff --git a/changes/ticket31839 b/changes/ticket31839
new file mode 100644
index 0000000000..d7da40f530
--- /dev/null
+++ b/changes/ticket31839
@@ -0,0 +1,3 @@
+  o Documentation:
+    - Document the signal-safe logging behaviour in the tor man page. Also
+      add some comments to the relevant functions. Closes ticket 31839.