• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2009 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 /**
20  * @addtogroup Logging
21  * @{
22  */
23 
24 /**
25  * \file
26  *
27  * Support routines to send messages to the Android log buffer,
28  * which can later be accessed through the `logcat` utility.
29  *
30  * Each log message must have
31  *   - a priority
32  *   - a log tag
33  *   - some text
34  *
35  * The tag normally corresponds to the component that emits the log message,
36  * and should be reasonably small.
37  *
38  * Log message text may be truncated to less than an implementation-specific
39  * limit (1023 bytes).
40  *
41  * Note that a newline character ("\n") will be appended automatically to your
42  * log message, if not already there. It is not possible to send several
43  * messages and have them appear on a single line in logcat.
44  *
45  * Please use logging in moderation:
46  *
47  *  - Sending log messages eats CPU and slow down your application and the
48  *    system.
49  *
50  *  - The circular log buffer is pretty small, so sending many messages
51  *    will hide other important log messages.
52  *
53  *  - In release builds, only send log messages to account for exceptional
54  *    conditions.
55  */
56 
57 #include <stdarg.h>
58 #include <stddef.h>
59 #include <stdint.h>
60 #include <sys/cdefs.h>
61 
62 #if !defined(__BIONIC__) && !defined(__INTRODUCED_IN)
63 #define __INTRODUCED_IN(x)
64 #endif
65 
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69 
70 /**
71  * Android log priority values, in increasing order of priority.
72  */
73 typedef enum android_LogPriority {
74   /** For internal use only.  */
75   ANDROID_LOG_UNKNOWN = 0,
76   /** The default priority, for internal use only.  */
77   ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */
78   /** Verbose logging. Should typically be disabled for a release apk. */
79   ANDROID_LOG_VERBOSE,
80   /** Debug logging. Should typically be disabled for a release apk. */
81   ANDROID_LOG_DEBUG,
82   /** Informational logging. Should typically be disabled for a release apk. */
83   ANDROID_LOG_INFO,
84   /** Warning logging. For use with recoverable failures. */
85   ANDROID_LOG_WARN,
86   /** Error logging. For use with unrecoverable failures. */
87   ANDROID_LOG_ERROR,
88   /** Fatal logging. For use when aborting. */
89   ANDROID_LOG_FATAL,
90   /** For internal use only.  */
91   ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */
92 } android_LogPriority;
93 
94 /**
95  * Writes the constant string `text` to the log, with priority `prio` and tag
96  * `tag`.
97  */
98 int __android_log_write(int prio, const char* tag, const char* text);
99 
100 /**
101  * Writes a formatted string to the log, with priority `prio` and tag `tag`.
102  * The details of formatting are the same as for
103  * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html).
104  */
105 int __android_log_print(int prio, const char* tag, const char* fmt, ...)
106     __attribute__((__format__(printf, 3, 4)));
107 
108 /**
109  * Equivalent to `__android_log_print`, but taking a `va_list`.
110  * (If `__android_log_print` is like `printf`, this is like `vprintf`.)
111  */
112 int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap)
113     __attribute__((__format__(printf, 3, 0)));
114 
115 /**
116  * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to
117  * stderr, before calling
118  * [abort(3)](http://man7.org/linux/man-pages/man3/abort.3.html).
119  *
120  * If `fmt` is non-null, `cond` is unused. If `fmt` is null, the string
121  * `Assertion failed: %s` is used with `cond` as the string argument.
122  * If both `fmt` and `cond` are null, a default string is provided.
123  *
124  * Most callers should use
125  * [assert(3)](http://man7.org/linux/man-pages/man3/assert.3.html) from
126  * `&lt;assert.h&gt;` instead, or the `__assert` and `__assert2` functions
127  * provided by bionic if more control is needed. They support automatically
128  * including the source filename and line number more conveniently than this
129  * function.
130  */
131 void __android_log_assert(const char* cond, const char* tag, const char* fmt, ...)
132     __attribute__((__noreturn__)) __attribute__((__format__(printf, 3, 4)));
133 
134 /**
135  * Identifies a specific log buffer for __android_log_buf_write()
136  * and __android_log_buf_print().
137  */
138 typedef enum log_id {
139   LOG_ID_MIN = 0,
140 
141   /** The main log buffer. This is the only log buffer available to apps. */
142   LOG_ID_MAIN = 0,
143   /** The radio log buffer. */
144   LOG_ID_RADIO = 1,
145   /** The event log buffer. */
146   LOG_ID_EVENTS = 2,
147   /** The system log buffer. */
148   LOG_ID_SYSTEM = 3,
149   /** The crash log buffer. */
150   LOG_ID_CRASH = 4,
151   /** The statistics log buffer. */
152   LOG_ID_STATS = 5,
153   /** The security log buffer. */
154   LOG_ID_SECURITY = 6,
155   /** The kernel log buffer. */
156   LOG_ID_KERNEL = 7,
157 
158   LOG_ID_MAX,
159 
160   /** Let the logging function choose the best log target. */
161   LOG_ID_DEFAULT = 0x7FFFFFFF
162 } log_id_t;
163 
164 /**
165  * Writes the constant string `text` to the log buffer `id`,
166  * with priority `prio` and tag `tag`.
167  *
168  * Apps should use __android_log_write() instead.
169  */
170 int __android_log_buf_write(int bufID, int prio, const char* tag, const char* text);
171 
172 /**
173  * Writes a formatted string to log buffer `id`,
174  * with priority `prio` and tag `tag`.
175  * The details of formatting are the same as for
176  * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html).
177  *
178  * Apps should use __android_log_print() instead.
179  */
180 int __android_log_buf_print(int bufID, int prio, const char* tag, const char* fmt, ...)
181     __attribute__((__format__(printf, 4, 5)));
182 
183 /**
184  * Logger data struct used for writing log messages to liblog via __android_log_write_logger_data()
185  * and sending log messages to user defined loggers specified in __android_log_set_logger().
186  */
187 struct __android_log_message {
188   /** Must be set to sizeof(__android_log_message) and is used for versioning. */
189   size_t struct_size;
190 
191   /** {@link log_id_t} values. */
192   int32_t buffer_id;
193 
194   /** {@link android_LogPriority} values. */
195   int32_t priority;
196 
197   /** The tag for the log message. */
198   const char* tag;
199 
200   /** Optional file name, may be set to nullptr. */
201   const char* file;
202 
203   /** Optional line number, ignore if file is nullptr. */
204   uint32_t line;
205 
206   /** The log message itself. */
207   const char* message;
208 };
209 
210 /**
211  * Prototype for the 'logger' function that is called for every log message.
212  */
213 typedef void (*__android_logger_function)(const struct __android_log_message* log_message);
214 /**
215  * Prototype for the 'abort' function that is called when liblog will abort due to
216  * __android_log_assert() failures.
217  */
218 typedef void (*__android_aborter_function)(const char* abort_message);
219 
220 /**
221  * Writes the log message specified by log_message.  log_message includes additional file name and
222  * line number information that a logger may use.  log_message is versioned for backwards
223  * compatibility.
224  * This assumes that loggability has already been checked through __android_log_is_loggable().
225  * Higher level logging libraries, such as libbase, first check loggability, then format their
226  * buffers, then pass the message to liblog via this function, and therefore we do not want to
227  * duplicate the loggability check here.
228  *
229  * @param log_message the log message itself, see __android_log_message.
230  *
231  * Available since API level 30.
232  */
233 void __android_log_write_log_message(struct __android_log_message* log_message) __INTRODUCED_IN(30);
234 
235 /**
236  * Sets a user defined logger function.  All log messages sent to liblog will be set to the
237  * function pointer specified by logger for processing.  It is not expected that log messages are
238  * already terminated with a new line.  This function should add new lines if required for line
239  * separation.
240  *
241  * @param logger the new function that will handle log messages.
242  *
243  * Available since API level 30.
244  */
245 void __android_log_set_logger(__android_logger_function logger) __INTRODUCED_IN(30);
246 
247 /**
248  * Writes the log message to logd.  This is an __android_logger_function and can be provided to
249  * __android_log_set_logger().  It is the default logger when running liblog on a device.
250  *
251  * @param log_message the log message to write, see __android_log_message.
252  *
253  * Available since API level 30.
254  */
255 void __android_log_logd_logger(const struct __android_log_message* log_message) __INTRODUCED_IN(30);
256 
257 /**
258  * Writes the log message to stderr.  This is an __android_logger_function and can be provided to
259  * __android_log_set_logger().  It is the default logger when running liblog on host.
260  *
261  * @param log_message the log message to write, see __android_log_message.
262  *
263  * Available since API level 30.
264  */
265 void __android_log_stderr_logger(const struct __android_log_message* log_message)
266     __INTRODUCED_IN(30);
267 
268 /**
269  * Sets a user defined aborter function that is called for __android_log_assert() failures.  This
270  * user defined aborter function is highly recommended to abort and be noreturn, but is not strictly
271  * required to.
272  *
273  * @param aborter the new aborter function, see __android_aborter_function.
274  *
275  * Available since API level 30.
276  */
277 void __android_log_set_aborter(__android_aborter_function aborter) __INTRODUCED_IN(30);
278 
279 /**
280  * Calls the stored aborter function.  This allows for other logging libraries to use the same
281  * aborter function by calling this function in liblog.
282  *
283  * @param abort_message an additional message supplied when aborting, for example this is used to
284  *                      call android_set_abort_message() in __android_log_default_aborter().
285  *
286  * Available since API level 30.
287  */
288 void __android_log_call_aborter(const char* abort_message) __INTRODUCED_IN(30);
289 
290 /**
291  * Sets android_set_abort_message() on device then aborts().  This is the default aborter.
292  *
293  * @param abort_message an additional message supplied when aborting.  This functions calls
294  *                      android_set_abort_message() with its contents.
295  *
296  * Available since API level 30.
297  */
298 void __android_log_default_aborter(const char* abort_message) __attribute__((noreturn))
299 __INTRODUCED_IN(30);
300 
301 /**
302  * Use the per-tag properties "log.tag.<tagname>" along with the minimum priority from
303  * __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will
304  * be printed.  A non-zero result indicates yes, zero indicates false.
305  *
306  * If both a priority for a tag and a minimum priority are set by
307  * __android_log_set_minimum_priority(), then the lowest of the two values are to determine the
308  * minimum priority needed to log.  If only one is set, then that value is used to determine the
309  * minimum priority needed.  If none are set, then default_priority is used.
310  *
311  * @param prio         the priority to test, takes android_LogPriority values.
312  * @param tag          the tag to test.
313  * @param default_prio the default priority to use if no properties or minimum priority are set.
314  * @return an integer where 1 indicates that the message is loggable and 0 indicates that it is not.
315  *
316  * Available since API level 30.
317  */
318 int __android_log_is_loggable(int prio, const char* tag, int default_prio) __INTRODUCED_IN(30);
319 
320 /**
321  * Use the per-tag properties "log.tag.<tagname>" along with the minimum priority from
322  * __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will
323  * be printed.  A non-zero result indicates yes, zero indicates false.
324  *
325  * If both a priority for a tag and a minimum priority are set by
326  * __android_log_set_minimum_priority(), then the lowest of the two values are to determine the
327  * minimum priority needed to log.  If only one is set, then that value is used to determine the
328  * minimum priority needed.  If none are set, then default_priority is used.
329  *
330  * @param prio         the priority to test, takes android_LogPriority values.
331  * @param tag          the tag to test.
332  * @param len          the length of the tag.
333  * @param default_prio the default priority to use if no properties or minimum priority are set.
334  * @return an integer where 1 indicates that the message is loggable and 0 indicates that it is not.
335  *
336  * Available since API level 30.
337  */
338 int __android_log_is_loggable_len(int prio, const char* tag, size_t len, int default_prio)
339     __INTRODUCED_IN(30);
340 
341 /**
342  * Sets the minimum priority that will be logged for this process.
343  *
344  * @param priority the new minimum priority to set, takes android_LogPriority values.
345  * @return the previous set minimum priority as android_LogPriority values, or
346  *         ANDROID_LOG_DEFAULT if none was set.
347  *
348  * Available since API level 30.
349  */
350 int32_t __android_log_set_minimum_priority(int32_t priority) __INTRODUCED_IN(30);
351 
352 /**
353  * Gets the minimum priority that will be logged for this process.  If none has been set by a
354  * previous __android_log_set_minimum_priority() call, this returns ANDROID_LOG_DEFAULT.
355  *
356  * @return the current minimum priority as android_LogPriority values, or
357  *         ANDROID_LOG_DEFAULT if none is set.
358  *
359  * Available since API level 30.
360  */
361 int32_t __android_log_get_minimum_priority(void) __INTRODUCED_IN(30);
362 
363 /**
364  * Sets the default tag if no tag is provided when writing a log message.  Defaults to
365  * getprogname().  This truncates tag to the maximum log message size, though appropriate tags
366  * should be much smaller.
367  *
368  * @param tag the new log tag.
369  *
370  * Available since API level 30.
371  */
372 void __android_log_set_default_tag(const char* tag) __INTRODUCED_IN(30);
373 
374 #ifdef __cplusplus
375 }
376 #endif
377 
378 /** @} */
379