Debian Codegraph @

www/c3ref/c_config_covering_index_scan.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>Configuration Options</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 <!-- 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_ROWID_IN_VIEW 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} -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Configuration Options</h2>
122 </div>
123 <blockquote><pre>
124 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
125 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
126 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
127 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
128 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
129 #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
130 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
131 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
132 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
133 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
134 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
135 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
136 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
137 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
138 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
139 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
140 #define SQLITE_CONFIG_URI 17 /* int */
141 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
142 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
143 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
144 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
145 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
146 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
147 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
148 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
149 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
150 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
151 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
152 #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
153 #define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
154 </pre></blockquote>
155 <p>
156 These constants are the available integer configuration options that
157 can be passed as the first argument to the <a href="../c3ref/config.html">sqlite3_config()</a> interface.</p>
158
159 <p>Most of the configuration options for sqlite3_config()
160 will only work if invoked prior to <a href="../c3ref/initialize.html">sqlite3_initialize()</a> or after
161 <a href="../c3ref/initialize.html">sqlite3_shutdown()</a>. The few exceptions to this rule are called
162 "anytime configuration options".
163 Calling <a href="../c3ref/config.html">sqlite3_config()</a> with a first argument that is not an
164 anytime configuration option in between calls to <a href="../c3ref/initialize.html">sqlite3_initialize()</a> and
165 <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> is a no-op that returns SQLITE_MISUSE.</p>
166
167 <p>The set of anytime configuration options can change (by insertions
168 and/or deletions) from one release of SQLite to the next.
169 As of SQLite version 3.42.0, the complete set of anytime configuration
170 options is:
171 <ul>
172 <li> SQLITE_CONFIG_LOG
173 <li> SQLITE_CONFIG_PCACHE_HDRSZ
174 </ul></p>
175
176 <p>New configuration options may be added in future releases of SQLite.
177 Existing configuration options might be discontinued. Applications
178 should check the return code from <a href="../c3ref/config.html">sqlite3_config()</a> to make sure that
179 the call worked. The <a href="../c3ref/config.html">sqlite3_config()</a> interface will return a
180 non-zero <a href="../rescode.html">error code</a> if a discontinued or unsupported configuration option
181 is invoked.</p>
182
183 <p><dl>
184 <a name="sqliteconfigsinglethread"></a>
185 <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
186 <dd>There are no arguments to this option. This option sets the
187 <a href="../threadsafe.html">threading mode</a> to Single-thread. In other words, it disables
188 all mutexing and puts SQLite into a mode where it can only be used
189 by a single thread. 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 change the <a href="../threadsafe.html">threading mode</a> from its default
192 value of Single-thread and so <a href="../c3ref/config.html">sqlite3_config()</a> will return
193 <a href="../rescode.html#error">SQLITE_ERROR</a> if called with the SQLITE_CONFIG_SINGLETHREAD
194 configuration option.</dd></p>
195
196 <p><a name="sqliteconfigmultithread"></a>
197 <dt>SQLITE_CONFIG_MULTITHREAD</dt>
198 <dd>There are no arguments to this option. This option sets the
199 <a href="../threadsafe.html">threading mode</a> to Multi-thread. In other words, it disables
200 mutexing on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
201 The application is responsible for serializing access to
202 <a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a>. But other mutexes
203 are enabled so that SQLite will be safe to use in a multi-threaded
204 environment as long as no two threads attempt to use the same
205 <a href="../c3ref/sqlite3.html">database connection</a> at the same time. If SQLite is compiled with
206 the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
207 it is not possible to set the Multi-thread <a href="../threadsafe.html">threading mode</a> and
208 <a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../rescode.html#error">SQLITE_ERROR</a> if called with the
209 SQLITE_CONFIG_MULTITHREAD configuration option.</dd></p>
210
211 <p><a name="sqliteconfigserialized"></a>
212 <dt>SQLITE_CONFIG_SERIALIZED</dt>
213 <dd>There are no arguments to this option. This option sets the
214 <a href="../threadsafe.html">threading mode</a> to Serialized. In other words, this option enables
215 all mutexes including the recursive
216 mutexes on <a href="../c3ref/sqlite3.html">database connection</a> and <a href="../c3ref/stmt.html">prepared statement</a> objects.
217 In this mode (which is the default when SQLite is compiled with
218 <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=1</a>) the SQLite library will itself serialize access
219 to <a href="../c3ref/sqlite3.html">database connections</a> and <a href="../c3ref/stmt.html">prepared statements</a> so that the
220 application is free to use the same <a href="../c3ref/sqlite3.html">database connection</a> or the
221 same <a href="../c3ref/stmt.html">prepared statement</a> in different threads at the same time.
222 If SQLite is compiled with
223 the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
224 it is not possible to set the Serialized <a href="../threadsafe.html">threading mode</a> and
225 <a href="../c3ref/config.html">sqlite3_config()</a> will return <a href="../rescode.html#error">SQLITE_ERROR</a> if called with the
226 SQLITE_CONFIG_SERIALIZED configuration option.</dd></p>
227
228 <p><a name="sqliteconfigmalloc"></a>
229 <dt>SQLITE_CONFIG_MALLOC</dt>
230 <dd> The SQLITE_CONFIG_MALLOC option takes a single argument which is
231 a pointer to an instance of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure.
232 The argument specifies
233 alternative low-level memory allocation routines to be used in place of
234 the memory allocation routines built into SQLite. SQLite makes
235 its own private copy of the content of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure
236 before the <a href="../c3ref/config.html">sqlite3_config()</a> call returns.</dd></p>
237
238 <p><a name="sqliteconfiggetmalloc"></a>
239 <dt>SQLITE_CONFIG_GETMALLOC</dt>
240 <dd> The SQLITE_CONFIG_GETMALLOC option takes a single argument which
241 is a pointer to an instance of the <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a> structure.
242 The <a href="../c3ref/mem_methods.html">sqlite3_mem_methods</a>
243 structure is filled with the currently defined memory allocation routines.
244 This option can be used to overload the default memory allocation
245 routines with a wrapper that simulates memory allocation failure or
246 tracks memory usage, for example. </dd></p>
247
248 <p><a name="sqliteconfigsmallmalloc"></a>
249 <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
250 <dd> The SQLITE_CONFIG_SMALL_MALLOC option takes a single argument of
251 type int, interpreted as a boolean, which if true provides a hint to
252 SQLite that it should avoid large memory allocations if possible.
253 SQLite will run faster if it is free to make large memory allocations,
254 but some applications might prefer to run slower in exchange for
255 guarantees about memory fragmentation that are possible if large
256 allocations are avoided. This hint is normally off.
257 </dd></p>
258
259 <p><a name="sqliteconfigmemstatus"></a>
260 <dt>SQLITE_CONFIG_MEMSTATUS</dt>
261 <dd> The SQLITE_CONFIG_MEMSTATUS option takes a single argument of type int,
262 interpreted as a boolean, which enables or disables the collection of
263 memory allocation statistics. When memory allocation statistics are
264 disabled, the following SQLite interfaces become non-operational:
265 <ul>
266 <li> <a href="../c3ref/hard_heap_limit64.html">sqlite3_hard_heap_limit64()</a>
267 <li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_used()</a>
268 <li> <a href="../c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>
269 <li> <a href="../c3ref/hard_heap_limit64.html">sqlite3_soft_heap_limit64()</a>
270 <li> <a href="../c3ref/status.html">sqlite3_status64()</a>
271 </ul>
272 Memory allocation statistics are enabled by default unless SQLite is
273 compiled with <a href="../compile.html#default_memstatus">SQLITE_DEFAULT_MEMSTATUS</a>=0 in which case memory
274 allocation statistics are disabled by default.
275 </dd></p>
276
277 <p><a name="sqliteconfigscratch"></a>
278 <dt>SQLITE_CONFIG_SCRATCH</dt>
279 <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
280 </dd></p>
281
282 <p><a name="sqliteconfigpagecache"></a>
283 <dt>SQLITE_CONFIG_PAGECACHE</dt>
284 <dd> The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
285 that SQLite can use for the database page cache with the default page
286 cache implementation.
287 This configuration option is a no-op if an application-defined page
288 cache implementation is loaded using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>.
289 There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
290 8-byte aligned memory (pMem), the size of each page cache line (sz),
291 and the number of cache lines (N).
292 The sz argument should be the size of the largest database page
293 (a power of two between 512 and 65536) plus some extra bytes for each
294 page header. The number of extra bytes needed by the page header
295 can be determined using <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpcachehdrsz">SQLITE_CONFIG_PCACHE_HDRSZ</a>.
296 It is harmless, apart from the wasted memory,
297 for the sz parameter to be larger than necessary. The pMem
298 argument must be either a NULL pointer or a pointer to an 8-byte
299 aligned block of memory of at least sz*N bytes, otherwise
300 subsequent behavior is undefined.
301 When pMem is not NULL, SQLite will strive to use the memory provided
302 to satisfy page cache needs, falling back to <a href="../c3ref/free.html">sqlite3_malloc()</a> if
303 a page cache line is larger than sz bytes or if all of the pMem buffer
304 is exhausted.
305 If pMem is NULL and N is non-zero, then each database connection
306 does an initial bulk allocation for page cache memory
307 from <a href="../c3ref/free.html">sqlite3_malloc()</a> sufficient for N cache lines if N is positive or
308 of -1024*N bytes if N is negative. If additional
309 page cache memory is needed beyond what is provided by the initial
310 allocation, then SQLite goes to <a href="../c3ref/free.html">sqlite3_malloc()</a> separately for each
311 additional cache line. </dd></p>
312
313 <p><a name="sqliteconfigheap"></a>
314 <dt>SQLITE_CONFIG_HEAP</dt>
315 <dd> The SQLITE_CONFIG_HEAP option specifies a static memory buffer
316 that SQLite will use for all of its dynamic memory allocation needs
317 beyond those provided for by <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
318 The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
319 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
320 <a href="../rescode.html#error">SQLITE_ERROR</a> if invoked otherwise.
321 There are three arguments to SQLITE_CONFIG_HEAP:
322 An 8-byte aligned pointer to the memory,
323 the number of bytes in the memory buffer, and the minimum allocation size.
324 If the first pointer (the memory pointer) is NULL, then SQLite reverts
325 to using its default memory allocator (the system malloc() implementation),
326 undoing any prior invocation of <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>. If the
327 memory pointer is not NULL then the alternative memory
328 allocator is engaged to handle all of SQLites memory allocation needs.
329 The first pointer (the memory pointer) must be aligned to an 8-byte
330 boundary or subsequent behavior of SQLite will be undefined.
331 The minimum allocation size is capped at 2**12. Reasonable values
332 for the minimum allocation size are 2**5 through 2**8.</dd></p>
333
334 <p><a name="sqliteconfigmutex"></a>
335 <dt>SQLITE_CONFIG_MUTEX</dt>
336 <dd> The SQLITE_CONFIG_MUTEX option takes a single argument which is a
337 pointer to an instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure.
338 The argument specifies alternative low-level mutex routines to be used
339 in place of the mutex routines built into SQLite. SQLite makes a copy of
340 the content of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure before the call to
341 <a href="../c3ref/config.html">sqlite3_config()</a> returns. If SQLite is compiled with
342 the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
343 the entire mutexing subsystem is omitted from the build and hence calls to
344 <a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_MUTEX configuration option will
345 return <a href="../rescode.html#error">SQLITE_ERROR</a>.</dd></p>
346
347 <p><a name="sqliteconfiggetmutex"></a>
348 <dt>SQLITE_CONFIG_GETMUTEX</dt>
349 <dd> The SQLITE_CONFIG_GETMUTEX option takes a single argument which
350 is a pointer to an instance of the <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a> structure. The
351 <a href="../c3ref/mutex_methods.html">sqlite3_mutex_methods</a>
352 structure is filled with the currently defined mutex routines.
353 This option can be used to overload the default mutex allocation
354 routines with a wrapper used to track mutex usage for performance
355 profiling or testing, for example. If SQLite is compiled with
356 the <a href="../compile.html#threadsafe">SQLITE_THREADSAFE=0</a> compile-time option then
357 the entire mutexing subsystem is omitted from the build and hence calls to
358 <a href="../c3ref/config.html">sqlite3_config()</a> with the SQLITE_CONFIG_GETMUTEX configuration option will
359 return <a href="../rescode.html#error">SQLITE_ERROR</a>.</dd></p>
360
361 <p><a name="sqliteconfiglookaside"></a>
362 <dt>SQLITE_CONFIG_LOOKASIDE</dt>
363 <dd> The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
364 the default size of <a href="../malloc.html#lookaside">lookaside memory</a> on each <a href="../c3ref/sqlite3.html">database connection</a>.
365 The first argument is the
366 size of each lookaside buffer slot ("sz") and the second is the number of
367 slots allocated to each database connection ("cnt").
368 SQLITE_CONFIG_LOOKASIDE sets the <i>default</i> lookaside size.
369 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
370 be used to change the lookaside configuration on individual connections.
371 The <a href="../compile.html#default_lookaside">-DSQLITE_DEFAULT_LOOKASIDE</a> option can be used to change the
372 default lookaside configuration at compile-time.
373 </dd></p>
374
375 <p><a name="sqliteconfigpcache2"></a>
376 <dt>SQLITE_CONFIG_PCACHE2</dt>
377 <dd> The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
378 a pointer to an <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. This object specifies
379 the interface to a custom page cache implementation.
380 SQLite makes a copy of the <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object.</dd></p>
381
382 <p><a name="sqliteconfiggetpcache2"></a>
383 <dt>SQLITE_CONFIG_GETPCACHE2</dt>
384 <dd> The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
385 is a pointer to an <a href="../c3ref/pcache_methods2.html">sqlite3_pcache_methods2</a> object. SQLite copies off
386 the current page cache implementation into that object. </dd></p>
387
388 <p><a name="sqliteconfiglog"></a>
389 <dt>SQLITE_CONFIG_LOG</dt>
390 <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
391 global <a href="../errlog.html">error log</a>.
392 (The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
393 function with a call signature of void(*)(void*,int,const char*),
394 and a pointer to void. If the function pointer is not NULL, it is
395 invoked by <a href="../c3ref/log.html">sqlite3_log()</a> to process each logging event. If the
396 function pointer is NULL, the <a href="../c3ref/log.html">sqlite3_log()</a> interface becomes a no-op.
397 The void pointer that is the second argument to SQLITE_CONFIG_LOG is
398 passed through as the first parameter to the application-defined logger
399 function whenever that function is invoked. The second parameter to
400 the logger function is a copy of the first parameter to the corresponding
401 <a href="../c3ref/log.html">sqlite3_log()</a> call and is intended to be a <a href="../rescode.html">result code</a> or an
402 <a href="../rescode.html#extrc">extended result code</a>. The third parameter passed to the logger is
403 a log message after formatting via <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a>.
404 The SQLite logging interface is not reentrant; the logger function
405 supplied by the application must not invoke any SQLite interface.
406 In a multi-threaded application, the application-defined logger
407 function must be threadsafe. </dd></p>
408
409 <p><a name="sqliteconfiguri"></a>
410 <dt>SQLITE_CONFIG_URI
411 <dd>The SQLITE_CONFIG_URI option takes a single argument of type int.
412 If non-zero, then URI handling is globally enabled. If the parameter is zero,
413 then URI handling is globally disabled. If URI handling is globally
414 enabled, all filenames passed to <a href="../c3ref/open.html">sqlite3_open()</a>, <a href="../c3ref/open.html">sqlite3_open_v2()</a>,
415 <a href="../c3ref/open.html">sqlite3_open16()</a> or
416 specified as part of <a href="../lang_attach.html">ATTACH</a> commands are interpreted as URIs, regardless
417 of whether or not the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is set when the database
418 connection is opened. If it is globally disabled, filenames are
419 only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
420 database connection is opened. By default, URI handling is globally
421 disabled. The default value may be changed by compiling with the
422 <a href="../compile.html#use_uri">SQLITE_USE_URI</a> symbol defined.</p>
423
424 <p><a name="sqliteconfigcoveringindexscan"></a>
425 <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
426 <dd>The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
427 argument which is interpreted as a boolean in order to enable or disable
428 the use of covering indices for full table scans in the query optimizer.
429 The default setting is determined
430 by the <a href="../compile.html#allow_covering_index_scan">SQLITE_ALLOW_COVERING_INDEX_SCAN</a> compile-time option, or is "on"
431 if that compile-time option is omitted.
432 The ability to disable the use of covering indices for full table scans
433 is because some incorrectly coded legacy applications might malfunction
434 when the optimization is enabled. Providing the ability to
435 disable the optimization allows the older, buggy application code to work
436 without change even with newer versions of SQLite.</p>
437
438 <p><a name="sqliteconfigpcache"></a>
439 <a name="sqliteconfiggetpcache"></a>
440
441 <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
442 <dd> These options are obsolete and should not be used by new code.
443 They are retained for backwards compatibility but are now no-ops.
444 </dd></p>
445
446 <p><a name="sqliteconfigsqllog"></a>
447
448 <dt>SQLITE_CONFIG_SQLLOG
449 <dd>This option is only available if sqlite is compiled with the
450 <a href="../compile.html#enable_sqllog">SQLITE_ENABLE_SQLLOG</a> pre-processor macro defined. The first argument should
451 be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
452 The second should be of type (void*). The callback is invoked by the library
453 in three separate circumstances, identified by the value passed as the
454 fourth parameter. If the fourth parameter is 0, then the database connection
455 passed as the second argument has just been opened. The third argument
456 points to a buffer containing the name of the main database file. If the
457 fourth parameter is 1, then the SQL statement that the third parameter
458 points to has just been executed. Or, if the fourth parameter is 2, then
459 the connection being passed as the second parameter is being closed. The
460 third parameter is passed NULL In this case. An example of using this
461 configuration option can be seen in the "test_sqllog.c" source file in
462 the canonical SQLite source tree.</dd></p>
463
464 <p><a name="sqliteconfigmmapsize"></a>
465
466 <dt>SQLITE_CONFIG_MMAP_SIZE
467 <dd>SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
468 that are the default mmap size limit (the default setting for
469 <a href="../pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>) and the maximum allowed mmap size limit.
470 The default setting can be overridden by each database connection using
471 either the <a href="../pragma.html#pragma_mmap_size">PRAGMA mmap_size</a> command, or by using the
472 <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control. The maximum allowed mmap size
473 will be silently truncated if necessary so that it does not exceed the
474 compile-time maximum mmap size set by the
475 <a href="../compile.html#max_mmap_size">SQLITE_MAX_MMAP_SIZE</a> compile-time option.
476 If either argument to this option is negative, then that argument is
477 changed to its compile-time default.</p>
478
479 <p><a name="sqliteconfigwin32heapsize"></a>
480
481 <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
482 <dd>The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
483 compiled for Windows with the <a href="../compile.html#win32_malloc">SQLITE_WIN32_MALLOC</a> pre-processor macro
484 defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
485 that specifies the maximum size of the created heap.</p>
486
487 <p><a name="sqliteconfigpcachehdrsz"></a>
488
489 <dt>SQLITE_CONFIG_PCACHE_HDRSZ
490 <dd>The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
491 is a pointer to an integer and writes into that integer the number of extra
492 bytes per page required for each page in <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>.
493 The amount of extra space required can change depending on the compiler,
494 target platform, and SQLite version.</p>
495
496 <p><a name="sqliteconfigpmasz"></a>
497
498 <dt>SQLITE_CONFIG_PMASZ
499 <dd>The SQLITE_CONFIG_PMASZ option takes a single parameter which
500 is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
501 sorter to that integer. The default minimum PMA Size is set by the
502 <a href="../compile.html#sorter_pmasz">SQLITE_SORTER_PMASZ</a> compile-time option. New threads are launched
503 to help with sort operations when multithreaded sorting
504 is enabled (using the <a href="../pragma.html#pragma_threads">PRAGMA threads</a> command) and the amount of content
505 to be sorted exceeds the page size times the minimum of the
506 <a href="../pragma.html#pragma_cache_size">PRAGMA cache_size</a> setting and this value.</p>
507
508 <p><a name="sqliteconfigstmtjrnlspill"></a>
509
510 <dt>SQLITE_CONFIG_STMTJRNL_SPILL
511 <dd>The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
512 becomes the <a href="../tempfiles.html#stmtjrnl">statement journal</a> spill-to-disk threshold.
513 <a href="../tempfiles.html#stmtjrnl">Statement journals</a> are held in memory until their size (in bytes)
514 exceeds this threshold, at which point they are written to disk.
515 Or if the threshold is -1, statement journals are always held
516 exclusively in memory.
517 Since many statement journals never become large, setting the spill
518 threshold to a value such as 64KiB can greatly reduce the amount of
519 I/O required to support statement rollback.
520 The default value for this setting is controlled by the
521 <a href="../compile.html#stmtjrnl_spill">SQLITE_STMTJRNL_SPILL</a> compile-time option.</p>
522
523 <p><a name="sqliteconfigsorterrefsize"></a>
524
525 <dt>SQLITE_CONFIG_SORTERREF_SIZE
526 <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
527 of type (int) - the new value of the sorter-reference size threshold.
528 Usually, when SQLite uses an external sort to order records according
529 to an ORDER BY clause, all fields required by the caller are present in the
530 sorted records. However, if SQLite determines based on the declared type
531 of a table column that its values are likely to be very large - larger
532 than the configured sorter-reference size threshold - then a reference
533 is stored in each sorted record and the required column values loaded
534 from the database as records are returned in sorted order. The default
535 value for this option is to never use this optimization. Specifying a
536 negative value for this option restores the default behavior.
537 This option is only available if SQLite is compiled with the
538 <a href="../compile.html#enable_sorter_references">SQLITE_ENABLE_SORTER_REFERENCES</a> compile-time option.</p>
539
540 <p><a name="sqliteconfigmemdbmaxsize"></a>
541
542 <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
543 <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
544 <a href="../c3ref/int64.html">sqlite3_int64</a> parameter which is the default maximum size for an in-memory
545 database created using <a href="../c3ref/deserialize.html">sqlite3_deserialize()</a>. This default maximum
546 size can be adjusted up or down for individual databases using the
547 <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
548 configuration setting is never used, then the default maximum is determined
549 by the <a href="../compile.html#memdb_default_maxsize">SQLITE_MEMDB_DEFAULT_MAXSIZE</a> compile-time option. If that
550 compile-time option is not set, then the default maximum is 1073741824.</p>
551
552 <p><a name="sqliteconfigrowidinview"></a>
553
554 <dt>SQLITE_CONFIG_ROWID_IN_VIEW
555 <dd>The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability
556 for VIEWs to have a ROWID. The capability can only be enabled if SQLite is
557 compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
558 defaults to on. This configuration option queries the current setting or
559 changes the setting to off or on. The argument is a pointer to an integer.
560 If that integer initially holds a value of 1, then the ability for VIEWs to
561 have ROWIDs is activated. If the integer initially holds zero, then the
562 ability is deactivated. Any other initial value for the integer leaves the
563 setting unchanged. After changes, if any, the integer is written with
564 a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off. If SQLite
565 is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
566 recommended case) then the integer is always filled with zero, regardless
567 if its initial value.
568 </dl>
569 </p><p>See also lists of
570 <a href="../c3ref/objlist.html">Objects</a>,
571 <a href="../c3ref/constlist.html">Constants</a>, and
572 <a href="../c3ref/funclist.html">Functions</a>.</p>
573