1 /*
2 * Copyright (C) 2015 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_BASE_LOGGING_H
18 #define ANDROID_BASE_LOGGING_H
19
20 //
21 // Google-style C++ logging.
22 //
23
24 // This header provides a C++ stream interface to logging.
25 //
26 // To log:
27 //
28 // LOG(INFO) << "Some text; " << some_value;
29 //
30 // Replace `INFO` with any severity from `enum LogSeverity`.
31 //
32 // To log the result of a failed function and include the string
33 // representation of `errno` at the end:
34 //
35 // PLOG(ERROR) << "Write failed";
36 //
37 // The output will be something like `Write failed: I/O error`.
38 // Remember this as 'P' as in perror(3).
39 //
40 // To output your own types, simply implement operator<< as normal.
41 //
42 // By default, output goes to logcat on Android and stderr on the host.
43 // A process can use `SetLogger` to decide where all logging goes.
44 // Implementations are provided for logcat, stderr, and dmesg.
45
46 // This header also provides assertions:
47 //
48 // CHECK(must_be_true);
49 // CHECK_EQ(a, b) << z_is_interesting_too;
50
51 // NOTE: For Windows, you must include logging.h after windows.h to allow the
52 // following code to suppress the evil ERROR macro:
53 #ifdef _WIN32
54 // windows.h includes wingdi.h which defines an evil macro ERROR.
55 #ifdef ERROR
56 #undef ERROR
57 #endif
58 #endif
59
60 #include <functional>
61 #include <memory>
62 #include <ostream>
63
64 #include "android-base/macros.h"
65
66 namespace android {
67 namespace base {
68
69 enum LogSeverity {
70 VERBOSE,
71 DEBUG,
72 INFO,
73 WARNING,
74 ERROR,
75 FATAL_WITHOUT_ABORT,
76 FATAL,
77 };
78
79 enum LogId {
80 DEFAULT,
81 MAIN,
82 SYSTEM,
83 };
84
85 using LogFunction = std::function<void(LogId, LogSeverity, const char*, const char*,
86 unsigned int, const char*)>;
87 using AbortFunction = std::function<void(const char*)>;
88
89 void KernelLogger(LogId, LogSeverity, const char*, const char*, unsigned int, const char*);
90 void StderrLogger(LogId, LogSeverity, const char*, const char*, unsigned int, const char*);
91
92 void DefaultAborter(const char* abort_message);
93
94 #ifdef __ANDROID__
95 // We expose this even though it is the default because a user that wants to
96 // override the default log buffer will have to construct this themselves.
97 class LogdLogger {
98 public:
99 explicit LogdLogger(LogId default_log_id = android::base::MAIN);
100
101 void operator()(LogId, LogSeverity, const char* tag, const char* file,
102 unsigned int line, const char* message);
103
104 private:
105 LogId default_log_id_;
106 };
107 #endif
108
109 // Configure logging based on ANDROID_LOG_TAGS environment variable.
110 // We need to parse a string that looks like
111 //
112 // *:v jdwp:d dalvikvm:d dalvikvm-gc:i dalvikvmi:i
113 //
114 // The tag (or '*' for the global level) comes first, followed by a colon and a
115 // letter indicating the minimum priority level we're expected to log. This can
116 // be used to reveal or conceal logs with specific tags.
117 #ifdef __ANDROID__
118 #define INIT_LOGGING_DEFAULT_LOGGER LogdLogger()
119 #else
120 #define INIT_LOGGING_DEFAULT_LOGGER StderrLogger
121 #endif
122 void InitLogging(char* argv[],
123 LogFunction&& logger = INIT_LOGGING_DEFAULT_LOGGER,
124 AbortFunction&& aborter = DefaultAborter);
125 #undef INIT_LOGGING_DEFAULT_LOGGER
126
127 // Replace the current logger.
128 void SetLogger(LogFunction&& logger);
129
130 // Replace the current aborter.
131 void SetAborter(AbortFunction&& aborter);
132
133 class ErrnoRestorer {
134 public:
ErrnoRestorer()135 ErrnoRestorer()
136 : saved_errno_(errno) {
137 }
138
~ErrnoRestorer()139 ~ErrnoRestorer() {
140 errno = saved_errno_;
141 }
142
143 // Allow this object to be used as part of && operation.
144 operator bool() const {
145 return true;
146 }
147
148 private:
149 const int saved_errno_;
150
151 DISALLOW_COPY_AND_ASSIGN(ErrnoRestorer);
152 };
153
154 // A helper macro that produces an expression that accepts both a qualified name and an
155 // unqualified name for a LogSeverity, and returns a LogSeverity value.
156 // Note: DO NOT USE DIRECTLY. This is an implementation detail.
157 #define SEVERITY_LAMBDA(severity) ([&]() { \
158 using ::android::base::VERBOSE; \
159 using ::android::base::DEBUG; \
160 using ::android::base::INFO; \
161 using ::android::base::WARNING; \
162 using ::android::base::ERROR; \
163 using ::android::base::FATAL_WITHOUT_ABORT; \
164 using ::android::base::FATAL; \
165 return (severity); }())
166
167 #ifdef __clang_analyzer__
168 // Clang's static analyzer does not see the conditional statement inside
169 // LogMessage's destructor that will abort on FATAL severity.
170 #define ABORT_AFTER_LOG_FATAL for (;; abort())
171
172 struct LogAbortAfterFullExpr {
~LogAbortAfterFullExprLogAbortAfterFullExpr173 ~LogAbortAfterFullExpr() __attribute__((noreturn)) { abort(); }
174 explicit operator bool() const { return false; }
175 };
176 // Provides an expression that evaluates to the truthiness of `x`, automatically
177 // aborting if `c` is true.
178 #define ABORT_AFTER_LOG_EXPR_IF(c, x) (((c) && ::android::base::LogAbortAfterFullExpr()) || (x))
179 // Note to the static analyzer that we always execute FATAL logs in practice.
180 #define MUST_LOG_MESSAGE(severity) (SEVERITY_LAMBDA(severity) == ::android::base::FATAL)
181 #else
182 #define ABORT_AFTER_LOG_FATAL
183 #define ABORT_AFTER_LOG_EXPR_IF(c, x) (x)
184 #define MUST_LOG_MESSAGE(severity) false
185 #endif
186 #define ABORT_AFTER_LOG_FATAL_EXPR(x) ABORT_AFTER_LOG_EXPR_IF(true, x)
187
188 // Defines whether the given severity will be logged or silently swallowed.
189 #define WOULD_LOG(severity) \
190 (UNLIKELY((SEVERITY_LAMBDA(severity)) >= ::android::base::GetMinimumLogSeverity()) || \
191 MUST_LOG_MESSAGE(severity))
192
193 // Get an ostream that can be used for logging at the given severity and to the default
194 // destination.
195 //
196 // Notes:
197 // 1) This will not check whether the severity is high enough. One should use WOULD_LOG to filter
198 // usage manually.
199 // 2) This does not save and restore errno.
200 #define LOG_STREAM(severity) LOG_STREAM_TO(DEFAULT, severity)
201
202 // Get an ostream that can be used for logging at the given severity and to the
203 // given destination. The same notes as for LOG_STREAM apply.
204 #define LOG_STREAM_TO(dest, severity) \
205 ::android::base::LogMessage(__FILE__, __LINE__, \
206 ::android::base::dest, \
207 SEVERITY_LAMBDA(severity), -1).stream()
208
209 // Logs a message to logcat on Android otherwise to stderr. If the severity is
210 // FATAL it also causes an abort. For example:
211 //
212 // LOG(FATAL) << "We didn't expect to reach here";
213 #define LOG(severity) LOG_TO(DEFAULT, severity)
214
215 // Checks if we want to log something, and sets up appropriate RAII objects if
216 // so.
217 // Note: DO NOT USE DIRECTLY. This is an implementation detail.
218 #define LOGGING_PREAMBLE(severity) \
219 (WOULD_LOG(severity) && \
220 ABORT_AFTER_LOG_EXPR_IF((SEVERITY_LAMBDA(severity)) == ::android::base::FATAL, true) && \
221 ::android::base::ErrnoRestorer())
222
223 // Logs a message to logcat with the specified log ID on Android otherwise to
224 // stderr. If the severity is FATAL it also causes an abort.
225 // Use an expression here so we can support the << operator following the macro,
226 // like "LOG(DEBUG) << xxx;".
227 #define LOG_TO(dest, severity) LOGGING_PREAMBLE(severity) && LOG_STREAM_TO(dest, severity)
228
229 // A variant of LOG that also logs the current errno value. To be used when
230 // library calls fail.
231 #define PLOG(severity) PLOG_TO(DEFAULT, severity)
232
233 // Behaves like PLOG, but logs to the specified log ID.
234 #define PLOG_TO(dest, severity) \
235 LOGGING_PREAMBLE(severity) && \
236 ::android::base::LogMessage(__FILE__, __LINE__, ::android::base::dest, \
237 SEVERITY_LAMBDA(severity), errno) \
238 .stream()
239
240 // Marker that code is yet to be implemented.
241 #define UNIMPLEMENTED(level) \
242 LOG(level) << __PRETTY_FUNCTION__ << " unimplemented "
243
244 // Check whether condition x holds and LOG(FATAL) if not. The value of the
245 // expression x is only evaluated once. Extra logging can be appended using <<
246 // after. For example:
247 //
248 // CHECK(false == true) results in a log message of
249 // "Check failed: false == true".
250 #define CHECK(x) \
251 LIKELY((x)) || ABORT_AFTER_LOG_FATAL_EXPR(false) || \
252 ::android::base::LogMessage( \
253 __FILE__, __LINE__, ::android::base::DEFAULT, ::android::base::FATAL, \
254 -1).stream() \
255 << "Check failed: " #x << " "
256
257 // Helper for CHECK_xx(x,y) macros.
258 #define CHECK_OP(LHS, RHS, OP) \
259 for (auto _values = ::android::base::MakeEagerEvaluator(LHS, RHS); \
260 UNLIKELY(!(_values.lhs OP _values.rhs)); \
261 /* empty */) \
262 ABORT_AFTER_LOG_FATAL \
263 ::android::base::LogMessage(__FILE__, __LINE__, ::android::base::DEFAULT, \
264 ::android::base::FATAL, -1).stream() \
265 << "Check failed: " << #LHS << " " << #OP << " " << #RHS \
266 << " (" #LHS "=" << _values.lhs << ", " #RHS "=" << _values.rhs << ") "
267
268 // Check whether a condition holds between x and y, LOG(FATAL) if not. The value
269 // of the expressions x and y is evaluated once. Extra logging can be appended
270 // using << after. For example:
271 //
272 // CHECK_NE(0 == 1, false) results in
273 // "Check failed: false != false (0==1=false, false=false) ".
274 #define CHECK_EQ(x, y) CHECK_OP(x, y, == )
275 #define CHECK_NE(x, y) CHECK_OP(x, y, != )
276 #define CHECK_LE(x, y) CHECK_OP(x, y, <= )
277 #define CHECK_LT(x, y) CHECK_OP(x, y, < )
278 #define CHECK_GE(x, y) CHECK_OP(x, y, >= )
279 #define CHECK_GT(x, y) CHECK_OP(x, y, > )
280
281 // Helper for CHECK_STRxx(s1,s2) macros.
282 #define CHECK_STROP(s1, s2, sense) \
283 while (UNLIKELY((strcmp(s1, s2) == 0) != (sense))) \
284 ABORT_AFTER_LOG_FATAL \
285 ::android::base::LogMessage(__FILE__, __LINE__, ::android::base::DEFAULT, \
286 ::android::base::FATAL, -1).stream() \
287 << "Check failed: " << "\"" << (s1) << "\"" \
288 << ((sense) ? " == " : " != ") << "\"" << (s2) << "\""
289
290 // Check for string (const char*) equality between s1 and s2, LOG(FATAL) if not.
291 #define CHECK_STREQ(s1, s2) CHECK_STROP(s1, s2, true)
292 #define CHECK_STRNE(s1, s2) CHECK_STROP(s1, s2, false)
293
294 // Perform the pthread function call(args), LOG(FATAL) on error.
295 #define CHECK_PTHREAD_CALL(call, args, what) \
296 do { \
297 int rc = call args; \
298 if (rc != 0) { \
299 errno = rc; \
300 ABORT_AFTER_LOG_FATAL \
301 PLOG(FATAL) << #call << " failed for " << (what); \
302 } \
303 } while (false)
304
305 // CHECK that can be used in a constexpr function. For example:
306 //
307 // constexpr int half(int n) {
308 // return
309 // DCHECK_CONSTEXPR(n >= 0, , 0)
310 // CHECK_CONSTEXPR((n & 1) == 0),
311 // << "Extra debugging output: n = " << n, 0)
312 // n / 2;
313 // }
314 #define CHECK_CONSTEXPR(x, out, dummy) \
315 (UNLIKELY(!(x))) \
316 ? (LOG(FATAL) << "Check failed: " << #x out, dummy) \
317 :
318
319 // DCHECKs are debug variants of CHECKs only enabled in debug builds. Generally
320 // CHECK should be used unless profiling identifies a CHECK as being in
321 // performance critical code.
322 #if defined(NDEBUG) && !defined(__clang_analyzer__)
323 static constexpr bool kEnableDChecks = false;
324 #else
325 static constexpr bool kEnableDChecks = true;
326 #endif
327
328 #define DCHECK(x) \
329 if (::android::base::kEnableDChecks) CHECK(x)
330 #define DCHECK_EQ(x, y) \
331 if (::android::base::kEnableDChecks) CHECK_EQ(x, y)
332 #define DCHECK_NE(x, y) \
333 if (::android::base::kEnableDChecks) CHECK_NE(x, y)
334 #define DCHECK_LE(x, y) \
335 if (::android::base::kEnableDChecks) CHECK_LE(x, y)
336 #define DCHECK_LT(x, y) \
337 if (::android::base::kEnableDChecks) CHECK_LT(x, y)
338 #define DCHECK_GE(x, y) \
339 if (::android::base::kEnableDChecks) CHECK_GE(x, y)
340 #define DCHECK_GT(x, y) \
341 if (::android::base::kEnableDChecks) CHECK_GT(x, y)
342 #define DCHECK_STREQ(s1, s2) \
343 if (::android::base::kEnableDChecks) CHECK_STREQ(s1, s2)
344 #define DCHECK_STRNE(s1, s2) \
345 if (::android::base::kEnableDChecks) CHECK_STRNE(s1, s2)
346 #if defined(NDEBUG) && !defined(__clang_analyzer__)
347 #define DCHECK_CONSTEXPR(x, out, dummy)
348 #else
349 #define DCHECK_CONSTEXPR(x, out, dummy) CHECK_CONSTEXPR(x, out, dummy)
350 #endif
351
352 // Temporary class created to evaluate the LHS and RHS, used with
353 // MakeEagerEvaluator to infer the types of LHS and RHS.
354 template <typename LHS, typename RHS>
355 struct EagerEvaluator {
EagerEvaluatorEagerEvaluator356 constexpr EagerEvaluator(LHS l, RHS r) : lhs(l), rhs(r) {
357 }
358 LHS lhs;
359 RHS rhs;
360 };
361
362 // Helper function for CHECK_xx.
363 template <typename LHS, typename RHS>
MakeEagerEvaluator(LHS lhs,RHS rhs)364 constexpr EagerEvaluator<LHS, RHS> MakeEagerEvaluator(LHS lhs, RHS rhs) {
365 return EagerEvaluator<LHS, RHS>(lhs, rhs);
366 }
367
368 // Explicitly instantiate EagerEvalue for pointers so that char*s aren't treated
369 // as strings. To compare strings use CHECK_STREQ and CHECK_STRNE. We rely on
370 // signed/unsigned warnings to protect you against combinations not explicitly
371 // listed below.
372 #define EAGER_PTR_EVALUATOR(T1, T2) \
373 template <> \
374 struct EagerEvaluator<T1, T2> { \
375 EagerEvaluator(T1 l, T2 r) \
376 : lhs(reinterpret_cast<const void*>(l)), \
377 rhs(reinterpret_cast<const void*>(r)) { \
378 } \
379 const void* lhs; \
380 const void* rhs; \
381 }
382 EAGER_PTR_EVALUATOR(const char*, const char*);
383 EAGER_PTR_EVALUATOR(const char*, char*);
384 EAGER_PTR_EVALUATOR(char*, const char*);
385 EAGER_PTR_EVALUATOR(char*, char*);
386 EAGER_PTR_EVALUATOR(const unsigned char*, const unsigned char*);
387 EAGER_PTR_EVALUATOR(const unsigned char*, unsigned char*);
388 EAGER_PTR_EVALUATOR(unsigned char*, const unsigned char*);
389 EAGER_PTR_EVALUATOR(unsigned char*, unsigned char*);
390 EAGER_PTR_EVALUATOR(const signed char*, const signed char*);
391 EAGER_PTR_EVALUATOR(const signed char*, signed char*);
392 EAGER_PTR_EVALUATOR(signed char*, const signed char*);
393 EAGER_PTR_EVALUATOR(signed char*, signed char*);
394
395 // Data for the log message, not stored in LogMessage to avoid increasing the
396 // stack size.
397 class LogMessageData;
398
399 // A LogMessage is a temporarily scoped object used by LOG and the unlikely part
400 // of a CHECK. The destructor will abort if the severity is FATAL.
401 class LogMessage {
402 public:
403 LogMessage(const char* file, unsigned int line, LogId id,
404 LogSeverity severity, int error);
405
406 ~LogMessage();
407
408 // Returns the stream associated with the message, the LogMessage performs
409 // output when it goes out of scope.
410 std::ostream& stream();
411
412 // The routine that performs the actual logging.
413 static void LogLine(const char* file, unsigned int line, LogId id,
414 LogSeverity severity, const char* msg);
415
416 private:
417 const std::unique_ptr<LogMessageData> data_;
418
419 DISALLOW_COPY_AND_ASSIGN(LogMessage);
420 };
421
422 // Get the minimum severity level for logging.
423 LogSeverity GetMinimumLogSeverity();
424
425 // Set the minimum severity level for logging, returning the old severity.
426 LogSeverity SetMinimumLogSeverity(LogSeverity new_severity);
427
428 // Allows to temporarily change the minimum severity level for logging.
429 class ScopedLogSeverity {
430 public:
431 explicit ScopedLogSeverity(LogSeverity level);
432 ~ScopedLogSeverity();
433
434 private:
435 LogSeverity old_;
436 };
437
438 } // namespace base
439 } // namespace android
440
441 #endif // ANDROID_BASE_LOGGING_H
442