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
73extern "C" {
74#endif
75
76/**
77 * Android log priority values, in increasing order of priority.
78 */
79typedef 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 */
104int __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 */
111int __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 */
129int __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 */
158void __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
176typedef 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 */
195int __android_log_buf_write(int bufID, int prio, const char* tag,
196                            const char* text);
197int __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