• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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