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