1LIBLOG(3) Android NDK Programming Manual LIBLOG(3) 2 3 4 5NAME 6 liblog - Android NDK logger interfaces 7 8SYNOPSIS 9 #include <log/log.h> 10 11 ALOG(android_priority, tag, format, ...) 12 IF_ALOG(android_priority, tag) 13 LOG_PRI(priority, tag, format, ...) 14 LOG_PRI_VA(priority, tag, format, args) 15 #define LOG_TAG NULL 16 ALOGV(format, ...) 17 SLOGV(format, ...) 18 RLOGV(format, ...) 19 ALOGV_IF(cond, format, ...) 20 SLOGV_IF(cond, format, ...) 21 RLOGV_IF(cond, format, ...) 22 IF_ALOGC() 23 ALOGD(format, ...) 24 SLOGD(format, ...) 25 RLOGD(format, ...) 26 ALOGD_IF(cond, format, ...) 27 SLOGD_IF(cond, format, ...) 28 RLOGD_IF(cond, format, ...) 29 IF_ALOGD() 30 ALOGI(format, ...) 31 SLOGI(format, ...) 32 RLOGI(format, ...) 33 ALOGI_IF(cond, format, ...) 34 SLOGI_IF(cond, format, ...) 35 RLOGI_IF(cond, format, ...) 36 IF_ALOGI() 37 ALOGW(format, ...) 38 SLOGW(format, ...) 39 RLOGW(format, ...) 40 ALOGW_IF(cond, format, ...) 41 SLOGW_IF(cond, format, ...) 42 RLOGW_IF(cond, format, ...) 43 IF_ALOGW() 44 ALOGE(format, ...) 45 SLOGE(format, ...) 46 RLOGE(format, ...) 47 ALOGE_IF(cond, format, ...) 48 SLOGE_IF(cond, format, ...) 49 RLOGE_IF(cond, format, ...) 50 IF_ALOGE() 51 LOG_FATAL(format, ...) 52 LOG_ALWAYS_FATAL(format, ...) 53 LOG_FATAL_IF(cond, format, ...) 54 LOG_ALWAYS_FATAL_IF(cond, format, ...) 55 ALOG_ASSERT(cond, format, ...) 56 LOG_EVENT_INT(tag, value) 57 LOG_EVENT_LONG(tag, value) 58 59 Link with -llog 60 61 #include <log/logger.h> 62 63 log_id_t android_logger_get_id(struct logger *logger) 64 int android_logger_clear(struct logger *logger) 65 int android_logger_get_log_size(struct logger *logger) 66 int android_logger_get_log_readable_size(struct logger *logger) 67 int android_logger_get_log_version(struct logger *logger) 68 69 struct logger_list *android_logger_list_alloc(int mode, unsigned int 70 tail, pid_t pid) 71 struct logger *android_logger_open(struct logger_list *logger_list, 72 log_id_t id) 73 struct logger_list *android_logger_list_open(log_id_t id, int mode, 74 unsigned int tail, pid_t pid) 75 76 int android_logger_list_read(struct logger_list *logger_list, struct 77 log_msg *log_msg 78 79 void android_logger_list_free(struct logger_list *logger_list) 80 81 log_id_t android_name_to_log_id(const char *logName) 82 const char *android_log_id_to_name(log_id_t log_id) 83 84 Link with -llog 85 86DESCRIPTION 87 liblog represents an interface to the volatile Android Logging system 88 for NDK (Native) applications and libraries. Interfaces for either 89 writing or reading logs. The log buffers are divided up in Main, Sys‐ 90 tem, Radio and Events sub-logs. 91 92 The logging interfaces are a series of macros, all of which can be 93 overridden individually in order to control the verbosity of the appli‐ 94 cation or library. [ASR]LOG[VDIWE] calls are used to log to BAsic, 95 System or Radio sub-logs in either the Verbose, Debug, Info, Warning or 96 Error priorities. [ASR]LOG[VDIWE]_IF calls are used to perform thus 97 based on a condition being true. IF_ALOG[VDIWE] calls are true if the 98 current LOG_TAG is enabled at the specified priority. LOG_ALWAYS_FATAL 99 is used to ALOG a message, then kill the process. LOG_FATAL call is a 100 variant of LOG_ALWAYS_FATAL, only enabled in engineering, and not 101 release builds. ALOG_ASSERT is used to ALOG a message if the condition 102 is false; the condition is part of the logged message. 103 LOG_EVENT_(INT|LONG) is used to drop binary content into the Events 104 sub-log. 105 106 The log reading interfaces permit opening the logs either singly or 107 multiply, retrieving a log entry at a time in time sorted order, 108 optionally limited to a specific pid and tail of the log(s) and finally 109 a call closing the logs. A single log can be opened with android_log‐ 110 ger_list_open; or multiple logs can be opened with android_log‐ 111 ger_list_alloc, calling in turn the android_logger_open for each log 112 id. Each entry can be retrieved with android_logger_list_read. The 113 log(s) can be closed with android_logger_list_free. The logs should be 114 opened with an ANDROID_LOG_RDONLY mode. ANDROID_LOG_NONBLOCK mode 115 will report when the log reading is done with an EAGAIN error return 116 code, otherwise the android_logger_list_read call will block for new 117 entries. 118 119 The ANDROID_LOG_WRAP mode flag to the android_logger_list_alloc_time 120 signals logd to quiesce the reader until the buffer is about to prune 121 at the start time then proceed to dumping content. 122 123 The ANDROID_LOG_PSTORE mode flag to the android_logger_open is used to 124 switch from the active logs to the persistent logs from before the last 125 reboot. 126 127 The value returned by android_logger_open can be used as a parameter to 128 the android_logger_clear function to empty the sub-log. It is recom‐ 129 mended to only open log ANDROID_LOG_WRONLY in that case. 130 131 The value returned by android_logger_open can be used as a parameter to 132 the android_logger_get_log_(size|readable_size|version) to retrieve the 133 sub-log maximum size, readable size and log buffer format protocol ver‐ 134 sion respectively. android_logger_get_id returns the id that was used 135 when opening the sub-log. It is recommended to open the log 136 ANDROID_LOG_RDONLY in these cases. 137 138ERRORS 139 If messages fail, a negative error code will be returned to the caller. 140 141 The -ENOTCONN return code indicates that the logger daemon is stopped. 142 143 The -EBADF return code indicates that the log access point can not be 144 opened, or the log buffer id is out of range. 145 146 For the -EAGAIN return code, this means that the logging message was 147 temporarily backed-up either because of Denial Of Service (DOS) logging 148 pressure from some chatty application or service in the Android system, 149 or if too small of a value is set in /proc/sys/net/unix/max_dgram_qlen. 150 To aid in diagnosing the occurence of this, a binary event from liblog 151 will be sent to the log daemon once a new message can get through 152 indicating how many messages were dropped as a result. Please take 153 action to resolve the structural problems at the source. 154 155 It is generally not advised for the caller to retry the -EAGAIN return 156 code as this will only make the problem(s) worse and cause your 157 application to temporarily drop to the logger daemon priority, BATCH 158 scheduling policy and background task cgroup. If you require a group of 159 messages to be passed atomically, merge them into one message with 160 embedded newlines to the maximum length LOGGER_ENTRY_MAX_PAYLOAD. 161 162 Other return codes from writing operation can be returned. Since the 163 library retries on EINTR, -EINTR should never be returned. 164 165SEE ALSO 166 syslogd(8) 167 168 169 170 24 Jan 2014 LIBLOG(3) 171