README.md
1Android liblog
2--------------
3
4Public Functions and Macros
5---------------------------
6
7 /*
8 * Please limit to 24 characters for runtime is loggable,
9 * 16 characters for persist is loggable, and logcat pretty
10 * alignment with limit of 7 characters.
11 */
12 #define LOG_TAG "yourtag"
13 #include <log/log.h>
14
15 ALOG(android_priority, tag, format, ...)
16 IF_ALOG(android_priority, tag)
17 LOG_PRI(priority, tag, format, ...)
18 LOG_PRI_VA(priority, tag, format, args)
19 #define LOG_TAG NULL
20 ALOGV(format, ...)
21 SLOGV(format, ...)
22 RLOGV(format, ...)
23 ALOGV_IF(cond, format, ...)
24 SLOGV_IF(cond, format, ...)
25 RLOGV_IF(cond, format, ...)
26 IF_ALOGC()
27 ALOGD(format, ...)
28 SLOGD(format, ...)
29 RLOGD(format, ...)
30 ALOGD_IF(cond, format, ...)
31 SLOGD_IF(cond, format, ...)
32 RLOGD_IF(cond, format, ...)
33 IF_ALOGD()
34 ALOGI(format, ...)
35 SLOGI(format, ...)
36 RLOGI(format, ...)
37 ALOGI_IF(cond, format, ...)
38 SLOGI_IF(cond, format, ...)
39 RLOGI_IF(cond, format, ...)
40 IF_ALOGI()
41 ALOGW(format, ...)
42 SLOGW(format, ...)
43 RLOGW(format, ...)
44 ALOGW_IF(cond, format, ...)
45 SLOGW_IF(cond, format, ...)
46 RLOGW_IF(cond, format, ...)
47 IF_ALOGW()
48 ALOGE(format, ...)
49 SLOGE(format, ...)
50 RLOGE(format, ...)
51 ALOGE_IF(cond, format, ...)
52 SLOGE_IF(cond, format, ...)
53 RLOGE_IF(cond, format, ...)
54 IF_ALOGE()
55 LOG_FATAL(format, ...)
56 LOG_ALWAYS_FATAL(format, ...)
57 LOG_FATAL_IF(cond, format, ...)
58 LOG_ALWAYS_FATAL_IF(cond, format, ...)
59 ALOG_ASSERT(cond, format, ...)
60 LOG_EVENT_INT(tag, value)
61 LOG_EVENT_LONG(tag, value)
62
63 clockid_t android_log_clockid()
64
65 log_id_t android_logger_get_id(struct logger *logger)
66 int android_logger_clear(struct logger *logger)
67 int android_logger_get_log_size(struct logger *logger)
68 int android_logger_get_log_readable_size(struct logger *logger)
69 int android_logger_get_log_version(struct logger *logger)
70
71 struct logger_list *android_logger_list_alloc(int mode, unsigned int tail, pid_t pid)
72 struct logger *android_logger_open(struct logger_list *logger_list, log_id_t id)
73 struct logger_list *android_logger_list_open(log_id_t id, int mode, unsigned int tail, pid_t pid)
74 int android_logger_list_read(struct logger_list *logger_list, struct log_msg *log_msg)
75 void android_logger_list_free(struct logger_list *logger_list)
76
77 log_id_t android_name_to_log_id(const char *logName)
78 const char *android_log_id_to_name(log_id_t log_id)
79
80 android_log_context create_android_logger(uint32_t tag)
81
82 int android_log_write_list_begin(android_log_context ctx)
83 int android_log_write_list_end(android_log_context ctx)
84
85 int android_log_write_int32(android_log_context ctx, int32_t value)
86 int android_log_write_int64(android_log_context ctx, int64_t value)
87 int android_log_write_string8(android_log_context ctx, const char *value)
88 int android_log_write_string8_len(android_log_context ctx, const char *value, size_t maxlen)
89 int android_log_write_float32(android_log_context ctx, float value)
90
91 int android_log_write_list(android_log_context ctx, log_id_t id = LOG_ID_EVENTS)
92
93 android_log_context create_android_log_parser(const char *msg, size_t len)
94 android_log_list_element android_log_read_next(android_log_context ctx)
95 android_log_list_element android_log_peek_next(android_log_context ctx)
96
97 int android_log_destroy(android_log_context *ctx)
98
99 #include <log/log_transport.h>
100
101 int android_set_log_transport(int transport_flag)
102 int android_get_log_transport()
103
104Description
105-----------
106
107liblog represents an interface to the volatile Android Logging system for NDK (Native) applications
108and libraries. Interfaces for either writing or reading logs. The log buffers are divided up in
109Main, System, Radio and Events sub-logs.
110
111The logging interfaces are a series of macros, all of which can be overridden individually in order
112to control the verbosity of the application or library. `[ASR]LOG[VDIWE]` calls are used to log to
113BAsic, System or Radio sub-logs in either the Verbose, Debug, Info, Warning or Error priorities.
114`[ASR]LOG[VDIWE]_IF` calls are used to perform thus based on a condition being true.
115`IF_ALOG[VDIWE]` calls are true if the current `LOG_TAG` is enabled at the specified priority.
116`LOG_ALWAYS_FATAL` is used to `ALOG` a message, then kill the process. `LOG_FATAL` call is a
117variant of `LOG_ALWAYS_FATAL`, only enabled in engineering, and not release builds. `ALOG_ASSERT`
118is used to `ALOG` a message if the condition is false; the condition is part of the logged message.
119`LOG_EVENT_(INT|LONG)` is used to drop binary content into the Events sub-log.
120
121The log reading interfaces permit opening the logs either singly or multiply, retrieving a log entry
122at a time in time sorted order, optionally limited to a specific pid and tail of the log(s) and
123finally a call closing the logs. A single log can be opened with `android_logger_list_open()`; or
124multiple logs can be opened with `android_logger_list_alloc()`, calling in turn the
125`android_logger_open()` for each log id. Each entry can be retrieved with
126`android_logger_list_read()`. The log(s) can be closed with `android_logger_list_free()`. The logs
127should be opened with an `ANDROID_LOG_RDONLY` mode. `ANDROID_LOG_NONBLOCK` mode will report when
128the log reading is done with an `EAGAIN` error return code, otherwise the
129`android_logger_list_read()` call will block for new entries.
130
131The `ANDROID_LOG_WRAP` mode flag to the `android_logger_list_alloc_time()` signals logd to quiesce
132the reader until the buffer is about to prune at the start time then proceed to dumping content.
133
134The `ANDROID_LOG_PSTORE` mode flag to the `android_logger_open()` is used to switch from the active
135logs to the persistent logs from before the last reboot.
136
137The value returned by `android_logger_open()` can be used as a parameter to the
138`android_logger_clear()` function to empty the sub-log. It is recommended to only open log
139`ANDROID_LOG_WRONLY` in that case.
140
141The value returned by `android_logger_open()` can be used as a parameter to the
142`android_logger_get_log_(size|readable_size|version)` to retrieve the sub-log maximum size, readable
143size and log buffer format protocol version respectively. `android_logger_get_id()` returns the id
144that was used when opening the sub-log. It is recommended to open the log `ANDROID_LOG_RDONLY` in
145these cases.
146
147`android_set_log_transport()` selects transport filters. Argument is either `LOGGER_DEFAULT`,
148`LOGGER_LOGD`, or `LOGGER_NULL`. Log to logger daemon for default or logd, or drop contents on floor
149respectively. `Both android_set_log_transport()` and `android_get_log_transport()` return the
150current transport mask, or a negative errno for any problems.
151
152Errors
153------
154
155If messages fail, a negative error code will be returned to the caller.
156
157The `-ENOTCONN` return code indicates that the logger daemon is stopped.
158
159The `-EBADF` return code indicates that the log access point can not be opened, or the log buffer id
160is out of range.
161
162For the `-EAGAIN` return code, this means that the logging message was temporarily backed-up either
163because of Denial Of Service (DOS) logging pressure from some chatty application or service in the
164Android system, or if too small of a value is set in /proc/sys/net/unix/max_dgram_qlen. To aid in
165diagnosing the occurence of this, a binary event from liblog will be sent to the log daemon once a
166new message can get through indicating how many messages were dropped as a result. Please take
167action to resolve the structural problems at the source.
168
169It is generally not advised for the caller to retry the `-EAGAIN` return code as this will only make
170the problem(s) worse and cause your application to temporarily drop to the logger daemon priority,
171BATCH scheduling policy and background task cgroup. If you require a group of messages to be passed
172atomically, merge them into one message with embedded newlines to the maximum length
173`LOGGER_ENTRY_MAX_PAYLOAD`.
174
175Other return codes from writing operation can be returned. Since the library retries on `EINTR`,
176`-EINTR` should never be returned.
177