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 * `<assert.h>` 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