Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 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 | |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 17 | #pragma once |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 18 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 19 | /** |
Dan Albert | 0802d1a | 2018-04-13 14:49:41 -0700 | [diff] [blame] | 20 | * @addtogroup Logging |
| 21 | * @{ |
| 22 | */ |
| 23 | |
| 24 | /** |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 25 | * \file |
| 26 | * |
| 27 | * Support routines to send messages to the Android log buffer, |
| 28 | * which can later be accessed through the `logcat` utility. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 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 |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 39 | * limit (1023 bytes). |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 40 | * |
| 41 | * Note that a newline character ("\n") will be appended automatically to your |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 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. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 44 | * |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 45 | * Please use logging in moderation: |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 46 | * |
| 47 | * - Sending log messages eats CPU and slow down your application and the |
| 48 | * system. |
| 49 | * |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 50 | * - The circular log buffer is pretty small, so sending many messages |
| 51 | * will hide other important log messages. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 52 | * |
| 53 | * - In release builds, only send log messages to account for exceptional |
| 54 | * conditions. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 55 | */ |
| 56 | |
| 57 | #include <stdarg.h> |
Tom Cherry | c17613c | 2020-01-08 14:47:42 -0800 | [diff] [blame] | 58 | #include <stddef.h> |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 59 | |
| 60 | #ifdef __cplusplus |
| 61 | extern "C" { |
| 62 | #endif |
| 63 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 64 | /** |
| 65 | * Android log priority values, in increasing order of priority. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 66 | */ |
| 67 | typedef enum android_LogPriority { |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 68 | /** For internal use only. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 69 | ANDROID_LOG_UNKNOWN = 0, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 70 | /** The default priority, for internal use only. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 71 | ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */ |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 72 | /** Verbose logging. Should typically be disabled for a release apk. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 73 | ANDROID_LOG_VERBOSE, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 74 | /** Debug logging. Should typically be disabled for a release apk. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 75 | ANDROID_LOG_DEBUG, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 76 | /** Informational logging. Should typically be disabled for a release apk. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 77 | ANDROID_LOG_INFO, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 78 | /** Warning logging. For use with recoverable failures. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 79 | ANDROID_LOG_WARN, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 80 | /** Error logging. For use with unrecoverable failures. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 81 | ANDROID_LOG_ERROR, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 82 | /** Fatal logging. For use when aborting. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 83 | ANDROID_LOG_FATAL, |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 84 | /** For internal use only. */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 85 | ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */ |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 86 | } android_LogPriority; |
| 87 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 88 | /** |
| 89 | * Writes the constant string `text` to the log, with priority `prio` and tag |
| 90 | * `tag`. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 91 | */ |
| 92 | int __android_log_write(int prio, const char* tag, const char* text); |
| 93 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 94 | /** |
| 95 | * Writes a formatted string to the log, with priority `prio` and tag `tag`. |
| 96 | * The details of formatting are the same as for |
| 97 | * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html). |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 98 | */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 99 | int __android_log_print(int prio, const char* tag, const char* fmt, ...) |
Tom Cherry | 7714cc9 | 2019-10-16 17:12:39 -0700 | [diff] [blame] | 100 | __attribute__((__format__(printf, 3, 4))); |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 101 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 102 | /** |
| 103 | * Equivalent to `__android_log_print`, but taking a `va_list`. |
| 104 | * (If `__android_log_print` is like `printf`, this is like `vprintf`.) |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 105 | */ |
Mark Salyzyn | 6e31568 | 2017-03-09 08:09:43 -0800 | [diff] [blame] | 106 | int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap) |
Tom Cherry | 7714cc9 | 2019-10-16 17:12:39 -0700 | [diff] [blame] | 107 | __attribute__((__format__(printf, 3, 0))); |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 108 | |
Elliott Hughes | 188a21c | 2018-01-26 10:57:10 -0800 | [diff] [blame] | 109 | /** |
| 110 | * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to |
| 111 | * stderr, before calling |
| 112 | * [abort(3)](http://man7.org/linux/man-pages/man3/abort.3.html). |
| 113 | * |
| 114 | * If `fmt` is non-null, `cond` is unused. If `fmt` is null, the string |
| 115 | * `Assertion failed: %s` is used with `cond` as the string argument. |
| 116 | * If both `fmt` and `cond` are null, a default string is provided. |
| 117 | * |
| 118 | * Most callers should use |
| 119 | * [assert(3)](http://man7.org/linux/man-pages/man3/assert.3.html) from |
Dan Albert | 333a898 | 2019-05-02 12:25:22 -0700 | [diff] [blame] | 120 | * `<assert.h>` instead, or the `__assert` and `__assert2` functions |
| 121 | * provided by bionic if more control is needed. They support automatically |
| 122 | * including the source filename and line number more conveniently than this |
| 123 | * function. |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 124 | */ |
Tom Cherry | 7714cc9 | 2019-10-16 17:12:39 -0700 | [diff] [blame] | 125 | void __android_log_assert(const char* cond, const char* tag, const char* fmt, ...) |
| 126 | __attribute__((__noreturn__)) __attribute__((__format__(printf, 3, 4))); |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 127 | |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 128 | /** |
| 129 | * Identifies a specific log buffer for __android_log_buf_write() |
| 130 | * and __android_log_buf_print(). |
| 131 | */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 132 | typedef enum log_id { |
| 133 | LOG_ID_MIN = 0, |
| 134 | |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 135 | /** The main log buffer. This is the only log buffer available to apps. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 136 | LOG_ID_MAIN = 0, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 137 | /** The radio log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 138 | LOG_ID_RADIO = 1, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 139 | /** The event log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 140 | LOG_ID_EVENTS = 2, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 141 | /** The system log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 142 | LOG_ID_SYSTEM = 3, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 143 | /** The crash log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 144 | LOG_ID_CRASH = 4, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 145 | /** The statistics log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 146 | LOG_ID_STATS = 5, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 147 | /** The security log buffer. */ |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 148 | LOG_ID_SECURITY = 6, |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 149 | /** The kernel log buffer. */ |
| 150 | LOG_ID_KERNEL = 7, |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 151 | |
| 152 | LOG_ID_MAX |
| 153 | } log_id_t; |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 154 | |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 155 | /** |
Tom Cherry | c17613c | 2020-01-08 14:47:42 -0800 | [diff] [blame] | 156 | * Let the logging function choose the best log target. |
| 157 | * This is not part of the enum since adding either -1 or 0xFFFFFFFF forces the enum to be signed or |
| 158 | * unsigned, which breaks unfortunately common arithmetic against LOG_ID_MIN and LOG_ID_MAX. */ |
| 159 | #define LOG_ID_DEFAULT -1 |
| 160 | |
| 161 | /** |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 162 | * Writes the constant string `text` to the log buffer `id`, |
| 163 | * with priority `prio` and tag `tag`. |
| 164 | * |
| 165 | * Apps should use __android_log_write() instead. |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 166 | */ |
Tom Cherry | 7714cc9 | 2019-10-16 17:12:39 -0700 | [diff] [blame] | 167 | int __android_log_buf_write(int bufID, int prio, const char* tag, const char* text); |
Elliott Hughes | cfec0ad | 2018-11-02 13:17:18 -0700 | [diff] [blame] | 168 | |
| 169 | /** |
| 170 | * Writes a formatted string to log buffer `id`, |
| 171 | * with priority `prio` and tag `tag`. |
| 172 | * The details of formatting are the same as for |
| 173 | * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html). |
| 174 | * |
| 175 | * Apps should use __android_log_print() instead. |
| 176 | */ |
Tom Cherry | 7714cc9 | 2019-10-16 17:12:39 -0700 | [diff] [blame] | 177 | int __android_log_buf_print(int bufID, int prio, const char* tag, const char* fmt, ...) |
| 178 | __attribute__((__format__(printf, 4, 5))); |
Tom Cherry | 00a359e | 2018-02-20 14:45:12 -0800 | [diff] [blame] | 179 | |
Tom Cherry | c17613c | 2020-01-08 14:47:42 -0800 | [diff] [blame] | 180 | /** |
| 181 | * Logger data struct used for writing log messages to liblog via __android_log_write_logger_data() |
| 182 | * and sending log messages to user defined loggers specified in __android_log_set_logger(). |
| 183 | */ |
| 184 | struct __android_logger_data { |
| 185 | size_t struct_size; /* Must be set to sizeof(__android_logger_data) and is used for versioning. */ |
| 186 | int buffer_id; /* log_id_t or -1 to represent 'default'. */ |
| 187 | int priority; /* android_LogPriority values. */ |
| 188 | const char* tag; |
| 189 | const char* file; /* Optional file name, may be set to nullptr. */ |
| 190 | unsigned int line; /* Optional line number, ignore if file is nullptr. */ |
| 191 | }; |
| 192 | |
| 193 | /** |
| 194 | * Writes the log message specified with logger_data and msg to the log. logger_data includes |
| 195 | * additional file name and line number information that a logger may use. logger_data is versioned |
| 196 | * for backwards compatibility. |
Tom Cherry | b9e0d5e | 2020-01-22 08:20:03 -0800 | [diff] [blame^] | 197 | * This assumes that loggability has already been checked through __android_log_is_loggable(). |
| 198 | * Higher level logging libraries, such as libbase, first check loggability, then format their |
| 199 | * buffers, then pass the message to liblog via this function, and therefore we do not want to |
| 200 | * duplicate the loggability check here. |
Tom Cherry | c17613c | 2020-01-08 14:47:42 -0800 | [diff] [blame] | 201 | */ |
| 202 | void __android_log_write_logger_data(struct __android_logger_data* logger_data, const char* msg); |
| 203 | |
| 204 | /** |
| 205 | * Prototype for the 'logger' function that is called for every log message. |
| 206 | */ |
| 207 | typedef void (*__android_logger_function)(const struct __android_logger_data* logger_data, |
| 208 | const char* message); |
| 209 | |
| 210 | /** |
| 211 | * Sets a user defined logger function. All log messages sent to liblog will be set to the |
| 212 | * function pointer specified by logger for processing. |
| 213 | */ |
| 214 | void __android_log_set_logger(__android_logger_function logger); |
| 215 | |
| 216 | /** |
| 217 | * Writes the log message to logd. This is an __android_logger_function and can be provided to |
| 218 | * __android_log_set_logger(). It is the default logger when running liblog on a device. |
| 219 | */ |
| 220 | void __android_log_logd_logger(const struct __android_logger_data* logger_data, const char* msg); |
| 221 | |
| 222 | /** |
| 223 | * Writes the log message to stderr. This is an __android_logger_function and can be provided to |
| 224 | * __android_log_set_logger(). It is the default logger when running liblog on host. |
| 225 | */ |
| 226 | void __android_log_stderr_logger(const struct __android_logger_data* logger_data, |
| 227 | const char* message); |
| 228 | |
| 229 | /** |
| 230 | * Prototype for the 'abort' function that is called when liblog will abort due to |
| 231 | * __android_log_assert() failures. |
| 232 | */ |
| 233 | typedef void (*__android_aborter_function)(const char* abort_message); |
| 234 | |
| 235 | /** |
| 236 | * Sets a user defined aborter function that is called for __android_log_assert() failures. |
| 237 | */ |
| 238 | void __android_log_set_aborter(__android_aborter_function aborter); |
| 239 | |
| 240 | /** |
| 241 | * Calls the stored aborter function. This allows for other logging libraries to use the same |
| 242 | * aborter function by calling this function in liblog. |
| 243 | */ |
| 244 | void __android_log_call_aborter(const char* abort_message); |
| 245 | |
| 246 | /** |
| 247 | * Sets android_set_abort_message() on device then aborts(). This is the default aborter. |
| 248 | */ |
| 249 | void __android_log_default_aborter(const char* abort_message); |
| 250 | |
Tom Cherry | 4004460 | 2020-01-16 15:58:02 -0800 | [diff] [blame] | 251 | /** |
| 252 | * Use the per-tag properties "log.tag.<tagname>" along with the minimum priority from |
| 253 | * __android_log_set_minimum_priority() to determine if a log message with a given prio and tag will |
| 254 | * be printed. A non-zero result indicates yes, zero indicates false. |
| 255 | * |
| 256 | * If both a priority for a tag and a minimum priority are set by |
| 257 | * __android_log_set_minimum_priority(), then the lowest of the two values are to determine the |
| 258 | * minimum priority needed to log. If only one is set, then that value is used to determine the |
| 259 | * minimum priority needed. If none are set, then default_priority is used. |
| 260 | * |
| 261 | * prio is ANDROID_LOG_VERBOSE to ANDROID_LOG_FATAL. |
| 262 | */ |
| 263 | int __android_log_is_loggable(int prio, const char* tag, int default_prio); |
| 264 | int __android_log_is_loggable_len(int prio, const char* tag, size_t len, int default_prio); |
| 265 | |
| 266 | /** |
| 267 | * Sets the minimum priority that will be logged for this process. |
| 268 | * |
| 269 | * This returns the previous set minimum priority, or ANDROID_LOG_DEFAULT if none was set. |
| 270 | */ |
| 271 | int __android_log_set_minimum_priority(int priority); |
| 272 | |
| 273 | /** |
| 274 | * Gets the minimum priority that will be logged for this process. If none has been set by a |
| 275 | * previous __android_log_set_minimum_priority() call, this returns ANDROID_LOG_DEFAULT. |
| 276 | */ |
| 277 | int __android_log_get_minimum_priority(); |
| 278 | |
Mark Salyzyn | fda73eb | 2017-01-09 12:44:13 -0800 | [diff] [blame] | 279 | #ifdef __cplusplus |
| 280 | } |
| 281 | #endif |
| 282 | |
Dan Albert | 0802d1a | 2018-04-13 14:49:41 -0700 | [diff] [blame] | 283 | /** @} */ |