Merge "liblog: convert README to markdown"

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)

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.