blob: 40a39ad8b3e68caac28020a0d4806aa3246939e4 [file] [log] [blame]
Mark Salyzyncfd5b082016-10-17 14:28:00 -07001LIBLOG(3) Android Internal NDK Programming Manual LIBLOG(3)
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -08002
3
4
5NAME
Mark Salyzyncfd5b082016-10-17 14:28:00 -07006 liblog - Android Internal NDK logger interfaces
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -08007
8SYNOPSIS
Mark Salyzyncfd5b082016-10-17 14:28:00 -07009 /*
10 * Please limit to 24 characters for runtime is loggable,
11 * 16 characters for persist is loggable, and logcat pretty
12 * alignment with limit of 7 characters.
13 */
14 #define LOG_TAG "yourtag"
15 #include <log/log.h>
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -080016
17 ALOG(android_priority, tag, format, ...)
18 IF_ALOG(android_priority, tag)
19 LOG_PRI(priority, tag, format, ...)
20 LOG_PRI_VA(priority, tag, format, args)
21 #define LOG_TAG NULL
22 ALOGV(format, ...)
23 SLOGV(format, ...)
24 RLOGV(format, ...)
25 ALOGV_IF(cond, format, ...)
26 SLOGV_IF(cond, format, ...)
27 RLOGV_IF(cond, format, ...)
28 IF_ALOGC()
29 ALOGD(format, ...)
30 SLOGD(format, ...)
31 RLOGD(format, ...)
32 ALOGD_IF(cond, format, ...)
33 SLOGD_IF(cond, format, ...)
34 RLOGD_IF(cond, format, ...)
35 IF_ALOGD()
36 ALOGI(format, ...)
37 SLOGI(format, ...)
38 RLOGI(format, ...)
39 ALOGI_IF(cond, format, ...)
40 SLOGI_IF(cond, format, ...)
41 RLOGI_IF(cond, format, ...)
42 IF_ALOGI()
43 ALOGW(format, ...)
44 SLOGW(format, ...)
45 RLOGW(format, ...)
46 ALOGW_IF(cond, format, ...)
47 SLOGW_IF(cond, format, ...)
48 RLOGW_IF(cond, format, ...)
49 IF_ALOGW()
50 ALOGE(format, ...)
51 SLOGE(format, ...)
52 RLOGE(format, ...)
53 ALOGE_IF(cond, format, ...)
54 SLOGE_IF(cond, format, ...)
55 RLOGE_IF(cond, format, ...)
56 IF_ALOGE()
57 LOG_FATAL(format, ...)
58 LOG_ALWAYS_FATAL(format, ...)
59 LOG_FATAL_IF(cond, format, ...)
60 LOG_ALWAYS_FATAL_IF(cond, format, ...)
61 ALOG_ASSERT(cond, format, ...)
62 LOG_EVENT_INT(tag, value)
63 LOG_EVENT_LONG(tag, value)
64
Mark Salyzynaeaaf812016-09-30 13:30:33 -070065 clockid_t android_log_clockid()
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -080066
67 log_id_t android_logger_get_id(struct logger *logger)
68 int android_logger_clear(struct logger *logger)
69 int android_logger_get_log_size(struct logger *logger)
70 int android_logger_get_log_readable_size(struct logger *logger)
71 int android_logger_get_log_version(struct logger *logger)
72
Mark Salyzyncfd5b082016-10-17 14:28:00 -070073 struct logger_list *android_logger_list_alloc(int mode,
74 unsigned int tail,
75 pid_t pid)
76 struct logger *android_logger_open(struct logger_list *logger_list,
77 log_id_t id)
78 struct logger_list *android_logger_list_open(log_id_t id, int mode,
79 unsigned int tail,
80 pid_t pid)
81 int android_logger_list_read(struct logger_list *logger_list,
82 struct log_msg *log_msg)
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -080083 void android_logger_list_free(struct logger_list *logger_list)
84
85 log_id_t android_name_to_log_id(const char *logName)
86 const char *android_log_id_to_name(log_id_t log_id)
87
Mark Salyzyncfd5b082016-10-17 14:28:00 -070088 android_log_context create_android_logger(uint32_t tag)
89
90 int android_log_write_list_begin(android_log_context ctx)
91 int android_log_write_list_end(android_log_context ctx)
92
93 int android_log_write_int32(android_log_context ctx, int32_t value)
94 int android_log_write_int64(android_log_context ctx, int64_t value)
95 int android_log_write_string8(android_log_context ctx,
96 const char *value)
97 int android_log_write_string8_len(android_log_context ctx,
98 const char *value, size_t maxlen)
99 int android_log_write_float32(android_log_context ctx, float value)
100
101 int android_log_write_list(android_log_context ctx,
102 log_id_t id = LOG_ID_EVENTS)
103
104 android_log_context create_android_log_parser(const char *msg,
105 size_t len)
106 android_log_list_element android_log_read_next(android_log_context ctx)
107 android_log_list_element android_log_peek_next(android_log_context ctx)
108
109 int android_log_destroy(android_log_context *ctx)
110
Mark Salyzyn850d06e2015-02-04 12:39:57 -0800111 #include <log/log_frontend.h>
112
113 int android_set_log_frontend(int frontend_flag)
114 int android_get_log_frontend()
115
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800116 Link with -llog
117
118DESCRIPTION
119 liblog represents an interface to the volatile Android Logging system
120 for NDK (Native) applications and libraries. Interfaces for either
121 writing or reading logs. The log buffers are divided up in Main, Sys
122 tem, Radio and Events sub-logs.
123
124 The logging interfaces are a series of macros, all of which can be
125 overridden individually in order to control the verbosity of the appli
126 cation or library. [ASR]LOG[VDIWE] calls are used to log to BAsic,
127 System or Radio sub-logs in either the Verbose, Debug, Info, Warning or
128 Error priorities. [ASR]LOG[VDIWE]_IF calls are used to perform thus
129 based on a condition being true. IF_ALOG[VDIWE] calls are true if the
130 current LOG_TAG is enabled at the specified priority. LOG_ALWAYS_FATAL
131 is used to ALOG a message, then kill the process. LOG_FATAL call is a
132 variant of LOG_ALWAYS_FATAL, only enabled in engineering, and not
133 release builds. ALOG_ASSERT is used to ALOG a message if the condition
134 is false; the condition is part of the logged message.
135 LOG_EVENT_(INT|LONG) is used to drop binary content into the Events
136 sub-log.
137
138 The log reading interfaces permit opening the logs either singly or
139 multiply, retrieving a log entry at a time in time sorted order,
140 optionally limited to a specific pid and tail of the log(s) and finally
141 a call closing the logs. A single log can be opened with android_log
142 ger_list_open; or multiple logs can be opened with android_log
143 ger_list_alloc, calling in turn the android_logger_open for each log
144 id. Each entry can be retrieved with android_logger_list_read. The
145 log(s) can be closed with android_logger_list_free. The logs should be
Mark Salyzyn2d3f38a2015-01-26 10:46:44 -0800146 opened with an ANDROID_LOG_RDONLY mode. ANDROID_LOG_NONBLOCK mode
147 will report when the log reading is done with an EAGAIN error return
148 code, otherwise the android_logger_list_read call will block for new
149 entries.
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800150
Mark Salyzynf8e546e2015-11-30 11:36:09 -0800151 The ANDROID_LOG_WRAP mode flag to the android_logger_list_alloc_time
152 signals logd to quiesce the reader until the buffer is about to prune
153 at the start time then proceed to dumping content.
154
Mark Salyzyn6eef4172014-12-15 09:51:39 -0800155 The ANDROID_LOG_PSTORE mode flag to the android_logger_open is used to
156 switch from the active logs to the persistent logs from before the last
157 reboot.
158
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800159 The value returned by android_logger_open can be used as a parameter to
160 the android_logger_clear function to empty the sub-log. It is recom
Mark Salyzyn2d3f38a2015-01-26 10:46:44 -0800161 mended to only open log ANDROID_LOG_WRONLY in that case.
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800162
163 The value returned by android_logger_open can be used as a parameter to
164 the android_logger_get_log_(size|readable_size|version) to retrieve the
165 sub-log maximum size, readable size and log buffer format protocol ver
166 sion respectively. android_logger_get_id returns the id that was used
Mark Salyzyn2d3f38a2015-01-26 10:46:44 -0800167 when opening the sub-log. It is recommended to open the log
168 ANDROID_LOG_RDONLY in these cases.
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800169
Mark Salyzyn850d06e2015-02-04 12:39:57 -0800170 android_set_log_frontend() selects frontend filters. Argument is either
Mark Salyzyn71002882016-03-08 16:18:26 -0800171 LOGGER_DEFAULT, LOGGER_LOGD, LOGGER_NULL or LOGGER_LOCAL. Log to logger
172 daemon for default or logd, drop contents on floor, or log into local
173 memory respectively. Both android_set_log_frontend() and
174 android_get_log_frontend() return the current frontend mask, or a
Mark Salyzyn850d06e2015-02-04 12:39:57 -0800175 negative errno for any problems.
176
Mark Salyzynd45d36e2015-02-12 15:14:26 -0800177ERRORS
178 If messages fail, a negative error code will be returned to the caller.
179
180 The -ENOTCONN return code indicates that the logger daemon is stopped.
181
182 The -EBADF return code indicates that the log access point can not be
183 opened, or the log buffer id is out of range.
184
185 For the -EAGAIN return code, this means that the logging message was
186 temporarily backed-up either because of Denial Of Service (DOS) logging
187 pressure from some chatty application or service in the Android system,
188 or if too small of a value is set in /proc/sys/net/unix/max_dgram_qlen.
189 To aid in diagnosing the occurence of this, a binary event from liblog
190 will be sent to the log daemon once a new message can get through
191 indicating how many messages were dropped as a result. Please take
192 action to resolve the structural problems at the source.
193
194 It is generally not advised for the caller to retry the -EAGAIN return
195 code as this will only make the problem(s) worse and cause your
196 application to temporarily drop to the logger daemon priority, BATCH
197 scheduling policy and background task cgroup. If you require a group of
198 messages to be passed atomically, merge them into one message with
199 embedded newlines to the maximum length LOGGER_ENTRY_MAX_PAYLOAD.
200
201 Other return codes from writing operation can be returned. Since the
202 library retries on EINTR, -EINTR should never be returned.
203
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800204SEE ALSO
Mark Salyzyncfd5b082016-10-17 14:28:00 -0700205 syslogd(8), klogd, auditd(8)
Mark Salyzyn24b5d3c2013-12-17 12:29:37 -0800206
207
208
Mark Salyzyn850d06e2015-02-04 12:39:57 -0800209 08 Feb 2017 LIBLOG(3)