Logging

Summary

Enumerations
`android_LogPriority{ ANDROID_LOG_UNKNOWN = 0, ANDROID_LOG_DEFAULT, ANDROID_LOG_VERBOSE, ANDROID_LOG_DEBUG, ANDROID_LOG_INFO, ANDROID_LOG_WARN, ANDROID_LOG_ERROR, ANDROID_LOG_FATAL, ANDROID_LOG_SILENT }`	enum Android log priority values, in increasing order of priority.
`log_id{ LOG_ID_MIN = 0, LOG_ID_MAIN = 0, LOG_ID_RADIO = 1, LOG_ID_EVENTS = 2, LOG_ID_SYSTEM = 3, LOG_ID_CRASH = 4, LOG_ID_STATS = 5, LOG_ID_SECURITY = 6, LOG_ID_KERNEL = 7, LOG_ID_MAX, LOG_ID_DEFAULT = 0x7FFFFFFF }`	enum Identifies a specific log buffer for __android_log_buf_write() and __android_log_buf_print().

Typedefs
`__android_aborter_function)(const char *abort_message)`	typedef `void(*` Prototype for the 'abort' function that is called when liblog will abort due to __android_log_assert() failures.
`__android_logger_function)(const struct __android_log_message *log_message)`	typedef `void(*` Prototype for the 'logger' function that is called for every log message.
`android_LogPriority`	typedef `enum android_LogPriority` Android log priority values, in increasing order of priority.
`log_id_t`	typedef `enum log_id` Identifies a specific log buffer for __android_log_buf_write() and __android_log_buf_print().

Functions
`__android_log_assert(const char cond, const char tag, const char *fmt, ...)`	`void` Writes an assertion failure to the main log buffer with priority `ANDROID_LOG_FATAL` and also to stderr before calling abort(3).
`__android_log_buf_print(int log_id, int prio, const char tag, const char fmt, ...)`	`int` Writes a formatted string to the log buffer `log_id` (one of the `log_id_t` values), with priority `prio` (one of the `android_LogPriority` values) and tag `tag`.
`__android_log_buf_write(int log_id, int prio, const char tag, const char text)`	`int` Writes the string `text` to the log buffer `log_id` (one of the `log_id_t` values), with priority `prio` (one of the `android_LogPriority` values) and tag `tag`.
`__android_log_call_aborter(const char *abort_message)`	`void` Calls the stored aborter function.
`__android_log_default_aborter(const char *abort_message)`	`void` Sets android_set_abort_message() on device then aborts().
`__android_log_get_minimum_priority(void)`	`int32_t` Gets the minimum priority that will be logged for this process.
`__android_log_id_is_valid(log_id_t log_id)`	`bool`
`__android_log_is_loggable(int prio, const char *tag, int default_prio)`	`int` Use the per-tag properties "log.tag." along with the minimum priority from __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will be printed.
`__android_log_is_loggable_len(int prio, const char *tag, size_t len, int default_prio)`	`int` Use the per-tag properties "log.tag." along with the minimum priority from __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will be printed.
`__android_log_logd_logger(const struct __android_log_message *log_message)`	`void` Writes the log message to logd.
`__android_log_logd_logger_with_timestamp(const struct __android_log_message log_message, const struct timespec timestamp)`	`void` Writes the log message to logd using the passed in timestamp.
`__android_log_print(int prio, const char tag, const char fmt, ...)`	`int` Writes a formatted string to the main log buffer, with priority `prio` (one of the `android_LogPriority` values) and tag `tag`.
`__android_log_set_aborter(__android_aborter_function aborter)`	`void` Sets a user defined aborter function that is called for __android_log_assert() failures.
`__android_log_set_default_tag(const char *tag)`	`void` Sets the default tag if no tag is provided when writing a log message.
`__android_log_set_logger(__android_logger_function logger)`	`void` Sets a user defined logger function.
`__android_log_set_minimum_priority(int32_t priority)`	`int32_t` Sets the minimum priority that will be logged for this process.
`__android_log_stderr_logger(const struct __android_log_message *log_message)`	`void` Writes the log message to stderr.
`__android_log_vprint(int prio, const char tag, const char fmt, va_list ap)`	`int` Equivalent to __android_log_print(), but taking a `va_list`.
`__android_log_write(int prio, const char tag, const char text)`	`int` Writes the constant string `text` to the main log buffer, with priority `prio` (one of the `android_LogPriority` values) and tag `tag`.
`__android_log_write_log_message(struct __android_log_message *log_message)`	`void` Writes the log message specified by log_message.

Structs
__android_log_message	Logger data struct used for writing log messages to liblog via __android_log_write_logger_data() and sending log messages to user defined loggers specified in __android_log_set_logger().

Enumerations

android_LogPriority

Declared in android/log.h

 android_LogPriority

Android log priority values, in increasing order of priority.

Properties
`ANDROID_LOG_DEBUG`	Debug logging. Should typically be disabled for a release apk.
`ANDROID_LOG_DEFAULT`	The default priority, for internal use only.
`ANDROID_LOG_ERROR`	Error logging. For use with unrecoverable failures.
`ANDROID_LOG_FATAL`	Fatal logging. For use when aborting.
`ANDROID_LOG_INFO`	Informational logging. Should typically be disabled for a release apk.
`ANDROID_LOG_SILENT`	For internal use only.
`ANDROID_LOG_UNKNOWN`	For internal use only.
`ANDROID_LOG_VERBOSE`	Verbose logging. Should typically be disabled for a release apk.
`ANDROID_LOG_WARN`	Warning logging. For use with recoverable failures.

log_id

Declared in android/log.h

 log_id

Identifies a specific log buffer for __android_log_buf_write() and __android_log_buf_print().

Properties
`LOG_ID_CRASH`	The crash log buffer.
`LOG_ID_DEFAULT`	Let the logging library choose the best log target in cases where it's unclear. This is useful if you're generic library code that can't know which log your caller should use.
`LOG_ID_EVENTS`	The event log buffer.
`LOG_ID_KERNEL`	The kernel log buffer.
`LOG_ID_MAIN`	The main log buffer. This is the only log buffer available to apps.
`LOG_ID_MAX`	For internal use only.
`LOG_ID_MIN`	For internal use only.
`LOG_ID_RADIO`	The radio log buffer.
`LOG_ID_SECURITY`	The security log buffer.
`LOG_ID_STATS`	The statistics log buffer.
`LOG_ID_SYSTEM`	The system log buffer.

Typedefs

__android_aborter_function

Declared in android/log.h

void(* __android_aborter_function)(const char *abort_message)

Prototype for the 'abort' function that is called when liblog will abort due to __android_log_assert() failures.

__android_logger_function

Declared in android/log.h

void(* __android_logger_function)(const struct __android_log_message *log_message)

Prototype for the 'logger' function that is called for every log message.

android_LogPriority

Declared in android/log.h

enum android_LogPriority android_LogPriority

Android log priority values, in increasing order of priority.

log_id_t

Declared in android/log.h

enum log_id log_id_t

Identifies a specific log buffer for __android_log_buf_write() and __android_log_buf_print().

Functions

__android_log_assert

Declared in android/log.h

void __android_log_assert(
  const char *cond,
  const char *tag,
  const char *fmt,
  ...
)

Writes an assertion failure to the main log buffer with priority ANDROID_LOG_FATAL and also to stderr before calling abort(3).

If fmt is non-null, cond is unused. If fmt is null, the string Assertion failed: s is used with cond as the string argument. If both fmt and cond are null, a default string is provided.

Most callers should use assert(3) from instead, or the __assert and __assert2 functions provided by bionic if more control is needed. They support automatically including the source filename and line number more conveniently than this function.

__android_log_buf_print

Declared in android/log.h

int __android_log_buf_print(
  int log_id,
  int prio,
  const char *tag,
  const char *fmt,
  ...
)

Writes a formatted string to the log buffer log_id (one of the log_id_t values), with priority prio (one of the android_LogPriority values) and tag tag.

The details of formatting are the same as for printf(3).

Apps should use __android_log_print() instead because LOG_ID_MAIN is the only log buffer available to them.

Details
Returns	1 if the message was written to the log, or -EPERM if it was not; see __android_log_is_loggable().

__android_log_buf_write

Declared in android/log.h

int __android_log_buf_write(
  int log_id,
  int prio,
  const char *tag,
  const char *text
)

Writes the string text to the log buffer log_id (one of the log_id_t values), with priority prio (one of the android_LogPriority values) and tag tag.

Apps should use __android_log_write() instead because LOG_ID_MAIN is the only log buffer available to them.

Details
Returns	1 if the message was written to the log, or -EPERM if it was not; see __android_log_is_loggable().

__android_log_call_aborter

Declared in android/log.h

void __android_log_call_aborter(
  const char *abort_message
)

Calls the stored aborter function.

This allows for other logging libraries to use the same aborter function by calling this function in liblog.

Available since API level 30.

Details

Parameters

abort_message

an additional message supplied when aborting, for example this is used to call android_set_abort_message() in __android_log_default_aborter().

__android_log_default_aborter

Declared in android/log.h

void __android_log_default_aborter(
  const char *abort_message
)

Sets android_set_abort_message() on device then aborts().

This is the default aborter.

Available since API level 30.

Details

Parameters

abort_message

an additional message supplied when aborting. This functions calls android_set_abort_message() with its contents.

__android_log_get_minimum_priority

Declared in android/log.h

int32_t __android_log_get_minimum_priority(
  void
)

Gets the minimum priority that will be logged for this process.

Available since API level 30.

Details
Returns	the current minimum priority, or `ANDROID_LOG_DEFAULT` if none is set.

__android_log_id_is_valid

Declared in android/log.h

bool __android_log_id_is_valid(
  log_id_t log_id
)

__android_log_is_loggable

Declared in android/log.h

int __android_log_is_loggable(
  int prio,
  const char *tag,
  int default_prio
)

Use the per-tag properties "log.tag." along with the minimum priority from __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will be printed.

A non-zero result indicates yes, zero indicates false.

If both a priority for a tag and a minimum priority are set by __android_log_set_minimum_priority(), then the lowest of the two values are to determine the minimum priority needed to log. If only one is set, then that value is used to determine the minimum priority needed. If none are set, then default_priority is used.

Available since API level 30.

Details

Parameters

`prio`	the priority to test, takes android_LogPriority values.
`tag`	the tag to test.
`default_prio`	the default priority to use if no properties or minimum priority are set.

Returns

an integer where 1 indicates that the message is loggable and 0 indicates that it is not.

__android_log_is_loggable_len

Declared in android/log.h

int __android_log_is_loggable_len(
  int prio,
  const char *tag,
  size_t len,
  int default_prio
)

Use the per-tag properties "log.tag." along with the minimum priority from __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will be printed.

A non-zero result indicates yes, zero indicates false.

Available since API level 30.

Details

Parameters

`prio`	the priority to test, takes android_LogPriority values.
`tag`	the tag to test.
`len`	the length of the tag.
`default_prio`	the default priority to use if no properties or minimum priority are set.

Returns

an integer where 1 indicates that the message is loggable and 0 indicates that it is not.

__android_log_logd_logger

Declared in android/log.h

void __android_log_logd_logger(
  const struct __android_log_message *log_message
)

Writes the log message to logd.

This is an __android_logger_function and can be provided to __android_log_set_logger(). It is the default logger when running liblog on a device.

Available since API level 30.

Details

Parameters

log_message

the log message to write, see __android_log_message.

__android_log_logd_logger_with_timestamp

Declared in android/log.h

void __android_log_logd_logger_with_timestamp(
  const struct __android_log_message *log_message,
  const struct timespec *timestamp
)

Writes the log message to logd using the passed in timestamp.

The messages are stored in logd in the order received not in order by timestamp. When displaying the log, there is no guarantee that messages are in timestamp order and might cause messages with different times to be interleaved. Filtering the log using a timestamp will work properly even if out of time order messages are present.

Available since API level 37.

Details

Parameters

`log_message`	the log message to write, see __android_log_message.
`timestamp`	the time to use for this log message. The value is interpreted as a CLOCK_REALTIME value.

__android_log_print

Declared in android/log.h

int __android_log_print(
  int prio,
  const char *tag,
  const char *fmt,
  ...
)

Writes a formatted string to the main log buffer, with priority prio (one of the android_LogPriority values) and tag tag.

The details of formatting are the same as for printf(3).

See __android_log_buf_print() to write to a different log buffer.

Details
Returns	1 if the message was written to the log, or -EPERM if it was not; see __android_log_is_loggable().

__android_log_set_aborter

Declared in android/log.h

void __android_log_set_aborter(
  __android_aborter_function aborter
)

Sets a user defined aborter function that is called for __android_log_assert() failures.

This user defined aborter function is highly recommended to abort and be noreturn, but is not strictly required to.

Available since API level 30.

Details

Parameters

aborter

the new aborter function, see __android_aborter_function.

__android_log_set_default_tag

Declared in android/log.h

void __android_log_set_default_tag(
  const char *tag
)

Sets the default tag if no tag is provided when writing a log message.

Defaults to getprogname(). This truncates tag to the maximum log message size, though appropriate tags should be much smaller.

Available since API level 30.

Details

Parameters

tag

the new log tag.

__android_log_set_logger

Declared in android/log.h

void __android_log_set_logger(
  __android_logger_function logger
)

Sets a user defined logger function.

All log messages sent to liblog will be set to the function pointer specified by logger for processing. It is not expected that log messages are already terminated with a new line. This function should add new lines if required for line separation.

Available since API level 30.

Details

Parameters

logger

the new function that will handle log messages.

__android_log_set_minimum_priority

Declared in android/log.h

int32_t __android_log_set_minimum_priority(
  int32_t priority
)

Sets the minimum priority that will be logged for this process.

Available since API level 30.

Details

Parameters

priority

the new minimum priority to set, takes android_LogPriority values.

Returns

the previous set minimum priority, or ANDROID_LOG_DEFAULT if none was set.

__android_log_stderr_logger

Declared in android/log.h

void __android_log_stderr_logger(
  const struct __android_log_message *log_message
)

Writes the log message to stderr.

This is an __android_logger_function and can be provided to __android_log_set_logger(). It is the default logger when running liblog on host.

Available since API level 30.

Details

Parameters

log_message

the log message to write, see __android_log_message.

__android_log_vprint

Declared in android/log.h

int __android_log_vprint(
  int prio,
  const char *tag,
  const char *fmt,
  va_list ap
)

Equivalent to __android_log_print(), but taking a va_list.

(If __android_log_print() is like printf(), this is like vprintf().)

Details
Returns	1 if the message was written to the log, or -EPERM if it was not; see __android_log_is_loggable().

__android_log_write

Declared in android/log.h

int __android_log_write(
  int prio,
  const char *tag,
  const char *text
)

Writes the constant string text to the main log buffer, with priority prio (one of the android_LogPriority values) and tag tag.

See __android_log_buf_write() to write to a different log buffer.

Details
Returns	1 if the message was written to the log, or -EPERM if it was not; see __android_log_is_loggable().

__android_log_write_log_message

Declared in android/log.h

void __android_log_write_log_message(
  struct __android_log_message *log_message
)

Writes the log message specified by log_message.

log_message includes additional file name and line number information that a logger may use. log_message is versioned for backwards compatibility. This assumes that loggability has already been checked through __android_log_is_loggable(). Higher level logging libraries, such as libbase, first check loggability, then format their buffers, then pass the message to liblog via this function, and therefore we do not want to duplicate the loggability check here.

Available since API level 30.

Details

Parameters

log_message

the log message itself, see __android_log_message.

Logging

Summary

Enumerations

Typedefs

Functions

Structs

Enumerations

android_LogPriority

log_id

Typedefs

__android_aborter_function

__android_logger_function

android_LogPriority

log_id_t

Functions

__android_log_assert

__android_log_buf_print

__android_log_buf_write

__android_log_call_aborter

__android_log_default_aborter

__android_log_get_minimum_priority

__android_log_id_is_valid

__android_log_is_loggable

__android_log_is_loggable_len

__android_log_logd_logger

__android_log_logd_logger_with_timestamp

__android_log_print

__android_log_set_aborter

__android_log_set_default_tag

__android_log_set_logger

__android_log_set_minimum_priority

__android_log_stderr_logger

__android_log_vprint

__android_log_write

__android_log_write_log_message