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 #ifndef _ANDROID_LOG_H 18 #define _ANDROID_LOG_H 19 20 /****************************************************************** 21 * 22 * IMPORTANT NOTICE: 23 * 24 * This file is part of Android's set of stable system headers 25 * exposed by the Android NDK (Native Development Kit) since 26 * platform release 1.5 27 * 28 * Third-party source AND binary code relies on the definitions 29 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 30 * 31 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 32 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 33 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 34 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 35 */ 36 37 /** 38 * @addtogroup Logging 39 * @{ 40 */ 41 42 /** 43 * \file 44 * 45 * Support routines to send messages to the Android log buffer, 46 * which can later be accessed through the `logcat` utility. 47 * 48 * Each log message must have 49 * - a priority 50 * - a log tag 51 * - some text 52 * 53 * The tag normally corresponds to the component that emits the log message, 54 * and should be reasonably small. 55 * 56 * Log message text may be truncated to less than an implementation-specific 57 * limit (1023 bytes). 58 * 59 * Note that a newline character ("\n") will be appended automatically to your 60 * log message, if not already there. It is not possible to send several 61 * messages and have them appear on a single line in logcat. 62 * 63 * Please use logging in moderation: 64 * 65 * - Sending log messages eats CPU and slow down your application and the 66 * system. 67 * 68 * - The circular log buffer is pretty small, so sending many messages 69 * will hide other important log messages. 70 * 71 * - In release builds, only send log messages to account for exceptional 72 * conditions. 73 */ 74 75 #include <stdarg.h> 76 77 #ifdef __cplusplus 78 extern "C" { 79 #endif 80 81 /** 82 * Android log priority values, in increasing order of priority. 83 */ 84 typedef enum android_LogPriority { 85 /** For internal use only. */ 86 ANDROID_LOG_UNKNOWN = 0, 87 /** The default priority, for internal use only. */ 88 ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */ 89 /** Verbose logging. Should typically be disabled for a release apk. */ 90 ANDROID_LOG_VERBOSE, 91 /** Debug logging. Should typically be disabled for a release apk. */ 92 ANDROID_LOG_DEBUG, 93 /** Informational logging. Should typically be disabled for a release apk. */ 94 ANDROID_LOG_INFO, 95 /** Warning logging. For use with recoverable failures. */ 96 ANDROID_LOG_WARN, 97 /** Error logging. For use with unrecoverable failures. */ 98 ANDROID_LOG_ERROR, 99 /** Fatal logging. For use when aborting. */ 100 ANDROID_LOG_FATAL, 101 /** For internal use only. */ 102 ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */ 103 } android_LogPriority; 104 105 /** 106 * Writes the constant string `text` to the log, with priority `prio` and tag 107 * `tag`. 108 */ 109 int __android_log_write(int prio, const char* tag, const char* text); 110 111 /** 112 * Writes a formatted string to the log, with priority `prio` and tag `tag`. 113 * The details of formatting are the same as for 114 * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html). 115 */ 116 int __android_log_print(int prio, const char* tag, const char* fmt, ...) 117 #if defined(__GNUC__) 118 __attribute__((__format__(printf, 3, 4))) 119 #endif 120 ; 121 122 /** 123 * Equivalent to `__android_log_print`, but taking a `va_list`. 124 * (If `__android_log_print` is like `printf`, this is like `vprintf`.) 125 */ 126 int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap) 127 #if defined(__GNUC__) 128 __attribute__((__format__(printf, 3, 0))) 129 #endif 130 ; 131 132 /** 133 * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to 134 * stderr, before calling 135 * [abort(3)](http://man7.org/linux/man-pages/man3/abort.3.html). 136 * 137 * If `fmt` is non-null, `cond` is unused. If `fmt` is null, the string 138 * `Assertion failed: %s` is used with `cond` as the string argument. 139 * If both `fmt` and `cond` are null, a default string is provided. 140 * 141 * Most callers should use 142 * [assert(3)](http://man7.org/linux/man-pages/man3/assert.3.html) from 143 * `<assert.h>` instead, or the `__assert` and `__assert2` functions provided by 144 * bionic if more control is needed. They support automatically including the 145 * source filename and line number more conveniently than this function. 146 */ 147 void __android_log_assert(const char* cond, const char* tag, const char* fmt, 148 ...) 149 #if defined(__GNUC__) 150 __attribute__((__noreturn__)) 151 __attribute__((__format__(printf, 3, 4))) 152 #endif 153 ; 154 155 #ifndef log_id_t_defined 156 #define log_id_t_defined 157 typedef enum log_id { 158 LOG_ID_MIN = 0, 159 160 LOG_ID_MAIN = 0, 161 LOG_ID_RADIO = 1, 162 LOG_ID_EVENTS = 2, 163 LOG_ID_SYSTEM = 3, 164 LOG_ID_CRASH = 4, 165 LOG_ID_STATS = 5, 166 LOG_ID_SECURITY = 6, 167 LOG_ID_KERNEL = 7, /* place last, third-parties can not use it */ 168 169 LOG_ID_MAX 170 } log_id_t; 171 #endif 172 173 /* 174 * Send a simple string to the log. 175 */ 176 int __android_log_buf_write(int bufID, int prio, const char* tag, 177 const char* text); 178 int __android_log_buf_print(int bufID, int prio, const char* tag, 179 const char* fmt, ...) 180 #if defined(__GNUC__) 181 __attribute__((__format__(printf, 4, 5))) 182 #endif 183 ; 184 185 #ifdef __cplusplus 186 } 187 #endif 188 189 /** @} */ 190 191 #endif /* _ANDROID_LOG_H */ 192