1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Configuration Options</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
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...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Configuration Options</h2><blockquote><pre>#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
121
#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
122
#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
123
#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
124
#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
125
#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
126
#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
127
#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
128
#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
129
#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
130
#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
131
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
132
#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
133
#define SQLITE_CONFIG_PCACHE 14 /* no-op */
134
#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
135
#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
136
#define SQLITE_CONFIG_URI 17 /* int */
137
#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
138
#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
139
</pre></blockquote><p>
140
These constants are the available integer configuration options that
141
can be passed as the first argument to the <a href="../c3ref/config.html">sqlite3_config()</a> interface.</p>
143
<p>New configuration options may be added in future releases of SQLite.
144
Existing configuration options might be discontinued. Applications
145
should check the return code from <a href="../c3ref/config.html">sqlite3_config()</a> to make sure that
146
the call worked. The <a href="../c3ref/config.html">sqlite3_config()</a> interface will return a
147
non-zero <a href="../c3ref/c_abort.html">error code</a> if a discontinued or unsupported configuration option
151
<a name="sqliteconfigsinglethread"></a>
152
<dt>SQLITE_CONFIG_SINGLETHREAD</dt>
153
<dd>There are no arguments to this option. This option sets the
154
<a href="../threadsafe.html">threading mode</a> to Single-thread. In other words, it disables
155
all mutexing and puts SQLite into a mode where it can only be used
156
by a single thread. If SQLite is compiled with
157
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
158
it is not possible to change the <a href="../threadsafe.html">threading mode</a> from its default
159
value of Single-thread and so <a href="../c3ref/config.html">sqlite3_config()</a> will return
160
<a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD
161
configuration option.</dd></p>
163
<p><a name="sqliteconfigmultithread"></a>
164
<dt>SQLITE_CONFIG_MULTITHREAD</dt>
165
<dd>There are no arguments to this option. This option sets the
166
<a href="../threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables
167
mutexing on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
168
The application is responsible for serializing access to
169
<a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a>. But other mutexes
170
are enabled so that SQLite will be safe to use in a multi-threaded
171
environment as long as no two threads attempt to use the same
172
<a href="../c3ref/sqlite3.html">database connection</a> at the same time. If SQLite is compiled with
173
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
174
it is not possible to set the Multi-thread <a href="../threadsafe.html">threading mode</a> and
175
<a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if called with the
176
SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p>
178
<p><a name="sqliteconfigserialized"></a>
179
<dt>SQLITE_CONFIG_SERIALIZED</dt>
180
<dd>There are no arguments to this option. This option sets the
181
<a href="../threadsafe.html">threading mode</a> to Serialized. In other words, this option enables
182
all mutexes including the recursive
183
mutexes on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
184
In this mode (which is the default when SQLite is compiled with
185
<a href="../compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access
186
to <a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a> so that the
187
application is free to use the same <a href="../c3ref/sqlite3.html">database connection</a> or the
188
same <a href="../c3ref/stmt.html">prepared statement</a> in different threads at the same time.
189
If SQLite is compiled with
190
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
191
it is not possible to set the Serialized <a href="../threadsafe.html">threading mode</a> and
192
<a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if called with the
193
SQLITE_CONFIG_SERIALIZED configuration option.</dd></p>
195
<p><a name="sqliteconfigmalloc"></a>
196
<dt>SQLITE_CONFIG_MALLOC</dt>
197
<dd> This option takes a single argument which is a pointer to an
198
instance of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure. The argument specifies
199
alternative low-level memory allocation routines to be used in place of
200
the memory allocation routines built into SQLite. SQLite makes
201
its own private copy of the content of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure
202
before the <a href="../c3ref/config.html">sqlite3_config()</a> call returns.</dd></p>
204
<p><a name="sqliteconfiggetmalloc"></a>
205
<dt>SQLITE_CONFIG_GETMALLOC</dt>
206
<dd> This option takes a single argument which is a pointer to an
207
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>
208
structure is filled with the currently defined memory allocation routines.
209
This option can be used to overload the default memory allocation
210
routines with a wrapper that simulations memory allocation failure or
211
tracks memory usage, for example. </dd></p>
213
<p><a name="sqliteconfigmemstatus"></a>
214
<dt>SQLITE_CONFIG_MEMSTATUS</dt>
215
<dd> This option takes single argument of type int, interpreted as a
216
boolean, which enables or disables the collection of memory allocation
217
statistics. When memory allocation statistics are disabled, the
218
following SQLite interfaces become non-operational:
220
<li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_used()</a>
221
<li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>
222
<li> <a href="../c3ref/soft_heap_limit64.html">sqlite3_soft_heap_limit64()</a>
223
<li> <a href="../c3ref/status.html">sqlite3_status()</a>
225
Memory allocation statistics are enabled by default unless SQLite is
226
compiled with <a href="../compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory
227
allocation statistics are disabled by default.
230
<p><a name="sqliteconfigscratch"></a>
231
<dt>SQLITE_CONFIG_SCRATCH</dt>
232
<dd> This option specifies a static memory buffer that SQLite can use for
233
scratch memory. There are three arguments: A pointer an 8-byte
234
aligned memory buffer from which the scratch allocations will be
235
drawn, the size of each scratch allocation (sz),
236
and the maximum number of scratch allocations (N). The sz
237
argument must be a multiple of 16.
238
The first argument must be a pointer to an 8-byte aligned buffer
239
of at least sz*N bytes of memory.
240
SQLite will use no more than two scratch buffers per thread. So
241
N should be set to twice the expected maximum number of threads.
242
SQLite will never require a scratch buffer that is more than 6
243
times the database page size. If SQLite needs needs additional
244
scratch memory beyond what is provided by this configuration option, then
245
<a href="../c3ref/free.html">sqlite3_malloc()</a> will be used to obtain the memory needed.</dd></p>
247
<p><a name="sqliteconfigpagecache"></a>
248
<dt>SQLITE_CONFIG_PAGECACHE</dt>
249
<dd> This option specifies a static memory buffer that SQLite can use for
250
the database page cache with the default page cache implementation.
251
This configuration should not be used if an application-define page
252
cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
253
There are three arguments to this option: A pointer to 8-byte aligned
254
memory, the size of each page buffer (sz), and the number of pages (N).
255
The sz argument should be the size of the largest database page
256
(a power of two between 512 and 32768) plus a little extra for each
257
page header. The page header size is 20 to 40 bytes depending on
258
the host architecture. It is harmless, apart from the wasted memory,
259
to make sz a little too large. The first
260
argument should point to an allocation of at least sz*N bytes of memory.
261
SQLite will use the memory provided by the first argument to satisfy its
262
memory needs for the first N pages that it adds to cache. If additional
263
page cache memory is needed beyond what is provided by this option, then
264
SQLite goes to <a href="../c3ref/free.html">sqlite3_malloc()</a> for the additional storage space.
265
The pointer in the first argument must
266
be aligned to an 8-byte boundary or subsequent behavior of SQLite
267
will be undefined.</dd></p>
269
<p><a name="sqliteconfigheap"></a>
270
<dt>SQLITE_CONFIG_HEAP</dt>
271
<dd> This option specifies a static memory buffer that SQLite will use
272
for all of its dynamic memory allocation needs beyond those provided
273
for by <a href="../c3ref/c_config_getmalloc.html#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a> and <a href="../c3ref/c_config_getmalloc.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
274
There are three arguments: An 8-byte aligned pointer to the memory,
275
the number of bytes in the memory buffer, and the minimum allocation size.
276
If the first pointer (the memory pointer) is NULL, then SQLite reverts
277
to using its default memory allocator (the system malloc() implementation),
278
undoing any prior invocation of <a href="../c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the
279
memory pointer is not NULL and either <a href="../compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or
280
<a href="../compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> are defined, then the alternative memory
281
allocator is engaged to handle all of SQLites memory allocation needs.
282
The first pointer (the memory pointer) must be aligned to an 8-byte
283
boundary or subsequent behavior of SQLite will be undefined.
284
The minimum allocation size is capped at 2**12. Reasonable values
285
for the minimum allocation size are 2**5 through 2**8.</dd></p>
287
<p><a name="sqliteconfigmutex"></a>
288
<dt>SQLITE_CONFIG_MUTEX</dt>
289
<dd> This option takes a single argument which is a pointer to an
290
instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure. The argument specifies
291
alternative low-level mutex routines to be used in place
292
the mutex routines built into SQLite. SQLite makes a copy of the
293
content of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure before the call to
294
<a href="../c3ref/config.html">sqlite3_config()</a> returns. If SQLite is compiled with
295
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
296
the entire mutexing subsystem is omitted from the build and hence calls to
297
<a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will
298
return <a href="../c3ref/c_abort.html">SQLITE_ERROR</a>.</dd></p>
300
<p><a name="sqliteconfiggetmutex"></a>
301
<dt>SQLITE_CONFIG_GETMUTEX</dt>
302
<dd> This option takes a single argument which is a pointer to an
303
instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure. The
304
<a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a>
305
structure is filled with the currently defined mutex routines.
306
This option can be used to overload the default mutex allocation
307
routines with a wrapper used to track mutex usage for performance
308
profiling or testing, for example. If SQLite is compiled with
309
the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
310
the entire mutexing subsystem is omitted from the build and hence calls to
311
<a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will
312
return <a href="../c3ref/c_abort.html">SQLITE_ERROR</a>.</dd></p>
314
<p><a name="sqliteconfiglookaside"></a>
315
<dt>SQLITE_CONFIG_LOOKASIDE</dt>
316
<dd> This option takes two arguments that determine the default
317
memory allocation for the lookaside memory allocator on each
318
<a href="../c3ref/sqlite3.html">database connection</a>. The first argument is the
319
size of each lookaside buffer slot and the second is the number of
320
slots allocated to each database connection. This option sets the
321
<i>default</i> lookaside size. The <a href="../c3ref/c_dbconfig_enable_fkey.html">SQLITE_DBCONFIG_LOOKASIDE</a>
322
verb to <a href="../c3ref/db_config.html">sqlite3_db_config()</a> can be used to change the lookaside
323
configuration on individual connections. </dd></p>
325
<p><a name="sqliteconfigpcache2"></a>
326
<dt>SQLITE_CONFIG_PCACHE2</dt>
327
<dd> This option takes a single argument which is a pointer to
328
an <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. This object specifies the interface
329
to a custom page cache implementation. SQLite makes a copy of the
330
object and uses it for page cache memory allocations.</dd></p>
332
<p><a name="sqliteconfiggetpcache2"></a>
333
<dt>SQLITE_CONFIG_GETPCACHE2</dt>
334
<dd> This option takes a single argument which is a pointer to an
335
<a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. SQLite copies of the current
336
page cache implementation into that object. </dd></p>
338
<p><a name="sqliteconfiglog"></a>
339
<dt>SQLITE_CONFIG_LOG</dt>
340
<dd> The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
341
function with a call signature of void(*)(void*,int,const char*),
342
and a pointer to void. If the function pointer is not NULL, it is
343
invoked by <a href="../c3ref/log.html">sqlite3_log()</a> to process each logging event. If the
344
function pointer is NULL, the <a href="../c3ref/log.html">sqlite3_log()</a> interface becomes a no-op.
345
The void pointer that is the second argument to SQLITE_CONFIG_LOG is
346
passed through as the first parameter to the application-defined logger
347
function whenever that function is invoked. The second parameter to
348
the logger function is a copy of the first parameter to the corresponding
349
<a href="../c3ref/log.html">sqlite3_log()</a> call and is intended to be a <a href="../c3ref/c_abort.html">result code</a> or an
350
<a href="../c3ref/c_abort_rollback.html">extended result code</a>. The third parameter passed to the logger is
351
log message after formatting via <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a>.
352
The SQLite logging interface is not reentrant; the logger function
353
supplied by the application must not invoke any SQLite interface.
354
In a multi-threaded application, the application-defined logger
355
function must be threadsafe. </dd></p>
357
<p><a name="sqliteconfiguri"></a>
358
<dt>SQLITE_CONFIG_URI
359
<dd> This option takes a single argument of type int. If non-zero, then
360
URI handling is globally enabled. If the parameter is zero, then URI handling
361
is globally disabled. If URI handling is globally enabled, all filenames
362
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
363
specified as part of <a href="../lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless
364
of whether or not the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is set when the database
365
connection is opened. If it is globally disabled, filenames are
366
only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
367
database connection is opened. By default, URI handling is globally
368
disabled. The default value may be changed by compiling with the
369
<a href="../compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p>
371
<p><a name="sqliteconfigpcache"></a>
372
<a name="sqliteconfiggetpcache"></a>
374
<dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
375
<dd> These options are obsolete and should not be used by new code.
376
They are retained for backwards compatibility but are now no-ops.
378
</p><p>See also lists of
379
<a href="objlist.html">Objects</a>,
380
<a href="constlist.html">Constants</a>, and
381
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/c_config_getmalloc.html
