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
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Configuration Options</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
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;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: SQLITE_CONFIG_COVERING_INDEX_SCAN SQLITE_CONFIG_GETMALLOC SQLITE_CONFIG_GETMUTEX SQLITE_CONFIG_GETPCACHE SQLITE_CONFIG_GETPCACHE2 SQLITE_CONFIG_HEAP SQLITE_CONFIG_LOG SQLITE_CONFIG_LOOKASIDE SQLITE_CONFIG_MALLOC SQLITE_CONFIG_MEMDB_MAXSIZE SQLITE_CONFIG_MEMSTATUS SQLITE_CONFIG_MMAP_SIZE SQLITE_CONFIG_MULTITHREAD SQLITE_CONFIG_MUTEX SQLITE_CONFIG_PAGECACHE SQLITE_CONFIG_PCACHE SQLITE_CONFIG_PCACHE2 SQLITE_CONFIG_PCACHE_HDRSZ SQLITE_CONFIG_PMASZ SQLITE_CONFIG_SCRATCH SQLITE_CONFIG_SERIALIZED SQLITE_CONFIG_SINGLETHREAD SQLITE_CONFIG_SMALL_MALLOC SQLITE_CONFIG_SORTERREF_SIZE SQLITE_CONFIG_SQLLOG SQLITE_CONFIG_STMTJRNL_SPILL SQLITE_CONFIG_URI SQLITE_CONFIG_WIN32_HEAPSIZE {configuration option} -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Configuration Options</h2>
</div>
<blockquote><pre>
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
#define SQLITE_CONFIG_PCACHE 14 /* no-op */
#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
#define SQLITE_CONFIG_URI 17 /* int */
#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
</pre></blockquote>
<p>
These constants are the available integer configuration options that
can be passed as the first argument to the <a href="../c3ref/config.html">sqlite3_config()</a> interface.</p>
<p>Most of the configuration options for sqlite3_config()
will only work if invoked prior to <a href="../c3ref/initialize.html">sqlite3_initialize()</a> or after
<a href="../c3ref/initialize.html">sqlite3_shutdown()</a>. The few exceptions to this rule are called
"anytime configuration options".
Calling <a href="../c3ref/config.html">sqlite3_config()</a> with a first argument that is not an
anytime configuration option in between calls to <a href="../c3ref/initialize.html">sqlite3_initialize()</a> and
<a href="../c3ref/initialize.html">sqlite3_shutdown()</a> is a no-op that returns SQLITE_MISUSE.</p>
<p>The set of anytime configuration options can change (by insertions
and/or deletions) from one release of SQLite to the next.
As of SQLite version 3.42.0, the complete set of anytime configuration
options is:
<ul>
<li> SQLITE_CONFIG_LOG
<li> SQLITE_CONFIG_PCACHE_HDRSZ
</ul></p>
<p>New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued. Applications
should check the return code from <a href="../c3ref/config.html">sqlite3_config()</a> to make sure that
the call worked. The <a href="../c3ref/config.html">sqlite3_config()</a> interface will return a
non-zero <a href="../rescode.html">error code</a> if a discontinued or unsupported configuration option
is invoked.</p>
<p><dl>
<a name="sqliteconfigsinglethread"></a>
<dt>SQLITE_CONFIG_SINGLETHREAD</dt>
<dd>There are no arguments to this option. This option sets the
<a href="../threadsafe.html">threading mode</a> to Single-thread. In other words, it disables
all mutexing and puts SQLite into a mode where it can only be used
by a single thread. If SQLite is compiled with
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
it is not possible to change the <a href="../threadsafe.html">threading mode</a> from its default
value of Single-thread and so <a href="../c3ref/config.html">sqlite3_config()</a> will return
<a href="../rescode.html#error">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD
configuration option.</dd></p>
<p><a name="sqliteconfigmultithread"></a>
<dt>SQLITE_CONFIG_MULTITHREAD</dt>
<dd>There are no arguments to this option. This option sets the
<a href="../threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables
mutexing on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
The application is responsible for serializing access to
<a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a>. But other mutexes
are enabled so that SQLite will be safe to use in a multi-threaded
environment as long as no two threads attempt to use the same
<a href="../c3ref/sqlite3.html">database connection</a> at the same time. If SQLite is compiled with
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
it is not possible to set the Multi-thread <a href="../threadsafe.html">threading mode</a> and
<a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../rescode.html#error">SQLITE_ERROR</a> if called with the
SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p>
<p><a name="sqliteconfigserialized"></a>
<dt>SQLITE_CONFIG_SERIALIZED</dt>
<dd>There are no arguments to this option. This option sets the
<a href="../threadsafe.html">threading mode</a> to Serialized. In other words, this option enables
all mutexes including the recursive
mutexes on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
In this mode (which is the default when SQLite is compiled with
<a href="../compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access
to <a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a> so that the
application is free to use the same <a href="../c3ref/sqlite3.html">database connection</a> or the
same <a href="../c3ref/stmt.html">prepared statement</a> in different threads at the same time.
If SQLite is compiled with
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
it is not possible to set the Serialized <a href="../threadsafe.html">threading mode</a> and
<a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../rescode.html#error">SQLITE_ERROR</a> if called with the
SQLITE_CONFIG_SERIALIZED configuration option.</dd></p>
<p><a name="sqliteconfigmalloc"></a>
<dt>SQLITE_CONFIG_MALLOC</dt>
<dd> The SQLITE_CONFIG_MALLOC option takes a single argument which is
a pointer to an instance of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure.
The argument specifies
alternative low-level memory allocation routines to be used in place of
the memory allocation routines built into SQLite. SQLite makes
its own private copy of the content of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure
before the <a href="../c3ref/config.html">sqlite3_config()</a> call returns.</dd></p>
<p><a name="sqliteconfiggetmalloc"></a>
<dt>SQLITE_CONFIG_GETMALLOC</dt>
<dd> The SQLITE_CONFIG_GETMALLOC option takes a single argument which
is a pointer to an instance of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure.
The <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a>
structure is filled with the currently defined memory allocation routines.
This option can be used to overload the default memory allocation
routines with a wrapper that simulations memory allocation failure or
tracks memory usage, for example. </dd></p>
<p><a name="sqliteconfigsmallmalloc"></a>
<dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
<dd> The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
type int, interpreted as a boolean, which if true provides a hint to
SQLite that it should avoid large memory allocations if possible.
SQLite will run faster if it is free to make large memory allocations,
but some application might prefer to run slower in exchange for
guarantees about memory fragmentation that are possible if large
allocations are avoided. This hint is normally off.
</dd></p>
<p><a name="sqliteconfigmemstatus"></a>
<dt>SQLITE_CONFIG_MEMSTATUS</dt>
<dd> The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
interpreted as a boolean, which enables or disables the collection of
memory allocation statistics. When memory allocation statistics are
disabled, the following SQLite interfaces become non-operational:
<ul>
<li> <a href="../c3ref/hard_heap_limit64.html">sqlite3_hard_heap_limit64()</a>
<li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_used()</a>
<li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>
<li> <a href="../c3ref/hard_heap_limit64.html">sqlite3_soft_heap_limit64()</a>
<li> <a href="../c3ref/status.html">sqlite3_status64()</a>
</ul>
Memory allocation statistics are enabled by default unless SQLite is
compiled with <a href="../compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory
allocation statistics are disabled by default.
</dd></p>
<p><a name="sqliteconfigscratch"></a>
<dt>SQLITE_CONFIG_SCRATCH</dt>
<dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
</dd></p>
<p><a name="sqliteconfigpagecache"></a>
<dt>SQLITE_CONFIG_PAGECACHE</dt>
<dd> The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
that SQLite can use for the database page cache with the default page
cache implementation.
This configuration option is a no-op if an application-defined page
cache implementation is loaded using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>.
There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
8-byte aligned memory (pMem), the size of each page cache line (sz),
and the number of cache lines (N).
The sz argument should be the size of the largest database page
(a power of two between 512 and 65536) plus some extra bytes for each
page header. The number of extra bytes needed by the page header
can be determined using <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpcachehdrsz">SQLITE_CONFIG_PCACHE_HDRSZ</a>.
It is harmless, apart from the wasted memory,
for the sz parameter to be larger than necessary. The pMem
argument must be either a NULL pointer or a pointer to an 8-byte
aligned block of memory of at least sz*N bytes, otherwise
subsequent behavior is undefined.
When pMem is not NULL, SQLite will strive to use the memory provided
to satisfy page cache needs, falling back to <a href="../c3ref/free.html">sqlite3_malloc()</a> if
a page cache line is larger than sz bytes or if all of the pMem buffer
is exhausted.
If pMem is NULL and N is non-zero, then each database connection
does an initial bulk allocation for page cache memory
from <a href="../c3ref/free.html">sqlite3_malloc()</a> sufficient for N cache lines if N is positive or
of -1024*N bytes if N is negative, . If additional
page cache memory is needed beyond what is provided by the initial
allocation, then SQLite goes to <a href="../c3ref/free.html">sqlite3_malloc()</a> separately for each
additional cache line. </dd></p>
<p><a name="sqliteconfigheap"></a>
<dt>SQLITE_CONFIG_HEAP</dt>
<dd> The SQLITE_CONFIG_HEAP option specifies a static memory buffer
that SQLite will use for all of its dynamic memory allocation needs
beyond those provided for by <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
with either <a href="../compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or <a href="../compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> and returns
<a href="../rescode.html#error">SQLITE_ERROR</a> if invoked otherwise.
There are three arguments to SQLITE_CONFIG_HEAP:
An 8-byte aligned pointer to the memory,
the number of bytes in the memory buffer, and the minimum allocation size.
If the first pointer (the memory pointer) is NULL, then SQLite reverts
to using its default memory allocator (the system malloc() implementation),
undoing any prior invocation of <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the
memory pointer is not NULL then the alternative memory
allocator is engaged to handle all of SQLites memory allocation needs.
The first pointer (the memory pointer) must be aligned to an 8-byte
boundary or subsequent behavior of SQLite will be undefined.
The minimum allocation size is capped at 2**12. Reasonable values
for the minimum allocation size are 2**5 through 2**8.</dd></p>
<p><a name="sqliteconfigmutex"></a>
<dt>SQLITE_CONFIG_MUTEX</dt>
<dd> The SQLITE_CONFIG_MUTEX option takes a single argument which is a
pointer to an instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure.
The argument specifies alternative low-level mutex routines to be used
in place the mutex routines built into SQLite. SQLite makes a copy of
the content of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure before the call to
<a href="../c3ref/config.html">sqlite3_config()</a> returns. If SQLite is compiled with
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
the entire mutexing subsystem is omitted from the build and hence calls to
<a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will
return <a href="../rescode.html#error">SQLITE_ERROR</a>.</dd></p>
<p><a name="sqliteconfiggetmutex"></a>
<dt>SQLITE_CONFIG_GETMUTEX</dt>
<dd> The SQLITE_CONFIG_GETMUTEX option takes a single argument which
is a pointer to an instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure. The
<a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a>
structure is filled with the currently defined mutex routines.
This option can be used to overload the default mutex allocation
routines with a wrapper used to track mutex usage for performance
profiling or testing, for example. If SQLite is compiled with
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
the entire mutexing subsystem is omitted from the build and hence calls to
<a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will
return <a href="../rescode.html#error">SQLITE_ERROR</a>.</dd></p>
<p><a name="sqliteconfiglookaside"></a>
<dt>SQLITE_CONFIG_LOOKASIDE</dt>
<dd> The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
the default size of lookaside memory on each <a href="../c3ref/sqlite3.html">database connection</a>.
The first argument is the
size of each lookaside buffer slot and the second is the number of
slots allocated to each database connection. SQLITE_CONFIG_LOOKASIDE
sets the <i>default</i> lookaside size. The <a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfiglookaside">SQLITE_DBCONFIG_LOOKASIDE</a>
option to <a href="../c3ref/db_config.html">sqlite3_db_config()</a> can be used to change the lookaside
configuration on individual connections. </dd></p>
<p><a name="sqliteconfigpcache2"></a>
<dt>SQLITE_CONFIG_PCACHE2</dt>
<dd> The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
a pointer to an <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. This object specifies
the interface to a custom page cache implementation.
SQLite makes a copy of the <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object.</dd></p>
<p><a name="sqliteconfiggetpcache2"></a>
<dt>SQLITE_CONFIG_GETPCACHE2</dt>
<dd> The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
is a pointer to an <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. SQLite copies of
the current page cache implementation into that object. </dd></p>
<p><a name="sqliteconfiglog"></a>
<dt>SQLITE_CONFIG_LOG</dt>
<dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
global <a href="../errlog.html">error log</a>.
(The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
function with a call signature of void(*)(void*,int,const char*),
and a pointer to void. If the function pointer is not NULL, it is
invoked by <a href="../c3ref/log.html">sqlite3_log()</a> to process each logging event. If the
function pointer is NULL, the <a href="../c3ref/log.html">sqlite3_log()</a> interface becomes a no-op.
The void pointer that is the second argument to SQLITE_CONFIG_LOG is
passed through as the first parameter to the application-defined logger
function whenever that function is invoked. The second parameter to
the logger function is a copy of the first parameter to the corresponding
<a href="../c3ref/log.html">sqlite3_log()</a> call and is intended to be a <a href="../rescode.html">result code</a> or an
<a href="../rescode.html#extrc">extended result code</a>. The third parameter passed to the logger is
log message after formatting via <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a>.
The SQLite logging interface is not reentrant; the logger function
supplied by the application must not invoke any SQLite interface.
In a multi-threaded application, the application-defined logger
function must be threadsafe. </dd></p>
<p><a name="sqliteconfiguri"></a>
<dt>SQLITE_CONFIG_URI
<dd>The SQLITE_CONFIG_URI option takes a single argument of type int.
If non-zero, then URI handling is globally enabled. If the parameter is zero,
then URI handling is globally disabled. If URI handling is globally
enabled, all filenames passed to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open_v2()</a>,
<a href="../c3ref/open.html">sqlite3_open16()</a> or
specified as part of <a href="../lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless
of whether or not the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is set when the database
connection is opened. If it is globally disabled, filenames are
only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
database connection is opened. By default, URI handling is globally
disabled. The default value may be changed by compiling with the
<a href="../compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p>
<p><a name="sqliteconfigcoveringindexscan"></a>
<dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
<dd>The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
argument which is interpreted as a boolean in order to enable or disable
the use of covering indices for full table scans in the query optimizer.
The default setting is determined
by the <a href="../compile.html#allow_covering_index_scan">SQLITE_ALLOW_COVERING_INDEX_SCAN</a> compile-time option, or is "on"
if that compile-time option is omitted.
The ability to disable the use of covering indices for full table scans
is because some incorrectly coded legacy applications might malfunction
when the optimization is enabled. Providing the ability to
disable the optimization allows the older, buggy application code to work
without change even with newer versions of SQLite.</p>
<p><a name="sqliteconfigpcache"></a>
<a name="sqliteconfiggetpcache"></a>
<dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
<dd> These options are obsolete and should not be used by new code.
They are retained for backwards compatibility but are now no-ops.
</dd></p>
<p><a name="sqliteconfigsqllog"></a>
<dt>SQLITE_CONFIG_SQLLOG
<dd>This option is only available if sqlite is compiled with the
<a href="../compile.html#enable_sqllog">SQLITE_ENABLE_SQLLOG</a> pre-processor macro defined. The first argument should
be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
The second should be of type (void*). The callback is invoked by the library
in three separate circumstances, identified by the value passed as the
fourth parameter. If the fourth parameter is 0, then the database connection
passed as the second argument has just been opened. The third argument
points to a buffer containing the name of the main database file. If the
fourth parameter is 1, then the SQL statement that the third parameter
points to has just been executed. Or, if the fourth parameter is 2, then
the connection being passed as the second parameter is being closed. The
third parameter is passed NULL In this case. An example of using this
configuration option can be seen in the "test_sqllog.c" source file in
the canonical SQLite source tree.</dd></p>
<p><a name="sqliteconfigmmapsize"></a>
<dt>SQLITE_CONFIG_MMAP_SIZE
<dd>SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
that are the default mmap size limit (the default setting for
<a href="../pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) and the maximum allowed mmap size limit.
The default setting can be overridden by each database connection using
either the <a href="../pragma.html#pragma_mmap_size">PRAGMA mmap_size</a> command, or by using the
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control. The maximum allowed mmap size
will be silently truncated if necessary so that it does not exceed the
compile-time maximum mmap size set by the
<a href="../compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> compile-time option.
If either argument to this option is negative, then that argument is
changed to its compile-time default.</p>
<p><a name="sqliteconfigwin32heapsize"></a>
<dt>SQLITE_CONFIG_WIN32_HEAPSIZE
<dd>The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
compiled for Windows with the <a href="../compile.html#win32_malloc">SQLITE_WIN32_MALLOC</a> pre-processor macro
defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
that specifies the maximum size of the created heap.</p>
<p><a name="sqliteconfigpcachehdrsz"></a>
<dt>SQLITE_CONFIG_PCACHE_HDRSZ
<dd>The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
is a pointer to an integer and writes into that integer the number of extra
bytes per page required for each page in <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
The amount of extra space required can change depending on the compiler,
target platform, and SQLite version.</p>
<p><a name="sqliteconfigpmasz"></a>
<dt>SQLITE_CONFIG_PMASZ
<dd>The SQLITE_CONFIG_PMASZ option takes a single parameter which
is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
sorter to that integer. The default minimum PMA Size is set by the
<a href="../compile.html#sorter_pmasz">SQLITE_SORTER_PMASZ</a> compile-time option. New threads are launched
to help with sort operations when multithreaded sorting
is enabled (using the <a href="../pragma.html#pragma_threads">PRAGMA threads</a> command) and the amount of content
to be sorted exceeds the page size times the minimum of the
<a href="../pragma.html#pragma_cache_size">PRAGMA cache_size</a> setting and this value.</p>
<p><a name="sqliteconfigstmtjrnlspill"></a>
<dt>SQLITE_CONFIG_STMTJRNL_SPILL
<dd>The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
becomes the <a href="../tempfiles.html#stmtjrnl">statement journal</a> spill-to-disk threshold.
<a href="../tempfiles.html#stmtjrnl">Statement journals</a> are held in memory until their size (in bytes)
exceeds this threshold, at which point they are written to disk.
Or if the threshold is -1, statement journals are always held
exclusively in memory.
Since many statement journals never become large, setting the spill
threshold to a value such as 64KiB can greatly reduce the amount of
I/O required to support statement rollback.
The default value for this setting is controlled by the
<a href="../compile.html#stmtjrnl_spill">SQLITE_STMTJRNL_SPILL</a> compile-time option.</p>
<p><a name="sqliteconfigsorterrefsize"></a>
<dt>SQLITE_CONFIG_SORTERREF_SIZE
<dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
of type (int) - the new value of the sorter-reference size threshold.
Usually, when SQLite uses an external sort to order records according
to an ORDER BY clause, all fields required by the caller are present in the
sorted records. However, if SQLite determines based on the declared type
of a table column that its values are likely to be very large - larger
than the configured sorter-reference size threshold - then a reference
is stored in each sorted record and the required column values loaded
from the database as records are returned in sorted order. The default
value for this option is to never use this optimization. Specifying a
negative value for this option restores the default behavior.
This option is only available if SQLite is compiled with the
<a href="../compile.html#enable_sorter_references">SQLITE_ENABLE_SORTER_REFERENCES</a> compile-time option.</p>
<p><a name="sqliteconfigmemdbmaxsize"></a>
<dt>SQLITE_CONFIG_MEMDB_MAXSIZE
<dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
<a href="../c3ref/int64.html">sqlite3_int64</a> parameter which is the default maximum size for an in-memory
database created using <a href="../c3ref/deserialize.html">sqlite3_deserialize()</a>. This default maximum
size can be adjusted up or down for individual databases using the
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> <a href="../c3ref/file_control.html">file-control</a>. If this
configuration setting is never used, then the default maximum is determined
by the <a href="../compile.html#memdb_default_maxsize">SQLITE_MEMDB_DEFAULT_MAXSIZE</a> compile-time option. If that
compile-time option is not set, then the default maximum is 1073741824.
</dl>
</p><p>See also lists of
<a href="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|