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