summaryrefslogtreecommitdiffstats
path: root/liblog
diff options
context:
space:
mode:
authorElliott Hughes2018-01-26 12:57:10 -0600
committerElliott Hughes2018-01-26 12:57:57 -0600
commit65725ac4646f8c243215f87df0abb8c96caea0ae (patch)
tree084bc07bed6599b877df2969e78e0e679079d141 /liblog
parenta0e50d0b56f6f831f81344f3a36e5733092c16d0 (diff)
downloadplatform-system-core-65725ac4646f8c243215f87df0abb8c96caea0ae.tar.gz
platform-system-core-65725ac4646f8c243215f87df0abb8c96caea0ae.tar.xz
platform-system-core-65725ac4646f8c243215f87df0abb8c96caea0ae.zip
Doxygen format <android/log.h>.
Bug: N/A Test: ran doxygen manually. Change-Id: I164de255dbbc6c0312e656ddd886dcac231c893a
Diffstat (limited to 'liblog')
-rw-r--r--liblog/include/android/log.h65
1 files changed, 44 insertions, 21 deletions
diff --git a/liblog/include/android/log.h b/liblog/include/android/log.h
index 15fba8b72..ade282187 100644
--- a/liblog/include/android/log.h
+++ b/liblog/include/android/log.h
@@ -34,9 +34,11 @@
34 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 34 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
35 */ 35 */
36 36
37/* 37/**
38 * Support routines to send messages to the Android in-kernel log buffer, 38 * \file
39 * which can later be accessed through the 'logcat' utility. 39 *
40 * Support routines to send messages to the Android log buffer,
41 * which can later be accessed through the `logcat` utility.
40 * 42 *
41 * Each log message must have 43 * Each log message must have
42 * - a priority 44 * - a priority
@@ -47,24 +49,22 @@
47 * and should be reasonably small. 49 * and should be reasonably small.
48 * 50 *
49 * Log message text may be truncated to less than an implementation-specific 51 * Log message text may be truncated to less than an implementation-specific
50 * limit (e.g. 1023 characters max). 52 * limit (1023 bytes).
51 * 53 *
52 * Note that a newline character ("\n") will be appended automatically to your 54 * Note that a newline character ("\n") will be appended automatically to your
53 * log message, if not already there. It is not possible to send several 55 * log message, if not already there. It is not possible to send several
54 * messages and have them appear on a single line in logcat. 56 * messages and have them appear on a single line in logcat.
55 * 57 *
56 * PLEASE USE LOGS WITH MODERATION: 58 * Please use logging in moderation:
57 * 59 *
58 * - Sending log messages eats CPU and slow down your application and the 60 * - Sending log messages eats CPU and slow down your application and the
59 * system. 61 * system.
60 * 62 *
61 * - The circular log buffer is pretty small (<64KB), sending many messages 63 * - The circular log buffer is pretty small, so sending many messages
62 * might push off other important log messages from the rest of the system. 64 * will hide other important log messages.
63 * 65 *
64 * - In release builds, only send log messages to account for exceptional 66 * - In release builds, only send log messages to account for exceptional
65 * conditions. 67 * conditions.
66 *
67 * NOTE: These functions MUST be implemented by /system/lib/liblog.so
68 */ 68 */
69 69
70#include <stdarg.h> 70#include <stdarg.h>
@@ -73,28 +73,40 @@
73extern "C" { 73extern "C" {
74#endif 74#endif
75 75
76/* 76/**
77 * Android log priority values, in ascending priority order. 77 * Android log priority values, in increasing order of priority.
78 */ 78 */
79typedef enum android_LogPriority { 79typedef enum android_LogPriority {
80 /** For internal use only. */
80 ANDROID_LOG_UNKNOWN = 0, 81 ANDROID_LOG_UNKNOWN = 0,
82 /** The default priority, for internal use only. */
81 ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */ 83 ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */
84 /** Verbose logging. Should typically be disabled for a release apk. */
82 ANDROID_LOG_VERBOSE, 85 ANDROID_LOG_VERBOSE,
86 /** Debug logging. Should typically be disabled for a release apk. */
83 ANDROID_LOG_DEBUG, 87 ANDROID_LOG_DEBUG,
88 /** Informational logging. Should typically be disabled for a release apk. */
84 ANDROID_LOG_INFO, 89 ANDROID_LOG_INFO,
90 /** Warning logging. For use with recoverable failures. */
85 ANDROID_LOG_WARN, 91 ANDROID_LOG_WARN,
92 /** Error logging. For use with unrecoverable failures. */
86 ANDROID_LOG_ERROR, 93 ANDROID_LOG_ERROR,
94 /** Fatal logging. For use when aborting. */
87 ANDROID_LOG_FATAL, 95 ANDROID_LOG_FATAL,
96 /** For internal use only. */
88 ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */ 97 ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */
89} android_LogPriority; 98} android_LogPriority;
90 99
91/* 100/**
92 * Send a simple string to the log. 101 * Writes the constant string `text` to the log, with priority `prio` and tag
102 * `tag`.
93 */ 103 */
94int __android_log_write(int prio, const char* tag, const char* text); 104int __android_log_write(int prio, const char* tag, const char* text);
95 105
96/* 106/**
97 * Send a formatted string to the log, used like printf(fmt,...) 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).
98 */ 110 */
99int __android_log_print(int prio, const char* tag, const char* fmt, ...) 111int __android_log_print(int prio, const char* tag, const char* fmt, ...)
100#if defined(__GNUC__) 112#if defined(__GNUC__)
@@ -110,9 +122,9 @@ int __android_log_print(int prio, const char* tag, const char* fmt, ...)
110#endif 122#endif
111 ; 123 ;
112 124
113/* 125/**
114 * A variant of __android_log_print() that takes a va_list to list 126 * Equivalent to `__android_log_print`, but taking a `va_list`.
115 * additional parameters. 127 * (If `__android_log_print` is like `printf`, this is like `vprintf`.)
116 */ 128 */
117int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap) 129int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap)
118#if defined(__GNUC__) 130#if defined(__GNUC__)
@@ -128,9 +140,20 @@ int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap)
128#endif 140#endif
129 ; 141 ;
130 142
131/* 143/**
132 * Log an assertion failure and abort the process to have a chance 144 * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to
133 * to inspect it if a debugger is attached. This uses the FATAL priority. 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.
134 */ 157 */
135void __android_log_assert(const char* cond, const char* tag, const char* fmt, 158void __android_log_assert(const char* cond, const char* tag, const char* fmt,
136 ...) 159 ...)