Debian Codegraph @

www/errlog.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>The Error And Warning Log</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 The Error And Warning Log
122 </div>
123 <details class="fancy_toc">
124 <summary>Table Of Contents</summary>
125 <div id="toc_sub"><div class="fancy-toc1"><a href="#setting_up_the_error_logging_callback">1. Setting Up The Error Logging Callback</a></div>
126 <div class="fancy-toc1"><a href="#interface_details">2. Interface Details</a></div>
127 <div class="fancy-toc1"><a href="#variety_of_error_messages">3. Variety of Error Messages</a></div>
128 <div class="fancy-toc1"><a href="#summary">4. Summary</a></div>
129 </div>
130 </details>
131 </div>
132
133
134
135
136 <h2 style="margin-left:1.0em" notoc="1" id="overview"> Overview</h2>
137
138 <p>SQLite can be configured to invoke a callback function containing
139 an error code and a terse error message whenever anomalies occur.
140 This mechanism is very helpful in tracking obscure problems that
141 occur rarely and in the field. Application developers are encouraged
142 to take advantage of the error logging facility of SQLite in their
143 products, as it is very low CPU and memory cost but can be a
144 huge aid for debugging.</p>
145
146 <h1 id="setting_up_the_error_logging_callback"><span>1. </span>Setting Up The Error Logging Callback</h1>
147
148 <p>There can only be a single error logging callback per process.
149 The error logging callback is registered at start-time using C-code
150 similar to the following:
151
152 </p><blockquote><pre>
153 <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglog">SQLITE_CONFIG_LOG</a>, errorLogCallback, pData);
154 </pre></blockquote>
155
156 <p>The error logger callback function might look something like this:</p>
157
158 <blockquote><pre>
159 void errorLogCallback(void *pArg, int iErrCode, const char *zMsg){
160 fprintf(stderr, "(%d) %s\n", iErrCode, zMsg);
161 }
162 </pre></blockquote>
163
164 <p>The example above illustrates the signature of the error logger callback.
165 However, in an embedded application, one usually does not print
166 messages on stderr. Instead, one might store the messages in a
167 preallocated circular buffer where they can be accessed when diagnostic
168 information is needed during debugging. Or perhaps the messages can be
169 sent to <a href="http://en.wikipedia.org/wiki/Syslog">Syslog</a>. Somehow, the
170 messages need to be stored where they are accessible to developers,
171 not displayed to end users.</p>
172
173 <p>Do not misunderstand: There is nothing technically wrong with displaying
174 the error logger messages to end users. The messages do not contain
175 sensitive or private information that must be protected from unauthorized
176 viewing. Rather the messages are technical in nature and are not useful
177 or meaningful to the typical end user. The messages coming from the
178 error logger are intended for database geeks. Display them accordingly.</p>
179
180 <h1 id="interface_details"><span>2. </span>Interface Details</h1>
181
182 <p>The third argument to the <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglog">SQLITE_CONFIG_LOG</a>,...)
183 interface (the "pData" argument in the example above) is a pointer to arbitrary
184 data. SQLite passes this pointer through to the first argument of the
185 error logger callback. The pointer can be used to pass application-specific
186 setup or state information, if desired. Or it can simply be a NULL
187 pointer which is ignored by the callback.</p>
188
189 <p>The second argument to the error logger callback is an integer
190 <a href="rescode.html#extrc">extended error code</a>. The third argument to the error logger is the
191 text of the error message. The error message text is stored in a fixed-length
192 stack buffer in the calling function and so will only be valid for the
193 duration of the error logger callback function. The error logger should
194 make a copy of this message into persistent storage if retention of the
195 message is needed.</p>
196
197 <p>The error logger callback should be treated like a signal handler.
198 The application should save off or otherwise process the error, then return
199 as soon as possible. No other SQLite APIs should be invoked, directly or
200 indirectly, from the error logger. SQLite is <u>not</u> reentrant through
201 the error logger callback. In particular, the error logger callback
202 is invoked when a memory allocation fails, so it is generally a bad idea
203 to try to allocate memory inside the error logger. Do not even think
204 about trying to store the error message in another SQLite database.</p>
205
206 <p>Applications can use the <a href="c3ref/log.html">sqlite3_log(E,F,..)</a> API to send new messages
207 to the log, if desired, but this is discouraged. The <a href="c3ref/log.html">sqlite3_log()</a>
208 interface is intended for use by extensions only, not by applications.</p>
209
210 <h1 id="variety_of_error_messages"><span>3. </span>Variety of Error Messages</h1>
211
212 <p>The error messages that might be sent to the error logger and their
213 exact format is subject to changes from one release to the next. So
214 applications should not depend on any particular error message text formats or
215 error codes. Things do not change capriciously, but they do sometimes
216 changes.</p>
217
218 <p>The following is a partial list of the kinds of messages that might
219 appear in the error logger callback.</p>
220
221 <ul>
222 <li><p>
223 Any time there is an error either compiling an SQL statement
224 (using <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> or its siblings) or running an SQL
225 statement (using <a href="c3ref/step.html">sqlite3_step()</a>) that error is logged.
226 </p>
227
228 </li><li><p>
229 When a schema change occurs that requires a prepared statement to be reparsed
230 and reprepared, that event is logged with the error code SQLITE_SCHEMA.
231 The reparse and reprepare is normally automatic (assuming that
232 <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> has been used to prepare the statements originally,
233 which is recommended) and so these logging events are normally the only
234 way to know that reprepares are taking place.</p>
235
236 </li><li><p>
237 SQLITE_NOTICE messages are logged whenever a database has to be recovered
238 because the previous writer crashed without completing its transaction.
239 The error code is SQLITE_NOTICE_RECOVER_ROLLBACK when recovering a
240 <a href="lockingv3.html#rollback">rollback journal</a> and SQLITE_NOTICE_RECOVER_WAL when recovering a
241 <a href="wal.html">write-ahead log</a>.
242 </p>
243
244 </li><li><p>
245 SQLITE_WARNING messages are logged when database files are renamed or
246 aliased in ways that can lead to database corruption.
247 (See <a href="howtocorrupt.html#unlink">1</a> and <a href="howtocorrupt.html#alias">2</a> for
248 additional information.)
249 </p>
250
251 </li><li><p>
252 Out of memory (OOM) error conditions generate error logging events
253 with the SQLITE_NOMEM error code and a message that says how many bytes
254 of memory were requested by the failed allocation.
255 </p>
256
257 </li><li><p>I/O errors in the OS-interface generate error logging events.
258 The message to these events gives the line number in the source code where
259 the error originated and the filename associated with the event when
260 there is a corresponding file. </p>
261
262 </li><li><p>When database corruption is detected, an SQLITE_CORRUPT error
263 logger callback is invoked. As with I/O errors, the error message text
264 contains the line number in the original source code where the error
265 was first detected.</p>
266
267 </li><li><p>
268 An error logger callback is invoked on SQLITE_MISUSE errors.
269 This is useful in detecting application design issues when return codes
270 are not consistently checked in the application code.
271 </p></li></ul>
272
273 <p>SQLite strives to keep error logger traffic low and only send messages
274 to the error logger when there really is something wrong. Applications
275 might further cull the error message traffic
276 by deliberately ignoring certain classes of error
277 messages that they do not care about. For example, an application that
278 makes frequent database schema changes might want to ignore all
279 SQLITE_SCHEMA errors.</p>
280
281 <h1 id="summary"><span>4. </span>Summary</h1>
282
283 <p>The use of the error logger callback is highly recommended.
284 The debugging information that the error logger provides has proven
285 very useful in tracking down obscure problems that occur with applications
286 after they get into the field. The error logger callback has also
287 proven useful in catching occasional errors that the application
288 misses because of inconsistent checking of API return codes.
289 Developers are encouraged to implement an error logger callback early
290 in the development cycle in order to spot unexpected behavior quickly,
291 and to leave the error logger callback turned on through deployment.
292 If the error logger never finds a problem, then no harm is done.
293 But failure to set up an appropriate error logger might compromise
294 diagnostic capabilities later on.</p>
295 <p align="center"><small><i>This page was last updated on 2022-04-18 02:55:50Z </small></i></p>
296