| 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 |
|