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 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /** 64 * Android log priority values, in increasing order of priority. 65 */ 66 typedef enum android_LogPriority { 67 /** For internal use only. */ 68 ANDROID_LOG_UNKNOWN = 0, 69 /** The default priority, for internal use only. */ 70 ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */ 71 /** Verbose logging. Should typically be disabled for a release apk. */ 72 ANDROID_LOG_VERBOSE, 73 /** Debug logging. Should typically be disabled for a release apk. */ 74 ANDROID_LOG_DEBUG, 75 /** Informational logging. Should typically be disabled for a release apk. */ 76 ANDROID_LOG_INFO, 77 /** Warning logging. For use with recoverable failures. */ 78 ANDROID_LOG_WARN, 79 /** Error logging. For use with unrecoverable failures. */ 80 ANDROID_LOG_ERROR, 81 /** Fatal logging. For use when aborting. */ 82 ANDROID_LOG_FATAL, 83 /** For internal use only. */ 84 ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */ 85 } android_LogPriority; 86 87 /** 88 * Writes the constant string `text` to the log, with priority `prio` and tag 89 * `tag`. 90 */ 91 int __android_log_write(int prio, const char* tag, const char* text); 92 93 /** 94 * Writes a formatted string to the log, with priority `prio` and tag `tag`. 95 * The details of formatting are the same as for 96 * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html). 97 */ 98 int __android_log_print(int prio, const char* tag, const char* fmt, ...) 99 #if defined(__GNUC__) 100 __attribute__((__format__(printf, 3, 4))) 101 #endif 102 ; 103 104 /** 105 * Equivalent to `__android_log_print`, but taking a `va_list`. 106 * (If `__android_log_print` is like `printf`, this is like `vprintf`.) 107 */ 108 int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap) 109 #if defined(__GNUC__) 110 __attribute__((__format__(printf, 3, 0))) 111 #endif 112 ; 113 114 /** 115 * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to 116 * stderr, before calling 117 * [abort(3)](http://man7.org/linux/man-pages/man3/abort.3.html). 118 * 119 * If `fmt` is non-null, `cond` is unused. If `fmt` is null, the string 120 * `Assertion failed: %s` is used with `cond` as the string argument. 121 * If both `fmt` and `cond` are null, a default string is provided. 122 * 123 * Most callers should use 124 * [assert(3)](http://man7.org/linux/man-pages/man3/assert.3.html) from 125 * `<assert.h>` instead, or the `__assert` and `__assert2` functions provided by 126 * bionic if more control is needed. They support automatically including the 127 * source filename and line number more conveniently than this function. 128 */ 129 void __android_log_assert(const char* cond, const char* tag, const char* fmt, 130 ...) 131 #if defined(__GNUC__) 132 __attribute__((__noreturn__)) 133 __attribute__((__format__(printf, 3, 4))) 134 #endif 135 ; 136 137 #ifndef log_id_t_defined 138 #define log_id_t_defined 139 /** 140 * Identifies a specific log buffer for __android_log_buf_write() 141 * and __android_log_buf_print(). 142 */ 143 typedef enum log_id { 144 LOG_ID_MIN = 0, 145 146 /** The main log buffer. This is the only log buffer available to apps. */ 147 LOG_ID_MAIN = 0, 148 /** The radio log buffer. */ 149 LOG_ID_RADIO = 1, 150 /** The event log buffer. */ 151 LOG_ID_EVENTS = 2, 152 /** The system log buffer. */ 153 LOG_ID_SYSTEM = 3, 154 /** The crash log buffer. */ 155 LOG_ID_CRASH = 4, 156 /** The statistics log buffer. */ 157 LOG_ID_STATS = 5, 158 /** The security log buffer. */ 159 LOG_ID_SECURITY = 6, 160 /** The kernel log buffer. */ 161 LOG_ID_KERNEL = 7, 162 163 LOG_ID_MAX 164 } log_id_t; 165 #endif 166 167 /** 168 * Writes the constant string `text` to the log buffer `id`, 169 * with priority `prio` and tag `tag`. 170 * 171 * Apps should use __android_log_write() instead. 172 */ 173 int __android_log_buf_write(int bufID, int prio, const char* tag, 174 const char* text); 175 176 /** 177 * Writes a formatted string to log buffer `id`, 178 * with priority `prio` and tag `tag`. 179 * The details of formatting are the same as for 180 * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html). 181 * 182 * Apps should use __android_log_print() instead. 183 */ 184 int __android_log_buf_print(int bufID, int prio, const char* tag, 185 const char* fmt, ...) 186 #if defined(__GNUC__) 187 __attribute__((__format__(printf, 4, 5))) 188 #endif 189 ; 190 191 #ifdef __cplusplus 192 } 193 #endif 194 195 /** @} */ 196