Merge "liblog: convert README to markdown"

2 files changed, 177 insertions, 209 deletions

diff --git a/liblog/README b/liblog/README
deleted file mode 100644
index 5a845be0e..000000000
--- a/liblog/README
+++ /dev/null
@@ -1,209 +0,0 @@
-LIBLOG(3)          Android Internal NDK Programming Manual           LIBLOG(3)
-
-
-
-NAME
-       liblog - Android Internal NDK logger interfaces
-
-SYNOPSIS
-       /*
-        * Please limit to 24 characters for runtime is loggable,
-        * 16 characters for persist is loggable, and logcat pretty
-        * alignment with limit of 7 characters.
-        */
-       #define LOG_TAG "yourtag"
-       #include <log/log.h>
-
-       ALOG(android_priority, tag, format, ...)
-       IF_ALOG(android_priority, tag)
-       LOG_PRI(priority, tag, format, ...)
-       LOG_PRI_VA(priority, tag, format, args)
-       #define LOG_TAG NULL
-       ALOGV(format, ...)
-       SLOGV(format, ...)
-       RLOGV(format, ...)
-       ALOGV_IF(cond, format, ...)
-       SLOGV_IF(cond, format, ...)
-       RLOGV_IF(cond, format, ...)
-       IF_ALOGC()
-       ALOGD(format, ...)
-       SLOGD(format, ...)
-       RLOGD(format, ...)
-       ALOGD_IF(cond, format, ...)
-       SLOGD_IF(cond, format, ...)
-       RLOGD_IF(cond, format, ...)
-       IF_ALOGD()
-       ALOGI(format, ...)
-       SLOGI(format, ...)
-       RLOGI(format, ...)
-       ALOGI_IF(cond, format, ...)
-       SLOGI_IF(cond, format, ...)
-       RLOGI_IF(cond, format, ...)
-       IF_ALOGI()
-       ALOGW(format, ...)
-       SLOGW(format, ...)
-       RLOGW(format, ...)
-       ALOGW_IF(cond, format, ...)
-       SLOGW_IF(cond, format, ...)
-       RLOGW_IF(cond, format, ...)
-       IF_ALOGW()
-       ALOGE(format, ...)
-       SLOGE(format, ...)
-       RLOGE(format, ...)
-       ALOGE_IF(cond, format, ...)
-       SLOGE_IF(cond, format, ...)
-       RLOGE_IF(cond, format, ...)
-       IF_ALOGE()
-       LOG_FATAL(format, ...)
-       LOG_ALWAYS_FATAL(format, ...)
-       LOG_FATAL_IF(cond, format, ...)
-       LOG_ALWAYS_FATAL_IF(cond, format, ...)
-       ALOG_ASSERT(cond, format, ...)
-       LOG_EVENT_INT(tag, value)
-       LOG_EVENT_LONG(tag, value)
-
-       clockid_t android_log_clockid()
-
-       log_id_t android_logger_get_id(struct logger *logger)
-       int android_logger_clear(struct logger *logger)
-       int android_logger_get_log_size(struct logger *logger)
-       int android_logger_get_log_readable_size(struct logger *logger)
-       int android_logger_get_log_version(struct logger *logger)
-
-       struct logger_list *android_logger_list_alloc(int mode,
-                                                     unsigned int tail,
-                                                     pid_t pid)
-       struct logger *android_logger_open(struct logger_list *logger_list,
-                                          log_id_t id)
-       struct logger_list *android_logger_list_open(log_id_t id, int mode,
-                                                    unsigned int tail,
-                                                    pid_t pid)
-       int android_logger_list_read(struct logger_list *logger_list,
-                                    struct log_msg *log_msg)
-       void android_logger_list_free(struct logger_list *logger_list)
-
-       log_id_t android_name_to_log_id(const char *logName)
-       const char *android_log_id_to_name(log_id_t log_id)
-
-       android_log_context create_android_logger(uint32_t tag)
-
-       int android_log_write_list_begin(android_log_context ctx)
-       int android_log_write_list_end(android_log_context ctx)
-
-       int android_log_write_int32(android_log_context ctx, int32_t value)
-       int android_log_write_int64(android_log_context ctx, int64_t value)
-       int android_log_write_string8(android_log_context ctx,
-                                     const char *value)
-       int android_log_write_string8_len(android_log_context ctx,
-                                         const char *value, size_t maxlen)
-       int android_log_write_float32(android_log_context ctx, float value)
-
-       int android_log_write_list(android_log_context ctx,
-                                  log_id_t id = LOG_ID_EVENTS)
-
-       android_log_context create_android_log_parser(const char *msg,
-                                                     size_t len)
-       android_log_list_element android_log_read_next(android_log_context ctx)
-       android_log_list_element android_log_peek_next(android_log_context ctx)
-
-       int android_log_destroy(android_log_context *ctx)
-
-       #include <log/log_transport.h>
-
-       int android_set_log_transport(int transport_flag)
-       int android_get_log_transport()
-
-       Link with -llog
-
-DESCRIPTION
-       liblog  represents  an interface to the volatile Android Logging system
-       for NDK (Native) applications  and  libraries.  Interfaces  for  either
-       writing  or reading logs.  The log buffers are divided up in Main, Sys‐
-       tem, Radio and Events sub-logs.
-
-       The logging interfaces are a series of macros,  all  of  which  can  be
-       overridden individually in order to control the verbosity of the appli‐
-       cation or library.  [ASR]LOG[VDIWE] calls are used  to  log  to  BAsic,
-       System or Radio sub-logs in either the Verbose, Debug, Info, Warning or
-       Error priorities.  [ASR]LOG[VDIWE]_IF calls are used  to  perform  thus
-       based  on a condition being true.  IF_ALOG[VDIWE] calls are true if the
-       current LOG_TAG is enabled at the specified priority.  LOG_ALWAYS_FATAL
-       is  used to ALOG a message, then kill the process.  LOG_FATAL call is a
-       variant of LOG_ALWAYS_FATAL,  only  enabled  in  engineering,  and  not
-       release builds.  ALOG_ASSERT is used to ALOG a message if the condition
-       is  false;   the   condition   is   part   of   the   logged   message.
-       LOG_EVENT_(INT|LONG)  is  used  to  drop binary content into the Events
-       sub-log.
-
-       The log reading interfaces permit opening the  logs  either  singly  or
-       multiply,  retrieving  a  log  entry  at  a  time in time sorted order,
-       optionally limited to a specific pid and tail of the log(s) and finally
-       a  call closing the logs.  A single log can be opened with android_log‐
-       ger_list_open;  or  multiple  logs  can  be  opened  with  android_log‐
-       ger_list_alloc,  calling  in  turn the android_logger_open for each log
-       id.  Each entry can be retrieved  with  android_logger_list_read.   The
-       log(s) can be closed with android_logger_list_free.  The logs should be
-       opened  with an  ANDROID_LOG_RDONLY  mode.   ANDROID_LOG_NONBLOCK  mode
-       will report when the  log reading is done with an  EAGAIN  error return
-       code,  otherwise the  android_logger_list_read  call will block for new
-       entries.
-
-       The  ANDROID_LOG_WRAP  mode flag to the  android_logger_list_alloc_time
-       signals  logd to quiesce  the reader until the buffer is about to prune
-       at the start time then proceed to dumping content.
-
-       The  ANDROID_LOG_PSTORE mode flag to the android_logger_open is used to
-       switch from the active logs to the persistent logs from before the last
-       reboot.
-
-       The value returned by android_logger_open can be used as a parameter to
-       the  android_logger_clear  function to empty the sub-log.  It is recom‐
-       mended to only open log ANDROID_LOG_WRONLY in that case.
-
-       The value returned by android_logger_open can be used as a parameter to
-       the android_logger_get_log_(size|readable_size|version) to retrieve the
-       sub-log maximum size, readable size and log buffer format protocol ver‐
-       sion  respectively.  android_logger_get_id returns the id that was used
-       when  opening  the  sub-log.    It  is  recommended  to  open  the  log
-       ANDROID_LOG_RDONLY in these cases.
-
-       android_set_log_transport()  selects  transport  filters.  Argument  is
-       either LOGGER_DEFAULT, LOGGER_LOGD, LOGGER_NULL or LOGGER_LOCAL. Log to
-       logger daemon for default or logd, drop contents on floor,  or log into
-       local   memory   respectively.       Both   android_set_log_transport()
-       and android_get_log_transport() return the current  transport mask,  or
-       a negative errno for any problems.
-
-ERRORS
-       If messages fail, a negative error code will be returned to the caller.
-
-       The -ENOTCONN return code indicates that the logger daemon is stopped.
-
-       The  -EBADF return code indicates that the log access point can not be
-       opened, or the log buffer id is out of range.
-
-       For the  -EAGAIN  return code,  this means that the logging message was
-       temporarily backed-up either because of Denial Of Service (DOS) logging
-       pressure from some chatty application or service in the Android system,
-       or if too small of a value is set in /proc/sys/net/unix/max_dgram_qlen.
-       To aid in diagnosing the occurence of this,  a binary event from liblog
-       will be sent to the  log  daemon  once a  new  message  can get through
-       indicating how many  messages were  dropped  as a result.   Please take
-       action to resolve the structural problems at the source.
-
-       It is generally not advised for the caller to retry the  -EAGAIN return
-       code as  this  will  only  make the  problem(s)  worse  and  cause your
-       application to temporarily drop to the  logger daemon  priority,  BATCH
-       scheduling policy and background task cgroup. If you require a group of
-       messages to be passed atomically,  merge  them  into  one  message with
-       embedded newlines to the maximum length LOGGER_ENTRY_MAX_PAYLOAD.
-
-       Other return codes  from  writing operation can be returned.  Since the
-       library retries on EINTR, -EINTR should never be returned.
-
-SEE ALSO
-       syslogd(8), klogd, auditd(8)
-
-
-
-                                  08 Feb 2017                        LIBLOG(3)
diff --git a/liblog/README.md b/liblog/README.md
new file mode 100644
index 000000000..886fe2551
--- /dev/null
+++ b/liblog/README.md
@@ -0,0 +1,177 @@
+Android liblog
+--------------
+
+Public Functions and Macros
+---------------------------
+
+    /*
+     * Please limit to 24 characters for runtime is loggable,
+     * 16 characters for persist is loggable, and logcat pretty
+     * alignment with limit of 7 characters.
+    */
+    #define LOG_TAG "yourtag"
+    #include <log/log.h>
+
+    ALOG(android_priority, tag, format, ...)
+    IF_ALOG(android_priority, tag)
+    LOG_PRI(priority, tag, format, ...)
+    LOG_PRI_VA(priority, tag, format, args)
+    #define LOG_TAG NULL
+    ALOGV(format, ...)
+    SLOGV(format, ...)
+    RLOGV(format, ...)
+    ALOGV_IF(cond, format, ...)
+    SLOGV_IF(cond, format, ...)
+    RLOGV_IF(cond, format, ...)
+    IF_ALOGC()
+    ALOGD(format, ...)
+    SLOGD(format, ...)
+    RLOGD(format, ...)
+    ALOGD_IF(cond, format, ...)
+    SLOGD_IF(cond, format, ...)
+    RLOGD_IF(cond, format, ...)
+    IF_ALOGD()
+    ALOGI(format, ...)
+    SLOGI(format, ...)
+    RLOGI(format, ...)
+    ALOGI_IF(cond, format, ...)
+    SLOGI_IF(cond, format, ...)
+    RLOGI_IF(cond, format, ...)
+    IF_ALOGI()
+    ALOGW(format, ...)
+    SLOGW(format, ...)
+    RLOGW(format, ...)
+    ALOGW_IF(cond, format, ...)
+    SLOGW_IF(cond, format, ...)
+    RLOGW_IF(cond, format, ...)
+    IF_ALOGW()
+    ALOGE(format, ...)
+    SLOGE(format, ...)
+    RLOGE(format, ...)
+    ALOGE_IF(cond, format, ...)
+    SLOGE_IF(cond, format, ...)
+    RLOGE_IF(cond, format, ...)
+    IF_ALOGE()
+    LOG_FATAL(format, ...)
+    LOG_ALWAYS_FATAL(format, ...)
+    LOG_FATAL_IF(cond, format, ...)
+    LOG_ALWAYS_FATAL_IF(cond, format, ...)
+    ALOG_ASSERT(cond, format, ...)
+    LOG_EVENT_INT(tag, value)
+    LOG_EVENT_LONG(tag, value)
+
+    clockid_t android_log_clockid()
+
+    log_id_t android_logger_get_id(struct logger *logger)
+    int android_logger_clear(struct logger *logger)
+    int android_logger_get_log_size(struct logger *logger)
+    int android_logger_get_log_readable_size(struct logger *logger)
+    int android_logger_get_log_version(struct logger *logger)
+
+    struct logger_list *android_logger_list_alloc(int mode, unsigned int tail, pid_t pid)
+    struct logger *android_logger_open(struct logger_list *logger_list, log_id_t id)
+    struct logger_list *android_logger_list_open(log_id_t id, int mode, unsigned int tail, pid_t pid)
+    int android_logger_list_read(struct logger_list *logger_list, struct log_msg *log_msg)
+    void android_logger_list_free(struct logger_list *logger_list)
+
+    log_id_t android_name_to_log_id(const char *logName)
+    const char *android_log_id_to_name(log_id_t log_id)
+
+    android_log_context create_android_logger(uint32_t tag)
+
+    int android_log_write_list_begin(android_log_context ctx)
+    int android_log_write_list_end(android_log_context ctx)
+
+    int android_log_write_int32(android_log_context ctx, int32_t value)
+    int android_log_write_int64(android_log_context ctx, int64_t value)
+    int android_log_write_string8(android_log_context ctx, const char *value)
+    int android_log_write_string8_len(android_log_context ctx, const char *value, size_t maxlen)
+    int android_log_write_float32(android_log_context ctx, float value)
+
+    int android_log_write_list(android_log_context ctx, log_id_t id = LOG_ID_EVENTS)
+
+    android_log_context create_android_log_parser(const char *msg, size_t len)
+    android_log_list_element android_log_read_next(android_log_context ctx)
+    android_log_list_element android_log_peek_next(android_log_context ctx)
+
+    int android_log_destroy(android_log_context *ctx)
+
+    #include <log/log_transport.h>
+
+    int android_set_log_transport(int transport_flag)
+    int android_get_log_transport()
+
+Description
+-----------
+
+liblog represents an interface to the volatile Android Logging system for NDK (Native) applications
+and libraries.  Interfaces for either writing or reading logs.  The log buffers are divided up in
+Main, System, Radio and Events sub-logs.
+
+The logging interfaces are a series of macros, all of which can be overridden individually in order
+to control the verbosity of the application or library.  `[ASR]LOG[VDIWE]` calls are used to log to
+BAsic, System or Radio sub-logs in either the Verbose, Debug, Info, Warning or Error priorities.
+`[ASR]LOG[VDIWE]_IF` calls are used to perform thus based on a condition being true.
+`IF_ALOG[VDIWE]` calls are true if the current `LOG_TAG` is enabled at the specified priority.
+`LOG_ALWAYS_FATAL` is used to `ALOG` a message, then kill the process.  `LOG_FATAL` call is a
+variant of `LOG_ALWAYS_FATAL`, only enabled in engineering, and not release builds.  `ALOG_ASSERT`
+is used to `ALOG` a message if the condition is false; the condition is part of the logged message.
+`LOG_EVENT_(INT|LONG)` is used to drop binary content into the Events sub-log.
+
+The log reading interfaces permit opening the logs either singly or multiply, retrieving a log entry
+at a time in time sorted order, optionally limited to a specific pid and tail of the log(s) and
+finally a call closing the logs.  A single log can be opened with `android_logger_list_open()`; or
+multiple logs can be opened with `android_logger_list_alloc()`, calling in turn the
+`android_logger_open()` for each log id.  Each entry can be retrieved with
+`android_logger_list_read()`.  The log(s) can be closed with `android_logger_list_free()`.  The logs
+should be opened with an `ANDROID_LOG_RDONLY` mode.  `ANDROID_LOG_NONBLOCK` mode will report when
+the log reading is done with an `EAGAIN` error return code, otherwise the
+`android_logger_list_read()` call will block for new entries.
+
+The `ANDROID_LOG_WRAP` mode flag to the `android_logger_list_alloc_time()` signals logd to quiesce
+the reader until the buffer is about to prune at the start time then proceed to dumping content.
+
+The `ANDROID_LOG_PSTORE` mode flag to the `android_logger_open()` is used to switch from the active
+logs to the persistent logs from before the last reboot.
+
+The value returned by `android_logger_open()` can be used as a parameter to the
+`android_logger_clear()` function to empty the sub-log.  It is recommended to only open log
+`ANDROID_LOG_WRONLY` in that case.
+
+The value returned by `android_logger_open()` can be used as a parameter to the
+`android_logger_get_log_(size|readable_size|version)` to retrieve the sub-log maximum size, readable
+size and log buffer format protocol version respectively.  `android_logger_get_id()` returns the id
+that was used when opening the sub-log.  It is recommended to open the log `ANDROID_LOG_RDONLY` in
+these cases.
+
+`android_set_log_transport()` selects transport filters.  Argument is either `LOGGER_DEFAULT`,
+`LOGGER_LOGD`, `LOGGER_NULL` or `LOGGER_LOCAL`. Log to logger daemon for default or logd, drop
+contents on floor, or log into local memory respectively.  `Both android_set_log_transport()` and
+`android_get_log_transport()` return the current transport mask, or a negative errno for any
+problems.
+
+Errors
+------
+
+If messages fail, a negative error code will be returned to the caller.
+
+The `-ENOTCONN` return code indicates that the logger daemon is stopped.
+
+The `-EBADF` return code indicates that the log access point can not be opened, or the log buffer id
+is out of range.
+
+For the `-EAGAIN` return code, this means that the logging message was temporarily backed-up either
+because of Denial Of Service (DOS) logging pressure from some chatty application or service in the
+Android system, or if too small of a value is set in /proc/sys/net/unix/max_dgram_qlen.  To aid in
+diagnosing the occurence of this, a binary event from liblog will be sent to the log daemon once a
+new message can get through indicating how many messages were dropped as a result.  Please take
+action to resolve the structural problems at the source.
+
+It is generally not advised for the caller to retry the `-EAGAIN` return code as this will only make
+the problem(s) worse and cause your application to temporarily drop to the logger daemon priority,
+BATCH scheduling policy and background task cgroup. If you require a group of messages to be passed
+atomically, merge them into one message with embedded newlines to the maximum length
+`LOGGER_ENTRY_MAX_PAYLOAD`.
+
+Other return codes from writing operation can be returned.  Since the library retries on `EINTR`,
+`-EINTR` should never be returned.