Merge branch 'tor-github/pr/1357'

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.

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

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];