doc/dlog_doc.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   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 __TIZEN_SYSTEM_DLOG_DOC_H__
  18 #define __TIZEN_SYSTEM_DLOG_DOC_H__
  19
  20 /**
  21  * @defgroup CAPI_SYSTEM_DLOG dlog
  22  * @brief The Dlog API provides functions for sending log output.
  23  * @ingroup CAPI_SYSTEM_FRAMEWORK
  24  * @section CAPI_SYSTEM_DLOG_HEADER Required Header
  25  *   \#include <dlog.h>
  26  *
  27  * @section CAPI_SYSTEM_DLOG_OVERVIEW Overview
  28  *
  29 Sending log message to circular buffer. dlog APIs include Priority and Tag. By using priority and Tag, we can easily filtered messages what we want to see.
  30 <h2 class="pg">priority</h2>
  31 priority level indicates the urgency of log message
  32
  33 <table>
  34 <tr>
  35         <th>Priority</th>
  36         <th>Description</th>
  37 </tr>
  38 <tr>
  39         <td>DLOG_DEBUG</td>
  40         <td>Debug messasge. - Log message which developer want to check.</td>
  41 </tr>
  42 <tr>
  43         <td>DLOG_INFO</td>
  44         <td>Information message - Normal operational messages. above of this priority will always be logged.</td>
  45 </tr>
  46 <tr>
  47         <td>DLOG_WARN</td>
  48         <td>Warning messages - Not an error, but indication that an error will occur if action is not taken.</td>
  49 </tr>
  50 <tr>
  51         <td>DLOG_ERROR</td>
  52         <td>Error message - Indicate error.</td>
  53 </tr>
  54 </table>
  55
  56 <h2 class="pg">Macro example for useful usage</h2>
  57 The dlog APIs can be used by defining own macros. The macros can be defined like below examples.
  58 Thus, developers can use appropriate method as a matter of convenience.
  59
  60 @code
  61 #undef LOG_TAG
  62 #define LOG_TAG "APP_TAG"
  63
  64 #define LOGI(fmt, arg...) \
  65         ({ do { \
  66                 dlog_print(DLOG_INFO, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  67         } while (0); })
  68 #define LOGW(fmt, arg...) \
  69         ({ do { \
  70                 dlog_print(DLOG_WARN, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  71         } while (0); })
  72 #define LOGE(fmt, arg...) \
  73         ({ do { \
  74                 dlog_print(DLOG_ERROR, LOG_TAG, "%s: %s(%d) > " fmt, __MODULE__, __func__, __LINE__, ##arg); \
  75         } while (0); })
  76 @endcode
  77
  78 <h1 class="pg">dlogutil</h1>
  79 <h2 class="pg">Introduction</h2>
  80 You can use dlogutil command to view and follow the contents of the log buffers. The general usage is :
  81 @code
  82 dlogutil [<option>] ... [<filter-spec>] ...
  83 @endcode
  84
  85 <h2 class="pg">Filtering log output</h2>
  86 Every log message has a <I>tag</I> and a <I>priority</I> associated with it.
  87 Filter expression follows this format <B><I>tag:priority</I></B> where <I>tag</I> indicates the tag of interest and <I>priority</I> indicates the minimum level of priority to report for that tag. You can add any number of tag:priority specifications in a single filter expression.
  88 The tag of a log message is a short indicating the system component from which the message originates
  89 The <I>priority</I> is one of the following character values, orderd from lowest to highest priority:<br>
  90 D - debug<br>
  91 I - info<br>
  92 W - warning<br>
  93 E - Error<br>
  94
  95 for example, if you want to see MY_APP tag and above of debug priority,
  96 @code
  97 # dlogutil MY_APP:D
  98 @endcode
  99 if you want to see all log message above of info priority.
 100 @code
 101 # dlogutil *:I
 102 @endcode
 103
 104 <h2 class="pg">List of logutil command options</h2>
 105
 106 <table>
 107 <tr>
 108         <th>Option</th>
 109         <th>Description</th>
 110 </tr>
 111 <tr>
 112         <td>-b \<buffer\> </td>
 113         <td>Alternate log buffer. The main buffer is used by default buffer. </td>
 114 </tr>
 115 <tr>
 116         <td>-c</td>
 117         <td>Clears the entire log and exits</td>
 118 </tr>
 119 <tr>
 120         <td>-d</td>
 121         <td>Dumps the log and exits.</td>
 122 </tr>
 123 <tr>
 124         <td>-f \<filename\></td>
 125         <td>Writes log to filename. The default is stdout</td>
 126 </tr>
 127 <tr>
 128         <td>-g</td>
 129         <td>Print the size of the specified log buffer and exits.</td>
 130 </tr>
 131 <tr>
 132         <td>-n \<count\></td>
 133         <td>Sets the maximum number of rotated logs to count. The default value is 4. Requires the -r option</td>
 134 </tr>
 135 <tr>
 136         <td>-r \<Kbytes\></td>
 137         <td>Rotates the log file every Kbytes of output. The default value is 16. Requires the -f option.</td>
 138 </tr>
 139 <tr>
 140         <td>-s</td>
 141         <td>Sets the default filter spec to silent.</td>
 142 </tr>
 143 <tr>
 144         <td>-v \<format\></td>
 145         <td>Sets the output format for log messages. The default is brief format. </td>
 146 </tr>
 147
 148 </table>
 149 >>>>>>> mobile
 150 *
 151 **/
 152 #endif /* __TIZEN_SYSTEM_DLOG_DOC_H__ */