Document the behaviour of CAP_SYSLOG

Change-Id: I3fe9d45220883b17141203539928059f57847bc1
Signed-off-by: Michal Bloch <m.bloch@samsung.com>

diff --git a/src/shared/fdi_logger.c b/src/shared/fdi_logger.c
index fd358a5..12cc86e 100644 (file)
--- a/src/shared/fdi_logger.c
+++ b/src/shared/fdi_logger.c
@@ -69,6 +69,45 @@ static int logger_getsize(struct fd_info *fdi, uint32_t *val)
  */
 static int logger_get_log_len(int fd)
 {
+       /* WARNING! This value REQUIRES `CAP_SYSLOG` to be correct!
+        *
+        * The driver returns the total amount of logs in the buffer
+        * from this syscall, but poll() and read() will NOT return
+        * all of those unless we have `CAP_SYSLOG` or `euid` matches.
+        *
+        * This means that the code will know there are more logs and
+        * wait for them, but will never receive them, causing what
+        * looks like a hang until more valid logs appear to fill in
+        * the gap. This usually takes a long time and is not what
+        * we want, at any rate.
+        *
+        * A full workaround (given that a kernel fix would be nearly
+        * impossible to properly distribute) would be to perform an
+        * additional read() call after the first one, on following
+        * conditions:
+        *   - CAP_SYSLOG is not present
+        *   - epoll marked our FD ready the previous iteration
+        *   - epoll marked our FD unready the current iteration
+        *   - we are a dumping instance
+        *   - we are using Android Logger backend.
+        * That would solve the issue with the minimal amount of syscalls.
+        * However, it would be a horrible idea to do so because it would
+        * turn our code into an abomination, and terror would consume
+        * those who dwell upon the earth.
+        *
+        * Alternatively, the loop could receive special handling for
+        * dumping Android Logger instances since technically they don't
+        * even need to poll (just read a log after each extraction to
+        * replace the hole). It's not very elegant either but would
+        * also offer a decent performance bonus so if mana permits it
+        * might be worth doing regardless.
+        *
+        * In the meantime, using [lib]dlogutil without CAP_SYSLOG is
+        * unsupported and people should just be told to get the cap if
+        * they want to use it (it took us four years to discover that
+        * this is an actual condition so presumably nowadays the cap is
+        * a dime a dozen and comparatively easy to obtain). */
+
        return logger_ioctl(fd, LOGGER_GET_LOG_LEN);
 }