4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
9 ** May you share freely, never taking more than you give.
11 *************************************************************************
12 ** Main file for the SQLite library. The routines in this file
13 ** implement the programmer interface to the library. Routines in
14 ** other files are for internal use by SQLite and should not be
15 ** accessed by users of the library.
17 #include "sqliteInt.h"
19 #ifdef SQLITE_ENABLE_FTS3
22 #ifdef SQLITE_ENABLE_RTREE
25 #if defined(SQLITE_ENABLE_ICU) || defined(SQLITE_ENABLE_ICU_COLLATIONS)
26 # include "sqliteicu.h"
30 ** This is an extension initializer that is a no-op and always
31 ** succeeds, except that it fails if the fault-simulation is set
34 static int sqlite3TestExtInit(sqlite3
*db
){
36 return sqlite3FaultSim(500);
41 ** Forward declarations of external module initializer functions
42 ** for modules that need them.
44 #ifdef SQLITE_ENABLE_FTS1
45 int sqlite3Fts1Init(sqlite3
*);
47 #ifdef SQLITE_ENABLE_FTS2
48 int sqlite3Fts2Init(sqlite3
*);
50 #ifdef SQLITE_ENABLE_FTS5
51 int sqlite3Fts5Init(sqlite3
*);
53 #ifdef SQLITE_ENABLE_JSON1
54 int sqlite3Json1Init(sqlite3
*);
56 #ifdef SQLITE_ENABLE_STMTVTAB
57 int sqlite3StmtVtabInit(sqlite3
*);
61 ** An array of pointers to extension initializer functions for
62 ** built-in extensions.
64 static int (*const sqlite3BuiltinExtensions
[])(sqlite3
*) = {
65 #ifdef SQLITE_ENABLE_FTS1
68 #ifdef SQLITE_ENABLE_FTS2
71 #ifdef SQLITE_ENABLE_FTS3
74 #ifdef SQLITE_ENABLE_FTS5
77 #if defined(SQLITE_ENABLE_ICU) || defined(SQLITE_ENABLE_ICU_COLLATIONS)
80 #ifdef SQLITE_ENABLE_RTREE
83 #ifdef SQLITE_ENABLE_DBPAGE_VTAB
84 sqlite3DbpageRegister
,
86 #ifdef SQLITE_ENABLE_DBSTAT_VTAB
87 sqlite3DbstatRegister
,
90 #ifdef SQLITE_ENABLE_JSON1
93 #ifdef SQLITE_ENABLE_STMTVTAB
96 #ifdef SQLITE_ENABLE_BYTECODE_VTAB
97 sqlite3VdbeBytecodeVtabInit
,
101 #ifndef SQLITE_AMALGAMATION
102 /* IMPLEMENTATION-OF: R-46656-45156 The sqlite3_version[] string constant
103 ** contains the text of SQLITE_VERSION macro.
105 const char sqlite3_version
[] = SQLITE_VERSION
;
108 /* IMPLEMENTATION-OF: R-53536-42575 The sqlite3_libversion() function returns
109 ** a pointer to the to the sqlite3_version[] string constant.
111 const char *sqlite3_libversion(void){ return sqlite3_version
; }
113 /* IMPLEMENTATION-OF: R-25063-23286 The sqlite3_sourceid() function returns a
114 ** pointer to a string constant whose value is the same as the
115 ** SQLITE_SOURCE_ID C preprocessor macro. Except if SQLite is built using
116 ** an edited copy of the amalgamation, then the last four characters of
117 ** the hash might be different from SQLITE_SOURCE_ID.
119 const char *sqlite3_sourceid(void){ return SQLITE_SOURCE_ID
; }
121 /* IMPLEMENTATION-OF: R-35210-63508 The sqlite3_libversion_number() function
122 ** returns an integer equal to SQLITE_VERSION_NUMBER.
124 int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER
; }
126 /* IMPLEMENTATION-OF: R-20790-14025 The sqlite3_threadsafe() function returns
127 ** zero if and only if SQLite was compiled with mutexing code omitted due to
128 ** the SQLITE_THREADSAFE compile-time option being set to 0.
130 int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE
; }
133 ** When compiling the test fixture or with debugging enabled (on Win32),
134 ** this variable being set to non-zero will cause OSTRACE macros to emit
135 ** extra diagnostic information.
137 #ifdef SQLITE_HAVE_OS_TRACE
138 # ifndef SQLITE_DEBUG_OS_TRACE
139 # define SQLITE_DEBUG_OS_TRACE 0
141 int sqlite3OSTrace
= SQLITE_DEBUG_OS_TRACE
;
144 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
146 ** If the following function pointer is not NULL and if
147 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
148 ** I/O active are written using this function. These messages
149 ** are intended for debugging activity only.
151 SQLITE_API
void (SQLITE_CDECL
*sqlite3IoTrace
)(const char*, ...) = 0;
155 ** If the following global variable points to a string which is the
156 ** name of a directory, then that directory will be used to store
159 ** See also the "PRAGMA temp_store_directory" SQL command.
161 char *sqlite3_temp_directory
= 0;
164 ** If the following global variable points to a string which is the
165 ** name of a directory, then that directory will be used to store
166 ** all database files specified with a relative pathname.
168 ** See also the "PRAGMA data_store_directory" SQL command.
170 char *sqlite3_data_directory
= 0;
173 ** Initialize SQLite.
175 ** This routine must be called to initialize the memory allocation,
176 ** VFS, and mutex subsystems prior to doing any serious work with
177 ** SQLite. But as long as you do not compile with SQLITE_OMIT_AUTOINIT
178 ** this routine will be called automatically by key routines such as
181 ** This routine is a no-op except on its very first call for the process,
182 ** or for the first call after a call to sqlite3_shutdown.
184 ** The first thread to call this routine runs the initialization to
185 ** completion. If subsequent threads call this routine before the first
186 ** thread has finished the initialization process, then the subsequent
187 ** threads must block until the first thread finishes with the initialization.
189 ** The first thread might call this routine recursively. Recursive
190 ** calls to this routine should not block, of course. Otherwise the
191 ** initialization process would never complete.
193 ** Let X be the first thread to enter this routine. Let Y be some other
194 ** thread. Then while the initial invocation of this routine by X is
195 ** incomplete, it is required that:
197 ** * Calls to this routine from Y must block until the outer-most
198 ** call by X completes.
200 ** * Recursive calls to this routine from thread X return immediately
203 int sqlite3_initialize(void){
204 MUTEX_LOGIC( sqlite3_mutex
*pMainMtx
; ) /* The main static mutex */
205 int rc
; /* Result code */
206 #ifdef SQLITE_EXTRA_INIT
207 int bRunExtraInit
= 0; /* Extra initialization needed */
210 #ifdef SQLITE_OMIT_WSD
211 rc
= sqlite3_wsd_init(4096, 24);
217 /* If the following assert() fails on some obscure processor/compiler
218 ** combination, the work-around is to set the correct pointer
219 ** size at compile-time using -DSQLITE_PTRSIZE=n compile-time option */
220 assert( SQLITE_PTRSIZE
==sizeof(char*) );
222 /* If SQLite is already completely initialized, then this call
223 ** to sqlite3_initialize() should be a no-op. But the initialization
224 ** must be complete. So isInit must not be set until the very end
227 if( sqlite3GlobalConfig
.isInit
){
228 sqlite3MemoryBarrier();
232 /* Make sure the mutex subsystem is initialized. If unable to
233 ** initialize the mutex subsystem, return early with the error.
234 ** If the system is so sick that we are unable to allocate a mutex,
235 ** there is not much SQLite is going to be able to do.
237 ** The mutex subsystem must take care of serializing its own
240 rc
= sqlite3MutexInit();
243 /* Initialize the malloc() system and the recursive pInitMutex mutex.
244 ** This operation is protected by the STATIC_MAIN mutex. Note that
245 ** MutexAlloc() is called for a static mutex prior to initializing the
246 ** malloc subsystem - this implies that the allocation of a static
247 ** mutex must not require support from the malloc subsystem.
249 MUTEX_LOGIC( pMainMtx
= sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MAIN
); )
250 sqlite3_mutex_enter(pMainMtx
);
251 sqlite3GlobalConfig
.isMutexInit
= 1;
252 if( !sqlite3GlobalConfig
.isMallocInit
){
253 rc
= sqlite3MallocInit();
256 sqlite3GlobalConfig
.isMallocInit
= 1;
257 if( !sqlite3GlobalConfig
.pInitMutex
){
258 sqlite3GlobalConfig
.pInitMutex
=
259 sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE
);
260 if( sqlite3GlobalConfig
.bCoreMutex
&& !sqlite3GlobalConfig
.pInitMutex
){
261 rc
= SQLITE_NOMEM_BKPT
;
266 sqlite3GlobalConfig
.nRefInitMutex
++;
268 sqlite3_mutex_leave(pMainMtx
);
270 /* If rc is not SQLITE_OK at this point, then either the malloc
271 ** subsystem could not be initialized or the system failed to allocate
272 ** the pInitMutex mutex. Return an error in either case. */
277 /* Do the rest of the initialization under the recursive mutex so
278 ** that we will be able to handle recursive calls into
279 ** sqlite3_initialize(). The recursive calls normally come through
280 ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other
281 ** recursive calls might also be possible.
283 ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls
284 ** to the xInit method, so the xInit method need not be threadsafe.
286 ** The following mutex is what serializes access to the appdef pcache xInit
287 ** methods. The sqlite3_pcache_methods.xInit() all is embedded in the
288 ** call to sqlite3PcacheInitialize().
290 sqlite3_mutex_enter(sqlite3GlobalConfig
.pInitMutex
);
291 if( sqlite3GlobalConfig
.isInit
==0 && sqlite3GlobalConfig
.inProgress
==0 ){
292 sqlite3GlobalConfig
.inProgress
= 1;
293 #ifdef SQLITE_ENABLE_SQLLOG
295 extern void sqlite3_init_sqllog(void);
296 sqlite3_init_sqllog();
299 memset(&sqlite3BuiltinFunctions
, 0, sizeof(sqlite3BuiltinFunctions
));
300 sqlite3RegisterBuiltinFunctions();
301 if( sqlite3GlobalConfig
.isPCacheInit
==0 ){
302 rc
= sqlite3PcacheInitialize();
305 sqlite3GlobalConfig
.isPCacheInit
= 1;
306 rc
= sqlite3OsInit();
308 #ifndef SQLITE_OMIT_DESERIALIZE
310 rc
= sqlite3MemdbInit();
314 sqlite3PCacheBufferSetup( sqlite3GlobalConfig
.pPage
,
315 sqlite3GlobalConfig
.szPage
, sqlite3GlobalConfig
.nPage
);
316 sqlite3MemoryBarrier();
317 sqlite3GlobalConfig
.isInit
= 1;
318 #ifdef SQLITE_EXTRA_INIT
322 sqlite3GlobalConfig
.inProgress
= 0;
324 sqlite3_mutex_leave(sqlite3GlobalConfig
.pInitMutex
);
326 /* Go back under the static mutex and clean up the recursive
327 ** mutex to prevent a resource leak.
329 sqlite3_mutex_enter(pMainMtx
);
330 sqlite3GlobalConfig
.nRefInitMutex
--;
331 if( sqlite3GlobalConfig
.nRefInitMutex
<=0 ){
332 assert( sqlite3GlobalConfig
.nRefInitMutex
==0 );
333 sqlite3_mutex_free(sqlite3GlobalConfig
.pInitMutex
);
334 sqlite3GlobalConfig
.pInitMutex
= 0;
336 sqlite3_mutex_leave(pMainMtx
);
338 /* The following is just a sanity check to make sure SQLite has
339 ** been compiled correctly. It is important to run this code, but
340 ** we don't want to run it too often and soak up CPU cycles for no
341 ** reason. So we run it once during initialization.
344 #ifndef SQLITE_OMIT_FLOATING_POINT
345 /* This section of code's only "output" is via assert() statements. */
347 u64 x
= (((u64
)1)<<63)-1;
349 assert(sizeof(x
)==8);
350 assert(sizeof(x
)==sizeof(y
));
352 assert( sqlite3IsNaN(y
) );
357 /* Do extra initialization steps requested by the SQLITE_EXTRA_INIT
358 ** compile-time option.
360 #ifdef SQLITE_EXTRA_INIT
362 int SQLITE_EXTRA_INIT(const char*);
363 rc
= SQLITE_EXTRA_INIT(0);
371 ** Undo the effects of sqlite3_initialize(). Must not be called while
372 ** there are outstanding database connections or memory allocations or
373 ** while any part of SQLite is otherwise in use in any thread. This
374 ** routine is not threadsafe. But it is safe to invoke this routine
375 ** on when SQLite is already shut down. If SQLite is already shut down
376 ** when this routine is invoked, then this routine is a harmless no-op.
378 int sqlite3_shutdown(void){
379 #ifdef SQLITE_OMIT_WSD
380 int rc
= sqlite3_wsd_init(4096, 24);
386 if( sqlite3GlobalConfig
.isInit
){
387 #ifdef SQLITE_EXTRA_SHUTDOWN
388 void SQLITE_EXTRA_SHUTDOWN(void);
389 SQLITE_EXTRA_SHUTDOWN();
392 sqlite3_reset_auto_extension();
393 sqlite3GlobalConfig
.isInit
= 0;
395 if( sqlite3GlobalConfig
.isPCacheInit
){
396 sqlite3PcacheShutdown();
397 sqlite3GlobalConfig
.isPCacheInit
= 0;
399 if( sqlite3GlobalConfig
.isMallocInit
){
401 sqlite3GlobalConfig
.isMallocInit
= 0;
403 #ifndef SQLITE_OMIT_SHUTDOWN_DIRECTORIES
404 /* The heap subsystem has now been shutdown and these values are supposed
405 ** to be NULL or point to memory that was obtained from sqlite3_malloc(),
406 ** which would rely on that heap subsystem; therefore, make sure these
407 ** values cannot refer to heap memory that was just invalidated when the
408 ** heap subsystem was shutdown. This is only done if the current call to
409 ** this function resulted in the heap subsystem actually being shutdown.
411 sqlite3_data_directory
= 0;
412 sqlite3_temp_directory
= 0;
415 if( sqlite3GlobalConfig
.isMutexInit
){
417 sqlite3GlobalConfig
.isMutexInit
= 0;
424 ** This API allows applications to modify the global configuration of
425 ** the SQLite library at run-time.
427 ** This routine should only be called when there are no outstanding
428 ** database connections or memory allocations. This routine is not
429 ** threadsafe. Failure to heed these warnings can lead to unpredictable
432 int sqlite3_config(int op
, ...){
436 /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while
437 ** the SQLite library is in use. */
438 if( sqlite3GlobalConfig
.isInit
) return SQLITE_MISUSE_BKPT
;
443 /* Mutex configuration options are only available in a threadsafe
446 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0 /* IMP: R-54466-46756 */
447 case SQLITE_CONFIG_SINGLETHREAD
: {
448 /* EVIDENCE-OF: R-02748-19096 This option sets the threading mode to
450 sqlite3GlobalConfig
.bCoreMutex
= 0; /* Disable mutex on core */
451 sqlite3GlobalConfig
.bFullMutex
= 0; /* Disable mutex on connections */
455 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0 /* IMP: R-20520-54086 */
456 case SQLITE_CONFIG_MULTITHREAD
: {
457 /* EVIDENCE-OF: R-14374-42468 This option sets the threading mode to
459 sqlite3GlobalConfig
.bCoreMutex
= 1; /* Enable mutex on core */
460 sqlite3GlobalConfig
.bFullMutex
= 0; /* Disable mutex on connections */
464 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0 /* IMP: R-59593-21810 */
465 case SQLITE_CONFIG_SERIALIZED
: {
466 /* EVIDENCE-OF: R-41220-51800 This option sets the threading mode to
468 sqlite3GlobalConfig
.bCoreMutex
= 1; /* Enable mutex on core */
469 sqlite3GlobalConfig
.bFullMutex
= 1; /* Enable mutex on connections */
473 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0 /* IMP: R-63666-48755 */
474 case SQLITE_CONFIG_MUTEX
: {
475 /* Specify an alternative mutex implementation */
476 sqlite3GlobalConfig
.mutex
= *va_arg(ap
, sqlite3_mutex_methods
*);
480 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0 /* IMP: R-14450-37597 */
481 case SQLITE_CONFIG_GETMUTEX
: {
482 /* Retrieve the current mutex implementation */
483 *va_arg(ap
, sqlite3_mutex_methods
*) = sqlite3GlobalConfig
.mutex
;
488 case SQLITE_CONFIG_MALLOC
: {
489 /* EVIDENCE-OF: R-55594-21030 The SQLITE_CONFIG_MALLOC option takes a
490 ** single argument which is a pointer to an instance of the
491 ** sqlite3_mem_methods structure. The argument specifies alternative
492 ** low-level memory allocation routines to be used in place of the memory
493 ** allocation routines built into SQLite. */
494 sqlite3GlobalConfig
.m
= *va_arg(ap
, sqlite3_mem_methods
*);
497 case SQLITE_CONFIG_GETMALLOC
: {
498 /* EVIDENCE-OF: R-51213-46414 The SQLITE_CONFIG_GETMALLOC option takes a
499 ** single argument which is a pointer to an instance of the
500 ** sqlite3_mem_methods structure. The sqlite3_mem_methods structure is
501 ** filled with the currently defined memory allocation routines. */
502 if( sqlite3GlobalConfig
.m
.xMalloc
==0 ) sqlite3MemSetDefault();
503 *va_arg(ap
, sqlite3_mem_methods
*) = sqlite3GlobalConfig
.m
;
506 case SQLITE_CONFIG_MEMSTATUS
: {
507 /* EVIDENCE-OF: R-61275-35157 The SQLITE_CONFIG_MEMSTATUS option takes
508 ** single argument of type int, interpreted as a boolean, which enables
509 ** or disables the collection of memory allocation statistics. */
510 sqlite3GlobalConfig
.bMemstat
= va_arg(ap
, int);
513 case SQLITE_CONFIG_SMALL_MALLOC
: {
514 sqlite3GlobalConfig
.bSmallMalloc
= va_arg(ap
, int);
517 case SQLITE_CONFIG_PAGECACHE
: {
518 /* EVIDENCE-OF: R-18761-36601 There are three arguments to
519 ** SQLITE_CONFIG_PAGECACHE: A pointer to 8-byte aligned memory (pMem),
520 ** the size of each page cache line (sz), and the number of cache lines
522 sqlite3GlobalConfig
.pPage
= va_arg(ap
, void*);
523 sqlite3GlobalConfig
.szPage
= va_arg(ap
, int);
524 sqlite3GlobalConfig
.nPage
= va_arg(ap
, int);
527 case SQLITE_CONFIG_PCACHE_HDRSZ
: {
528 /* EVIDENCE-OF: R-39100-27317 The SQLITE_CONFIG_PCACHE_HDRSZ option takes
529 ** a single parameter which is a pointer to an integer and writes into
530 ** that integer the number of extra bytes per page required for each page
531 ** in SQLITE_CONFIG_PAGECACHE. */
533 sqlite3HeaderSizeBtree() +
534 sqlite3HeaderSizePcache() +
535 sqlite3HeaderSizePcache1();
539 case SQLITE_CONFIG_PCACHE
: {
543 case SQLITE_CONFIG_GETPCACHE
: {
549 case SQLITE_CONFIG_PCACHE2
: {
550 /* EVIDENCE-OF: R-63325-48378 The SQLITE_CONFIG_PCACHE2 option takes a
551 ** single argument which is a pointer to an sqlite3_pcache_methods2
552 ** object. This object specifies the interface to a custom page cache
553 ** implementation. */
554 sqlite3GlobalConfig
.pcache2
= *va_arg(ap
, sqlite3_pcache_methods2
*);
557 case SQLITE_CONFIG_GETPCACHE2
: {
558 /* EVIDENCE-OF: R-22035-46182 The SQLITE_CONFIG_GETPCACHE2 option takes a
559 ** single argument which is a pointer to an sqlite3_pcache_methods2
560 ** object. SQLite copies of the current page cache implementation into
562 if( sqlite3GlobalConfig
.pcache2
.xInit
==0 ){
563 sqlite3PCacheSetDefault();
565 *va_arg(ap
, sqlite3_pcache_methods2
*) = sqlite3GlobalConfig
.pcache2
;
569 /* EVIDENCE-OF: R-06626-12911 The SQLITE_CONFIG_HEAP option is only
570 ** available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or
571 ** SQLITE_ENABLE_MEMSYS5 and returns SQLITE_ERROR if invoked otherwise. */
572 #if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
573 case SQLITE_CONFIG_HEAP
: {
574 /* EVIDENCE-OF: R-19854-42126 There are three arguments to
575 ** SQLITE_CONFIG_HEAP: An 8-byte aligned pointer to the memory, the
576 ** number of bytes in the memory buffer, and the minimum allocation size.
578 sqlite3GlobalConfig
.pHeap
= va_arg(ap
, void*);
579 sqlite3GlobalConfig
.nHeap
= va_arg(ap
, int);
580 sqlite3GlobalConfig
.mnReq
= va_arg(ap
, int);
582 if( sqlite3GlobalConfig
.mnReq
<1 ){
583 sqlite3GlobalConfig
.mnReq
= 1;
584 }else if( sqlite3GlobalConfig
.mnReq
>(1<<12) ){
585 /* cap min request size at 2^12 */
586 sqlite3GlobalConfig
.mnReq
= (1<<12);
589 if( sqlite3GlobalConfig
.pHeap
==0 ){
590 /* EVIDENCE-OF: R-49920-60189 If the first pointer (the memory pointer)
591 ** is NULL, then SQLite reverts to using its default memory allocator
592 ** (the system malloc() implementation), undoing any prior invocation of
593 ** SQLITE_CONFIG_MALLOC.
595 ** Setting sqlite3GlobalConfig.m to all zeros will cause malloc to
596 ** revert to its default implementation when sqlite3_initialize() is run
598 memset(&sqlite3GlobalConfig
.m
, 0, sizeof(sqlite3GlobalConfig
.m
));
600 /* EVIDENCE-OF: R-61006-08918 If the memory pointer is not NULL then the
601 ** alternative memory allocator is engaged to handle all of SQLites
602 ** memory allocation needs. */
603 #ifdef SQLITE_ENABLE_MEMSYS3
604 sqlite3GlobalConfig
.m
= *sqlite3MemGetMemsys3();
606 #ifdef SQLITE_ENABLE_MEMSYS5
607 sqlite3GlobalConfig
.m
= *sqlite3MemGetMemsys5();
614 case SQLITE_CONFIG_LOOKASIDE
: {
615 sqlite3GlobalConfig
.szLookaside
= va_arg(ap
, int);
616 sqlite3GlobalConfig
.nLookaside
= va_arg(ap
, int);
620 /* Record a pointer to the logger function and its first argument.
621 ** The default is NULL. Logging is disabled if the function pointer is
624 case SQLITE_CONFIG_LOG
: {
625 /* MSVC is picky about pulling func ptrs from va lists.
626 ** http://support.microsoft.com/kb/47961
627 ** sqlite3GlobalConfig.xLog = va_arg(ap, void(*)(void*,int,const char*));
629 typedef void(*LOGFUNC_t
)(void*,int,const char*);
630 sqlite3GlobalConfig
.xLog
= va_arg(ap
, LOGFUNC_t
);
631 sqlite3GlobalConfig
.pLogArg
= va_arg(ap
, void*);
635 /* EVIDENCE-OF: R-55548-33817 The compile-time setting for URI filenames
636 ** can be changed at start-time using the
637 ** sqlite3_config(SQLITE_CONFIG_URI,1) or
638 ** sqlite3_config(SQLITE_CONFIG_URI,0) configuration calls.
640 case SQLITE_CONFIG_URI
: {
641 /* EVIDENCE-OF: R-25451-61125 The SQLITE_CONFIG_URI option takes a single
642 ** argument of type int. If non-zero, then URI handling is globally
643 ** enabled. If the parameter is zero, then URI handling is globally
645 sqlite3GlobalConfig
.bOpenUri
= va_arg(ap
, int);
649 case SQLITE_CONFIG_COVERING_INDEX_SCAN
: {
650 /* EVIDENCE-OF: R-36592-02772 The SQLITE_CONFIG_COVERING_INDEX_SCAN
651 ** option takes a single integer argument which is interpreted as a
652 ** boolean in order to enable or disable the use of covering indices for
653 ** full table scans in the query optimizer. */
654 sqlite3GlobalConfig
.bUseCis
= va_arg(ap
, int);
658 #ifdef SQLITE_ENABLE_SQLLOG
659 case SQLITE_CONFIG_SQLLOG
: {
660 typedef void(*SQLLOGFUNC_t
)(void*, sqlite3
*, const char*, int);
661 sqlite3GlobalConfig
.xSqllog
= va_arg(ap
, SQLLOGFUNC_t
);
662 sqlite3GlobalConfig
.pSqllogArg
= va_arg(ap
, void *);
667 case SQLITE_CONFIG_MMAP_SIZE
: {
668 /* EVIDENCE-OF: R-58063-38258 SQLITE_CONFIG_MMAP_SIZE takes two 64-bit
669 ** integer (sqlite3_int64) values that are the default mmap size limit
670 ** (the default setting for PRAGMA mmap_size) and the maximum allowed
671 ** mmap size limit. */
672 sqlite3_int64 szMmap
= va_arg(ap
, sqlite3_int64
);
673 sqlite3_int64 mxMmap
= va_arg(ap
, sqlite3_int64
);
674 /* EVIDENCE-OF: R-53367-43190 If either argument to this option is
675 ** negative, then that argument is changed to its compile-time default.
677 ** EVIDENCE-OF: R-34993-45031 The maximum allowed mmap size will be
678 ** silently truncated if necessary so that it does not exceed the
679 ** compile-time maximum mmap size set by the SQLITE_MAX_MMAP_SIZE
680 ** compile-time option.
682 if( mxMmap
<0 || mxMmap
>SQLITE_MAX_MMAP_SIZE
){
683 mxMmap
= SQLITE_MAX_MMAP_SIZE
;
685 if( szMmap
<0 ) szMmap
= SQLITE_DEFAULT_MMAP_SIZE
;
686 if( szMmap
>mxMmap
) szMmap
= mxMmap
;
687 sqlite3GlobalConfig
.mxMmap
= mxMmap
;
688 sqlite3GlobalConfig
.szMmap
= szMmap
;
692 #if SQLITE_OS_WIN && defined(SQLITE_WIN32_MALLOC) /* IMP: R-04780-55815 */
693 case SQLITE_CONFIG_WIN32_HEAPSIZE
: {
694 /* EVIDENCE-OF: R-34926-03360 SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit
695 ** unsigned integer value that specifies the maximum size of the created
697 sqlite3GlobalConfig
.nHeap
= va_arg(ap
, int);
702 case SQLITE_CONFIG_PMASZ
: {
703 sqlite3GlobalConfig
.szPma
= va_arg(ap
, unsigned int);
707 case SQLITE_CONFIG_STMTJRNL_SPILL
: {
708 sqlite3GlobalConfig
.nStmtSpill
= va_arg(ap
, int);
712 #ifdef SQLITE_ENABLE_SORTER_REFERENCES
713 case SQLITE_CONFIG_SORTERREF_SIZE
: {
714 int iVal
= va_arg(ap
, int);
716 iVal
= SQLITE_DEFAULT_SORTERREF_SIZE
;
718 sqlite3GlobalConfig
.szSorterRef
= (u32
)iVal
;
721 #endif /* SQLITE_ENABLE_SORTER_REFERENCES */
723 #ifndef SQLITE_OMIT_DESERIALIZE
724 case SQLITE_CONFIG_MEMDB_MAXSIZE
: {
725 sqlite3GlobalConfig
.mxMemdbSize
= va_arg(ap
, sqlite3_int64
);
728 #endif /* SQLITE_OMIT_DESERIALIZE */
740 ** Set up the lookaside buffers for a database connection.
741 ** Return SQLITE_OK on success.
742 ** If lookaside is already active, return SQLITE_BUSY.
744 ** The sz parameter is the number of bytes in each lookaside slot.
745 ** The cnt parameter is the number of slots. If pStart is NULL the
746 ** space for the lookaside memory is obtained from sqlite3_malloc().
747 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
748 ** the lookaside memory.
750 static int setupLookaside(sqlite3
*db
, void *pBuf
, int sz
, int cnt
){
751 #ifndef SQLITE_OMIT_LOOKASIDE
753 sqlite3_int64 szAlloc
= sz
*(sqlite3_int64
)cnt
;
754 int nBig
; /* Number of full-size slots */
755 int nSm
; /* Number smaller LOOKASIDE_SMALL-byte slots */
757 if( sqlite3LookasideUsed(db
,0)>0 ){
760 /* Free any existing lookaside buffer for this handle before
761 ** allocating a new one so we don't have to have space for
762 ** both at the same time.
764 if( db
->lookaside
.bMalloced
){
765 sqlite3_free(db
->lookaside
.pStart
);
767 /* The size of a lookaside slot after ROUNDDOWN8 needs to be larger
768 ** than a pointer to be useful.
770 sz
= ROUNDDOWN8(sz
); /* IMP: R-33038-09382 */
771 if( sz
<=(int)sizeof(LookasideSlot
*) ) sz
= 0;
773 if( sz
==0 || cnt
==0 ){
777 sqlite3BeginBenignMalloc();
778 pStart
= sqlite3Malloc( szAlloc
); /* IMP: R-61949-35727 */
779 sqlite3EndBenignMalloc();
780 if( pStart
) szAlloc
= sqlite3MallocSize(pStart
);
784 #ifndef SQLITE_OMIT_TWOSIZE_LOOKASIDE
785 if( sz
>=LOOKASIDE_SMALL
*3 ){
786 nBig
= szAlloc
/(3*LOOKASIDE_SMALL
+sz
);
787 nSm
= (szAlloc
- sz
*nBig
)/LOOKASIDE_SMALL
;
788 }else if( sz
>=LOOKASIDE_SMALL
*2 ){
789 nBig
= szAlloc
/(LOOKASIDE_SMALL
+sz
);
790 nSm
= (szAlloc
- sz
*nBig
)/LOOKASIDE_SMALL
;
792 #endif /* SQLITE_OMIT_TWOSIZE_LOOKASIDE */
799 db
->lookaside
.pStart
= pStart
;
800 db
->lookaside
.pInit
= 0;
801 db
->lookaside
.pFree
= 0;
802 db
->lookaside
.sz
= (u16
)sz
;
803 db
->lookaside
.szTrue
= (u16
)sz
;
807 assert( sz
> (int)sizeof(LookasideSlot
*) );
808 p
= (LookasideSlot
*)pStart
;
809 for(i
=0; i
<nBig
; i
++){
810 p
->pNext
= db
->lookaside
.pInit
;
811 db
->lookaside
.pInit
= p
;
812 p
= (LookasideSlot
*)&((u8
*)p
)[sz
];
814 #ifndef SQLITE_OMIT_TWOSIZE_LOOKASIDE
815 db
->lookaside
.pSmallInit
= 0;
816 db
->lookaside
.pSmallFree
= 0;
817 db
->lookaside
.pMiddle
= p
;
818 for(i
=0; i
<nSm
; i
++){
819 p
->pNext
= db
->lookaside
.pSmallInit
;
820 db
->lookaside
.pSmallInit
= p
;
821 p
= (LookasideSlot
*)&((u8
*)p
)[LOOKASIDE_SMALL
];
823 #endif /* SQLITE_OMIT_TWOSIZE_LOOKASIDE */
824 assert( ((uptr
)p
)<=szAlloc
+ (uptr
)pStart
);
825 db
->lookaside
.pEnd
= p
;
826 db
->lookaside
.bDisable
= 0;
827 db
->lookaside
.bMalloced
= pBuf
==0 ?1:0;
828 db
->lookaside
.nSlot
= nBig
+nSm
;
830 db
->lookaside
.pStart
= db
;
831 #ifndef SQLITE_OMIT_TWOSIZE_LOOKASIDE
832 db
->lookaside
.pSmallInit
= 0;
833 db
->lookaside
.pSmallFree
= 0;
834 db
->lookaside
.pMiddle
= db
;
835 #endif /* SQLITE_OMIT_TWOSIZE_LOOKASIDE */
836 db
->lookaside
.pEnd
= db
;
837 db
->lookaside
.bDisable
= 1;
838 db
->lookaside
.sz
= 0;
839 db
->lookaside
.bMalloced
= 0;
840 db
->lookaside
.nSlot
= 0;
842 assert( sqlite3LookasideUsed(db
,0)==0 );
843 #endif /* SQLITE_OMIT_LOOKASIDE */
848 ** Return the mutex associated with a database connection.
850 sqlite3_mutex
*sqlite3_db_mutex(sqlite3
*db
){
851 #ifdef SQLITE_ENABLE_API_ARMOR
852 if( !sqlite3SafetyCheckOk(db
) ){
853 (void)SQLITE_MISUSE_BKPT
;
861 ** Free up as much memory as we can from the given database
864 int sqlite3_db_release_memory(sqlite3
*db
){
867 #ifdef SQLITE_ENABLE_API_ARMOR
868 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
870 sqlite3_mutex_enter(db
->mutex
);
871 sqlite3BtreeEnterAll(db
);
872 for(i
=0; i
<db
->nDb
; i
++){
873 Btree
*pBt
= db
->aDb
[i
].pBt
;
875 Pager
*pPager
= sqlite3BtreePager(pBt
);
876 sqlite3PagerShrink(pPager
);
879 sqlite3BtreeLeaveAll(db
);
880 sqlite3_mutex_leave(db
->mutex
);
885 ** Flush any dirty pages in the pager-cache for any attached database
888 int sqlite3_db_cacheflush(sqlite3
*db
){
893 #ifdef SQLITE_ENABLE_API_ARMOR
894 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
896 sqlite3_mutex_enter(db
->mutex
);
897 sqlite3BtreeEnterAll(db
);
898 for(i
=0; rc
==SQLITE_OK
&& i
<db
->nDb
; i
++){
899 Btree
*pBt
= db
->aDb
[i
].pBt
;
900 if( pBt
&& sqlite3BtreeTxnState(pBt
)==SQLITE_TXN_WRITE
){
901 Pager
*pPager
= sqlite3BtreePager(pBt
);
902 rc
= sqlite3PagerFlush(pPager
);
903 if( rc
==SQLITE_BUSY
){
909 sqlite3BtreeLeaveAll(db
);
910 sqlite3_mutex_leave(db
->mutex
);
911 return ((rc
==SQLITE_OK
&& bSeenBusy
) ? SQLITE_BUSY
: rc
);
915 ** Configuration settings for an individual database connection
917 int sqlite3_db_config(sqlite3
*db
, int op
, ...){
922 case SQLITE_DBCONFIG_MAINDBNAME
: {
923 /* IMP: R-06824-28531 */
924 /* IMP: R-36257-52125 */
925 db
->aDb
[0].zDbSName
= va_arg(ap
,char*);
929 case SQLITE_DBCONFIG_LOOKASIDE
: {
930 void *pBuf
= va_arg(ap
, void*); /* IMP: R-26835-10964 */
931 int sz
= va_arg(ap
, int); /* IMP: R-47871-25994 */
932 int cnt
= va_arg(ap
, int); /* IMP: R-04460-53386 */
933 rc
= setupLookaside(db
, pBuf
, sz
, cnt
);
937 static const struct {
938 int op
; /* The opcode */
939 u32 mask
; /* Mask of the bit in sqlite3.flags to set/clear */
941 { SQLITE_DBCONFIG_ENABLE_FKEY
, SQLITE_ForeignKeys
},
942 { SQLITE_DBCONFIG_ENABLE_TRIGGER
, SQLITE_EnableTrigger
},
943 { SQLITE_DBCONFIG_ENABLE_VIEW
, SQLITE_EnableView
},
944 { SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
, SQLITE_Fts3Tokenizer
},
945 { SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
, SQLITE_LoadExtension
},
946 { SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
, SQLITE_NoCkptOnClose
},
947 { SQLITE_DBCONFIG_ENABLE_QPSG
, SQLITE_EnableQPSG
},
948 { SQLITE_DBCONFIG_TRIGGER_EQP
, SQLITE_TriggerEQP
},
949 { SQLITE_DBCONFIG_RESET_DATABASE
, SQLITE_ResetDatabase
},
950 { SQLITE_DBCONFIG_DEFENSIVE
, SQLITE_Defensive
},
951 { SQLITE_DBCONFIG_WRITABLE_SCHEMA
, SQLITE_WriteSchema
|
952 SQLITE_NoSchemaError
},
953 { SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
, SQLITE_LegacyAlter
},
954 { SQLITE_DBCONFIG_DQS_DDL
, SQLITE_DqsDDL
},
955 { SQLITE_DBCONFIG_DQS_DML
, SQLITE_DqsDML
},
956 { SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
, SQLITE_LegacyFileFmt
},
957 { SQLITE_DBCONFIG_TRUSTED_SCHEMA
, SQLITE_TrustedSchema
},
960 rc
= SQLITE_ERROR
; /* IMP: R-42790-23372 */
961 for(i
=0; i
<ArraySize(aFlagOp
); i
++){
962 if( aFlagOp
[i
].op
==op
){
963 int onoff
= va_arg(ap
, int);
964 int *pRes
= va_arg(ap
, int*);
965 u64 oldFlags
= db
->flags
;
967 db
->flags
|= aFlagOp
[i
].mask
;
968 }else if( onoff
==0 ){
969 db
->flags
&= ~(u64
)aFlagOp
[i
].mask
;
971 if( oldFlags
!=db
->flags
){
972 sqlite3ExpirePreparedStatements(db
, 0);
975 *pRes
= (db
->flags
& aFlagOp
[i
].mask
)!=0;
989 ** This is the default collating function named "BINARY" which is always
992 static int binCollFunc(
994 int nKey1
, const void *pKey1
,
995 int nKey2
, const void *pKey2
998 UNUSED_PARAMETER(NotUsed
);
999 n
= nKey1
<nKey2
? nKey1
: nKey2
;
1000 /* EVIDENCE-OF: R-65033-28449 The built-in BINARY collation compares
1001 ** strings byte by byte using the memcmp() function from the standard C
1003 assert( pKey1
&& pKey2
);
1004 rc
= memcmp(pKey1
, pKey2
, n
);
1012 ** This is the collating function named "RTRIM" which is always
1013 ** available. Ignore trailing spaces.
1015 static int rtrimCollFunc(
1017 int nKey1
, const void *pKey1
,
1018 int nKey2
, const void *pKey2
1020 const u8
*pK1
= (const u8
*)pKey1
;
1021 const u8
*pK2
= (const u8
*)pKey2
;
1022 while( nKey1
&& pK1
[nKey1
-1]==' ' ) nKey1
--;
1023 while( nKey2
&& pK2
[nKey2
-1]==' ' ) nKey2
--;
1024 return binCollFunc(pUser
, nKey1
, pKey1
, nKey2
, pKey2
);
1028 ** Return true if CollSeq is the default built-in BINARY.
1030 int sqlite3IsBinary(const CollSeq
*p
){
1031 assert( p
==0 || p
->xCmp
!=binCollFunc
|| strcmp(p
->zName
,"BINARY")==0 );
1032 return p
==0 || p
->xCmp
==binCollFunc
;
1036 ** Another built-in collating sequence: NOCASE.
1038 ** This collating sequence is intended to be used for "case independent
1039 ** comparison". SQLite's knowledge of upper and lower case equivalents
1040 ** extends only to the 26 characters used in the English language.
1042 ** At the moment there is only a UTF-8 implementation.
1044 static int nocaseCollatingFunc(
1046 int nKey1
, const void *pKey1
,
1047 int nKey2
, const void *pKey2
1049 int r
= sqlite3StrNICmp(
1050 (const char *)pKey1
, (const char *)pKey2
, (nKey1
<nKey2
)?nKey1
:nKey2
);
1051 UNUSED_PARAMETER(NotUsed
);
1059 ** Return the ROWID of the most recent insert
1061 sqlite_int64
sqlite3_last_insert_rowid(sqlite3
*db
){
1062 #ifdef SQLITE_ENABLE_API_ARMOR
1063 if( !sqlite3SafetyCheckOk(db
) ){
1064 (void)SQLITE_MISUSE_BKPT
;
1068 return db
->lastRowid
;
1072 ** Set the value returned by the sqlite3_last_insert_rowid() API function.
1074 void sqlite3_set_last_insert_rowid(sqlite3
*db
, sqlite3_int64 iRowid
){
1075 #ifdef SQLITE_ENABLE_API_ARMOR
1076 if( !sqlite3SafetyCheckOk(db
) ){
1077 (void)SQLITE_MISUSE_BKPT
;
1081 sqlite3_mutex_enter(db
->mutex
);
1082 db
->lastRowid
= iRowid
;
1083 sqlite3_mutex_leave(db
->mutex
);
1087 ** Return the number of changes in the most recent call to sqlite3_exec().
1089 int sqlite3_changes(sqlite3
*db
){
1090 #ifdef SQLITE_ENABLE_API_ARMOR
1091 if( !sqlite3SafetyCheckOk(db
) ){
1092 (void)SQLITE_MISUSE_BKPT
;
1100 ** Return the number of changes since the database handle was opened.
1102 int sqlite3_total_changes(sqlite3
*db
){
1103 #ifdef SQLITE_ENABLE_API_ARMOR
1104 if( !sqlite3SafetyCheckOk(db
) ){
1105 (void)SQLITE_MISUSE_BKPT
;
1109 return db
->nTotalChange
;
1113 ** Close all open savepoints. This function only manipulates fields of the
1114 ** database handle object, it does not close any savepoints that may be open
1115 ** at the b-tree/pager level.
1117 void sqlite3CloseSavepoints(sqlite3
*db
){
1118 while( db
->pSavepoint
){
1119 Savepoint
*pTmp
= db
->pSavepoint
;
1120 db
->pSavepoint
= pTmp
->pNext
;
1121 sqlite3DbFree(db
, pTmp
);
1125 db
->isTransactionSavepoint
= 0;
1129 ** Invoke the destructor function associated with FuncDef p, if any. Except,
1130 ** if this is not the last copy of the function, do not invoke it. Multiple
1131 ** copies of a single function are created when create_function() is called
1132 ** with SQLITE_ANY as the encoding.
1134 static void functionDestroy(sqlite3
*db
, FuncDef
*p
){
1135 FuncDestructor
*pDestructor
= p
->u
.pDestructor
;
1137 pDestructor
->nRef
--;
1138 if( pDestructor
->nRef
==0 ){
1139 pDestructor
->xDestroy(pDestructor
->pUserData
);
1140 sqlite3DbFree(db
, pDestructor
);
1146 ** Disconnect all sqlite3_vtab objects that belong to database connection
1147 ** db. This is called when db is being closed.
1149 static void disconnectAllVtab(sqlite3
*db
){
1150 #ifndef SQLITE_OMIT_VIRTUALTABLE
1153 sqlite3BtreeEnterAll(db
);
1154 for(i
=0; i
<db
->nDb
; i
++){
1155 Schema
*pSchema
= db
->aDb
[i
].pSchema
;
1157 for(p
=sqliteHashFirst(&pSchema
->tblHash
); p
; p
=sqliteHashNext(p
)){
1158 Table
*pTab
= (Table
*)sqliteHashData(p
);
1159 if( IsVirtual(pTab
) ) sqlite3VtabDisconnect(db
, pTab
);
1163 for(p
=sqliteHashFirst(&db
->aModule
); p
; p
=sqliteHashNext(p
)){
1164 Module
*pMod
= (Module
*)sqliteHashData(p
);
1165 if( pMod
->pEpoTab
){
1166 sqlite3VtabDisconnect(db
, pMod
->pEpoTab
);
1169 sqlite3VtabUnlockList(db
);
1170 sqlite3BtreeLeaveAll(db
);
1172 UNUSED_PARAMETER(db
);
1177 ** Return TRUE if database connection db has unfinalized prepared
1178 ** statements or unfinished sqlite3_backup objects.
1180 static int connectionIsBusy(sqlite3
*db
){
1182 assert( sqlite3_mutex_held(db
->mutex
) );
1183 if( db
->pVdbe
) return 1;
1184 for(j
=0; j
<db
->nDb
; j
++){
1185 Btree
*pBt
= db
->aDb
[j
].pBt
;
1186 if( pBt
&& sqlite3BtreeIsInBackup(pBt
) ) return 1;
1192 ** Close an existing SQLite database
1194 static int sqlite3Close(sqlite3
*db
, int forceZombie
){
1196 /* EVIDENCE-OF: R-63257-11740 Calling sqlite3_close() or
1197 ** sqlite3_close_v2() with a NULL pointer argument is a harmless no-op. */
1200 if( !sqlite3SafetyCheckSickOrOk(db
) ){
1201 return SQLITE_MISUSE_BKPT
;
1203 sqlite3_mutex_enter(db
->mutex
);
1204 if( db
->mTrace
& SQLITE_TRACE_CLOSE
){
1205 db
->trace
.xV2(SQLITE_TRACE_CLOSE
, db
->pTraceArg
, db
, 0);
1208 /* Force xDisconnect calls on all virtual tables */
1209 disconnectAllVtab(db
);
1211 /* If a transaction is open, the disconnectAllVtab() call above
1212 ** will not have called the xDisconnect() method on any virtual
1213 ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()
1214 ** call will do so. We need to do this before the check for active
1215 ** SQL statements below, as the v-table implementation may be storing
1216 ** some prepared statements internally.
1218 sqlite3VtabRollback(db
);
1220 /* Legacy behavior (sqlite3_close() behavior) is to return
1221 ** SQLITE_BUSY if the connection can not be closed immediately.
1223 if( !forceZombie
&& connectionIsBusy(db
) ){
1224 sqlite3ErrorWithMsg(db
, SQLITE_BUSY
, "unable to close due to unfinalized "
1225 "statements or unfinished backups");
1226 sqlite3_mutex_leave(db
->mutex
);
1230 #ifdef SQLITE_ENABLE_SQLLOG
1231 if( sqlite3GlobalConfig
.xSqllog
){
1232 /* Closing the handle. Fourth parameter is passed the value 2. */
1233 sqlite3GlobalConfig
.xSqllog(sqlite3GlobalConfig
.pSqllogArg
, db
, 0, 2);
1237 /* Convert the connection into a zombie and then close it.
1239 db
->magic
= SQLITE_MAGIC_ZOMBIE
;
1240 sqlite3LeaveMutexAndCloseZombie(db
);
1245 ** Return the transaction state for a single databse, or the maximum
1246 ** transaction state over all attached databases if zSchema is null.
1248 int sqlite3_txn_state(sqlite3
*db
, const char *zSchema
){
1251 #ifdef SQLITE_ENABLE_API_ARMOR
1252 if( !sqlite3SafetyCheckOk(db
) ){
1253 (void)SQLITE_MISUSE_BKPT
;
1257 sqlite3_mutex_enter(db
->mutex
);
1259 nDb
= iDb
= sqlite3FindDbName(db
, zSchema
);
1265 for(; iDb
<=nDb
; iDb
++){
1266 Btree
*pBt
= db
->aDb
[iDb
].pBt
;
1267 int x
= pBt
!=0 ? sqlite3BtreeTxnState(pBt
) : SQLITE_TXN_NONE
;
1268 if( x
>iTxn
) iTxn
= x
;
1270 sqlite3_mutex_leave(db
->mutex
);
1275 ** Two variations on the public interface for closing a database
1276 ** connection. The sqlite3_close() version returns SQLITE_BUSY and
1277 ** leaves the connection open if there are unfinalized prepared
1278 ** statements or unfinished sqlite3_backups. The sqlite3_close_v2()
1279 ** version forces the connection to become a zombie if there are
1280 ** unclosed resources, and arranges for deallocation when the last
1281 ** prepare statement or sqlite3_backup closes.
1283 int sqlite3_close(sqlite3
*db
){ return sqlite3Close(db
,0); }
1284 int sqlite3_close_v2(sqlite3
*db
){ return sqlite3Close(db
,1); }
1288 ** Close the mutex on database connection db.
1290 ** Furthermore, if database connection db is a zombie (meaning that there
1291 ** has been a prior call to sqlite3_close(db) or sqlite3_close_v2(db)) and
1292 ** every sqlite3_stmt has now been finalized and every sqlite3_backup has
1293 ** finished, then free all resources.
1295 void sqlite3LeaveMutexAndCloseZombie(sqlite3
*db
){
1296 HashElem
*i
; /* Hash table iterator */
1299 /* If there are outstanding sqlite3_stmt or sqlite3_backup objects
1300 ** or if the connection has not yet been closed by sqlite3_close_v2(),
1301 ** then just leave the mutex and return.
1303 if( db
->magic
!=SQLITE_MAGIC_ZOMBIE
|| connectionIsBusy(db
) ){
1304 sqlite3_mutex_leave(db
->mutex
);
1308 /* If we reach this point, it means that the database connection has
1309 ** closed all sqlite3_stmt and sqlite3_backup objects and has been
1310 ** passed to sqlite3_close (meaning that it is a zombie). Therefore,
1311 ** go ahead and free all resources.
1314 /* If a transaction is open, roll it back. This also ensures that if
1315 ** any database schemas have been modified by an uncommitted transaction
1316 ** they are reset. And that the required b-tree mutex is held to make
1317 ** the pager rollback and schema reset an atomic operation. */
1318 sqlite3RollbackAll(db
, SQLITE_OK
);
1320 /* Free any outstanding Savepoint structures. */
1321 sqlite3CloseSavepoints(db
);
1323 /* Close all database connections */
1324 for(j
=0; j
<db
->nDb
; j
++){
1325 struct Db
*pDb
= &db
->aDb
[j
];
1327 sqlite3BtreeClose(pDb
->pBt
);
1334 /* Clear the TEMP schema separately and last */
1335 if( db
->aDb
[1].pSchema
){
1336 sqlite3SchemaClear(db
->aDb
[1].pSchema
);
1338 sqlite3VtabUnlockList(db
);
1340 /* Free up the array of auxiliary databases */
1341 sqlite3CollapseDatabaseArray(db
);
1342 assert( db
->nDb
<=2 );
1343 assert( db
->aDb
==db
->aDbStatic
);
1345 /* Tell the code in notify.c that the connection no longer holds any
1346 ** locks and does not require any further unlock-notify callbacks.
1348 sqlite3ConnectionClosed(db
);
1350 for(i
=sqliteHashFirst(&db
->aFunc
); i
; i
=sqliteHashNext(i
)){
1352 p
= sqliteHashData(i
);
1354 functionDestroy(db
, p
);
1356 sqlite3DbFree(db
, p
);
1360 sqlite3HashClear(&db
->aFunc
);
1361 for(i
=sqliteHashFirst(&db
->aCollSeq
); i
; i
=sqliteHashNext(i
)){
1362 CollSeq
*pColl
= (CollSeq
*)sqliteHashData(i
);
1363 /* Invoke any destructors registered for collation sequence user data. */
1365 if( pColl
[j
].xDel
){
1366 pColl
[j
].xDel(pColl
[j
].pUser
);
1369 sqlite3DbFree(db
, pColl
);
1371 sqlite3HashClear(&db
->aCollSeq
);
1372 #ifndef SQLITE_OMIT_VIRTUALTABLE
1373 for(i
=sqliteHashFirst(&db
->aModule
); i
; i
=sqliteHashNext(i
)){
1374 Module
*pMod
= (Module
*)sqliteHashData(i
);
1375 sqlite3VtabEponymousTableClear(db
, pMod
);
1376 sqlite3VtabModuleUnref(db
, pMod
);
1378 sqlite3HashClear(&db
->aModule
);
1381 sqlite3Error(db
, SQLITE_OK
); /* Deallocates any cached error strings. */
1382 sqlite3ValueFree(db
->pErr
);
1383 sqlite3CloseExtensions(db
);
1384 #if SQLITE_USER_AUTHENTICATION
1385 sqlite3_free(db
->auth
.zAuthUser
);
1386 sqlite3_free(db
->auth
.zAuthPW
);
1389 db
->magic
= SQLITE_MAGIC_ERROR
;
1391 /* The temp-database schema is allocated differently from the other schema
1392 ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).
1393 ** So it needs to be freed here. Todo: Why not roll the temp schema into
1394 ** the same sqliteMalloc() as the one that allocates the database
1397 sqlite3DbFree(db
, db
->aDb
[1].pSchema
);
1398 sqlite3_mutex_leave(db
->mutex
);
1399 db
->magic
= SQLITE_MAGIC_CLOSED
;
1400 sqlite3_mutex_free(db
->mutex
);
1401 assert( sqlite3LookasideUsed(db
,0)==0 );
1402 if( db
->lookaside
.bMalloced
){
1403 sqlite3_free(db
->lookaside
.pStart
);
1409 ** Rollback all database files. If tripCode is not SQLITE_OK, then
1410 ** any write cursors are invalidated ("tripped" - as in "tripping a circuit
1411 ** breaker") and made to return tripCode if there are any further
1412 ** attempts to use that cursor. Read cursors remain open and valid
1413 ** but are "saved" in case the table pages are moved around.
1415 void sqlite3RollbackAll(sqlite3
*db
, int tripCode
){
1419 assert( sqlite3_mutex_held(db
->mutex
) );
1420 sqlite3BeginBenignMalloc();
1422 /* Obtain all b-tree mutexes before making any calls to BtreeRollback().
1423 ** This is important in case the transaction being rolled back has
1424 ** modified the database schema. If the b-tree mutexes are not taken
1425 ** here, then another shared-cache connection might sneak in between
1426 ** the database rollback and schema reset, which can cause false
1427 ** corruption reports in some cases. */
1428 sqlite3BtreeEnterAll(db
);
1429 schemaChange
= (db
->mDbFlags
& DBFLAG_SchemaChange
)!=0 && db
->init
.busy
==0;
1431 for(i
=0; i
<db
->nDb
; i
++){
1432 Btree
*p
= db
->aDb
[i
].pBt
;
1434 if( sqlite3BtreeTxnState(p
)==SQLITE_TXN_WRITE
){
1437 sqlite3BtreeRollback(p
, tripCode
, !schemaChange
);
1440 sqlite3VtabRollback(db
);
1441 sqlite3EndBenignMalloc();
1444 sqlite3ExpirePreparedStatements(db
, 0);
1445 sqlite3ResetAllSchemasOfConnection(db
);
1447 sqlite3BtreeLeaveAll(db
);
1449 /* Any deferred constraint violations have now been resolved. */
1450 db
->nDeferredCons
= 0;
1451 db
->nDeferredImmCons
= 0;
1452 db
->flags
&= ~(u64
)SQLITE_DeferFKs
;
1454 /* If one has been configured, invoke the rollback-hook callback */
1455 if( db
->xRollbackCallback
&& (inTrans
|| !db
->autoCommit
) ){
1456 db
->xRollbackCallback(db
->pRollbackArg
);
1461 ** Return a static string containing the name corresponding to the error code
1462 ** specified in the argument.
1464 #if defined(SQLITE_NEED_ERR_NAME)
1465 const char *sqlite3ErrName(int rc
){
1466 const char *zName
= 0;
1468 for(i
=0; i
<2 && zName
==0; i
++, rc
&= 0xff){
1470 case SQLITE_OK
: zName
= "SQLITE_OK"; break;
1471 case SQLITE_ERROR
: zName
= "SQLITE_ERROR"; break;
1472 case SQLITE_ERROR_SNAPSHOT
: zName
= "SQLITE_ERROR_SNAPSHOT"; break;
1473 case SQLITE_INTERNAL
: zName
= "SQLITE_INTERNAL"; break;
1474 case SQLITE_PERM
: zName
= "SQLITE_PERM"; break;
1475 case SQLITE_ABORT
: zName
= "SQLITE_ABORT"; break;
1476 case SQLITE_ABORT_ROLLBACK
: zName
= "SQLITE_ABORT_ROLLBACK"; break;
1477 case SQLITE_BUSY
: zName
= "SQLITE_BUSY"; break;
1478 case SQLITE_BUSY_RECOVERY
: zName
= "SQLITE_BUSY_RECOVERY"; break;
1479 case SQLITE_BUSY_SNAPSHOT
: zName
= "SQLITE_BUSY_SNAPSHOT"; break;
1480 case SQLITE_LOCKED
: zName
= "SQLITE_LOCKED"; break;
1481 case SQLITE_LOCKED_SHAREDCACHE
: zName
= "SQLITE_LOCKED_SHAREDCACHE";break;
1482 case SQLITE_NOMEM
: zName
= "SQLITE_NOMEM"; break;
1483 case SQLITE_READONLY
: zName
= "SQLITE_READONLY"; break;
1484 case SQLITE_READONLY_RECOVERY
: zName
= "SQLITE_READONLY_RECOVERY"; break;
1485 case SQLITE_READONLY_CANTINIT
: zName
= "SQLITE_READONLY_CANTINIT"; break;
1486 case SQLITE_READONLY_ROLLBACK
: zName
= "SQLITE_READONLY_ROLLBACK"; break;
1487 case SQLITE_READONLY_DBMOVED
: zName
= "SQLITE_READONLY_DBMOVED"; break;
1488 case SQLITE_READONLY_DIRECTORY
: zName
= "SQLITE_READONLY_DIRECTORY";break;
1489 case SQLITE_INTERRUPT
: zName
= "SQLITE_INTERRUPT"; break;
1490 case SQLITE_IOERR
: zName
= "SQLITE_IOERR"; break;
1491 case SQLITE_IOERR_READ
: zName
= "SQLITE_IOERR_READ"; break;
1492 case SQLITE_IOERR_SHORT_READ
: zName
= "SQLITE_IOERR_SHORT_READ"; break;
1493 case SQLITE_IOERR_WRITE
: zName
= "SQLITE_IOERR_WRITE"; break;
1494 case SQLITE_IOERR_FSYNC
: zName
= "SQLITE_IOERR_FSYNC"; break;
1495 case SQLITE_IOERR_DIR_FSYNC
: zName
= "SQLITE_IOERR_DIR_FSYNC"; break;
1496 case SQLITE_IOERR_TRUNCATE
: zName
= "SQLITE_IOERR_TRUNCATE"; break;
1497 case SQLITE_IOERR_FSTAT
: zName
= "SQLITE_IOERR_FSTAT"; break;
1498 case SQLITE_IOERR_UNLOCK
: zName
= "SQLITE_IOERR_UNLOCK"; break;
1499 case SQLITE_IOERR_RDLOCK
: zName
= "SQLITE_IOERR_RDLOCK"; break;
1500 case SQLITE_IOERR_DELETE
: zName
= "SQLITE_IOERR_DELETE"; break;
1501 case SQLITE_IOERR_NOMEM
: zName
= "SQLITE_IOERR_NOMEM"; break;
1502 case SQLITE_IOERR_ACCESS
: zName
= "SQLITE_IOERR_ACCESS"; break;
1503 case SQLITE_IOERR_CHECKRESERVEDLOCK
:
1504 zName
= "SQLITE_IOERR_CHECKRESERVEDLOCK"; break;
1505 case SQLITE_IOERR_LOCK
: zName
= "SQLITE_IOERR_LOCK"; break;
1506 case SQLITE_IOERR_CLOSE
: zName
= "SQLITE_IOERR_CLOSE"; break;
1507 case SQLITE_IOERR_DIR_CLOSE
: zName
= "SQLITE_IOERR_DIR_CLOSE"; break;
1508 case SQLITE_IOERR_SHMOPEN
: zName
= "SQLITE_IOERR_SHMOPEN"; break;
1509 case SQLITE_IOERR_SHMSIZE
: zName
= "SQLITE_IOERR_SHMSIZE"; break;
1510 case SQLITE_IOERR_SHMLOCK
: zName
= "SQLITE_IOERR_SHMLOCK"; break;
1511 case SQLITE_IOERR_SHMMAP
: zName
= "SQLITE_IOERR_SHMMAP"; break;
1512 case SQLITE_IOERR_SEEK
: zName
= "SQLITE_IOERR_SEEK"; break;
1513 case SQLITE_IOERR_DELETE_NOENT
: zName
= "SQLITE_IOERR_DELETE_NOENT";break;
1514 case SQLITE_IOERR_MMAP
: zName
= "SQLITE_IOERR_MMAP"; break;
1515 case SQLITE_IOERR_GETTEMPPATH
: zName
= "SQLITE_IOERR_GETTEMPPATH"; break;
1516 case SQLITE_IOERR_CONVPATH
: zName
= "SQLITE_IOERR_CONVPATH"; break;
1517 case SQLITE_CORRUPT
: zName
= "SQLITE_CORRUPT"; break;
1518 case SQLITE_CORRUPT_VTAB
: zName
= "SQLITE_CORRUPT_VTAB"; break;
1519 case SQLITE_NOTFOUND
: zName
= "SQLITE_NOTFOUND"; break;
1520 case SQLITE_FULL
: zName
= "SQLITE_FULL"; break;
1521 case SQLITE_CANTOPEN
: zName
= "SQLITE_CANTOPEN"; break;
1522 case SQLITE_CANTOPEN_NOTEMPDIR
: zName
= "SQLITE_CANTOPEN_NOTEMPDIR";break;
1523 case SQLITE_CANTOPEN_ISDIR
: zName
= "SQLITE_CANTOPEN_ISDIR"; break;
1524 case SQLITE_CANTOPEN_FULLPATH
: zName
= "SQLITE_CANTOPEN_FULLPATH"; break;
1525 case SQLITE_CANTOPEN_CONVPATH
: zName
= "SQLITE_CANTOPEN_CONVPATH"; break;
1526 case SQLITE_CANTOPEN_SYMLINK
: zName
= "SQLITE_CANTOPEN_SYMLINK"; break;
1527 case SQLITE_PROTOCOL
: zName
= "SQLITE_PROTOCOL"; break;
1528 case SQLITE_EMPTY
: zName
= "SQLITE_EMPTY"; break;
1529 case SQLITE_SCHEMA
: zName
= "SQLITE_SCHEMA"; break;
1530 case SQLITE_TOOBIG
: zName
= "SQLITE_TOOBIG"; break;
1531 case SQLITE_CONSTRAINT
: zName
= "SQLITE_CONSTRAINT"; break;
1532 case SQLITE_CONSTRAINT_UNIQUE
: zName
= "SQLITE_CONSTRAINT_UNIQUE"; break;
1533 case SQLITE_CONSTRAINT_TRIGGER
: zName
= "SQLITE_CONSTRAINT_TRIGGER";break;
1534 case SQLITE_CONSTRAINT_FOREIGNKEY
:
1535 zName
= "SQLITE_CONSTRAINT_FOREIGNKEY"; break;
1536 case SQLITE_CONSTRAINT_CHECK
: zName
= "SQLITE_CONSTRAINT_CHECK"; break;
1537 case SQLITE_CONSTRAINT_PRIMARYKEY
:
1538 zName
= "SQLITE_CONSTRAINT_PRIMARYKEY"; break;
1539 case SQLITE_CONSTRAINT_NOTNULL
: zName
= "SQLITE_CONSTRAINT_NOTNULL";break;
1540 case SQLITE_CONSTRAINT_COMMITHOOK
:
1541 zName
= "SQLITE_CONSTRAINT_COMMITHOOK"; break;
1542 case SQLITE_CONSTRAINT_VTAB
: zName
= "SQLITE_CONSTRAINT_VTAB"; break;
1543 case SQLITE_CONSTRAINT_FUNCTION
:
1544 zName
= "SQLITE_CONSTRAINT_FUNCTION"; break;
1545 case SQLITE_CONSTRAINT_ROWID
: zName
= "SQLITE_CONSTRAINT_ROWID"; break;
1546 case SQLITE_MISMATCH
: zName
= "SQLITE_MISMATCH"; break;
1547 case SQLITE_MISUSE
: zName
= "SQLITE_MISUSE"; break;
1548 case SQLITE_NOLFS
: zName
= "SQLITE_NOLFS"; break;
1549 case SQLITE_AUTH
: zName
= "SQLITE_AUTH"; break;
1550 case SQLITE_FORMAT
: zName
= "SQLITE_FORMAT"; break;
1551 case SQLITE_RANGE
: zName
= "SQLITE_RANGE"; break;
1552 case SQLITE_NOTADB
: zName
= "SQLITE_NOTADB"; break;
1553 case SQLITE_ROW
: zName
= "SQLITE_ROW"; break;
1554 case SQLITE_NOTICE
: zName
= "SQLITE_NOTICE"; break;
1555 case SQLITE_NOTICE_RECOVER_WAL
: zName
= "SQLITE_NOTICE_RECOVER_WAL";break;
1556 case SQLITE_NOTICE_RECOVER_ROLLBACK
:
1557 zName
= "SQLITE_NOTICE_RECOVER_ROLLBACK"; break;
1558 case SQLITE_WARNING
: zName
= "SQLITE_WARNING"; break;
1559 case SQLITE_WARNING_AUTOINDEX
: zName
= "SQLITE_WARNING_AUTOINDEX"; break;
1560 case SQLITE_DONE
: zName
= "SQLITE_DONE"; break;
1564 static char zBuf
[50];
1565 sqlite3_snprintf(sizeof(zBuf
), zBuf
, "SQLITE_UNKNOWN(%d)", origRc
);
1573 ** Return a static string that describes the kind of error specified in the
1576 const char *sqlite3ErrStr(int rc
){
1577 static const char* const aMsg
[] = {
1578 /* SQLITE_OK */ "not an error",
1579 /* SQLITE_ERROR */ "SQL logic error",
1580 /* SQLITE_INTERNAL */ 0,
1581 /* SQLITE_PERM */ "access permission denied",
1582 /* SQLITE_ABORT */ "query aborted",
1583 /* SQLITE_BUSY */ "database is locked",
1584 /* SQLITE_LOCKED */ "database table is locked",
1585 /* SQLITE_NOMEM */ "out of memory",
1586 /* SQLITE_READONLY */ "attempt to write a readonly database",
1587 /* SQLITE_INTERRUPT */ "interrupted",
1588 /* SQLITE_IOERR */ "disk I/O error",
1589 /* SQLITE_CORRUPT */ "database disk image is malformed",
1590 /* SQLITE_NOTFOUND */ "unknown operation",
1591 /* SQLITE_FULL */ "database or disk is full",
1592 /* SQLITE_CANTOPEN */ "unable to open database file",
1593 /* SQLITE_PROTOCOL */ "locking protocol",
1594 /* SQLITE_EMPTY */ 0,
1595 /* SQLITE_SCHEMA */ "database schema has changed",
1596 /* SQLITE_TOOBIG */ "string or blob too big",
1597 /* SQLITE_CONSTRAINT */ "constraint failed",
1598 /* SQLITE_MISMATCH */ "datatype mismatch",
1599 /* SQLITE_MISUSE */ "bad parameter or other API misuse",
1600 #ifdef SQLITE_DISABLE_LFS
1601 /* SQLITE_NOLFS */ "large file support is disabled",
1603 /* SQLITE_NOLFS */ 0,
1605 /* SQLITE_AUTH */ "authorization denied",
1606 /* SQLITE_FORMAT */ 0,
1607 /* SQLITE_RANGE */ "column index out of range",
1608 /* SQLITE_NOTADB */ "file is not a database",
1609 /* SQLITE_NOTICE */ "notification message",
1610 /* SQLITE_WARNING */ "warning message",
1612 const char *zErr
= "unknown error";
1614 case SQLITE_ABORT_ROLLBACK
: {
1615 zErr
= "abort due to ROLLBACK";
1619 zErr
= "another row available";
1623 zErr
= "no more rows available";
1628 if( ALWAYS(rc
>=0) && rc
<ArraySize(aMsg
) && aMsg
[rc
]!=0 ){
1638 ** This routine implements a busy callback that sleeps and tries
1639 ** again until a timeout value is reached. The timeout value is
1640 ** an integer number of milliseconds passed in as the first
1643 ** Return non-zero to retry the lock. Return zero to stop trying
1644 ** and cause SQLite to return SQLITE_BUSY.
1646 static int sqliteDefaultBusyCallback(
1647 void *ptr
, /* Database connection */
1648 int count
/* Number of times table has been busy */
1650 #if SQLITE_OS_WIN || HAVE_USLEEP
1651 /* This case is for systems that have support for sleeping for fractions of
1652 ** a second. Examples: All windows systems, unix systems with usleep() */
1653 static const u8 delays
[] =
1654 { 1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100 };
1655 static const u8 totals
[] =
1656 { 0, 1, 3, 8, 18, 33, 53, 78, 103, 128, 178, 228 };
1657 # define NDELAY ArraySize(delays)
1658 sqlite3
*db
= (sqlite3
*)ptr
;
1659 int tmout
= db
->busyTimeout
;
1663 if( count
< NDELAY
){
1664 delay
= delays
[count
];
1665 prior
= totals
[count
];
1667 delay
= delays
[NDELAY
-1];
1668 prior
= totals
[NDELAY
-1] + delay
*(count
-(NDELAY
-1));
1670 if( prior
+ delay
> tmout
){
1671 delay
= tmout
- prior
;
1672 if( delay
<=0 ) return 0;
1674 sqlite3OsSleep(db
->pVfs
, delay
*1000);
1677 /* This case for unix systems that lack usleep() support. Sleeping
1678 ** must be done in increments of whole seconds */
1679 sqlite3
*db
= (sqlite3
*)ptr
;
1680 int tmout
= ((sqlite3
*)ptr
)->busyTimeout
;
1681 if( (count
+1)*1000 > tmout
){
1684 sqlite3OsSleep(db
->pVfs
, 1000000);
1690 ** Invoke the given busy handler.
1692 ** This routine is called when an operation failed to acquire a
1693 ** lock on VFS file pFile.
1695 ** If this routine returns non-zero, the lock is retried. If it
1696 ** returns 0, the operation aborts with an SQLITE_BUSY error.
1698 int sqlite3InvokeBusyHandler(BusyHandler
*p
){
1700 if( p
->xBusyHandler
==0 || p
->nBusy
<0 ) return 0;
1701 rc
= p
->xBusyHandler(p
->pBusyArg
, p
->nBusy
);
1711 ** This routine sets the busy callback for an Sqlite database to the
1712 ** given callback function with the given argument.
1714 int sqlite3_busy_handler(
1716 int (*xBusy
)(void*,int),
1719 #ifdef SQLITE_ENABLE_API_ARMOR
1720 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
1722 sqlite3_mutex_enter(db
->mutex
);
1723 db
->busyHandler
.xBusyHandler
= xBusy
;
1724 db
->busyHandler
.pBusyArg
= pArg
;
1725 db
->busyHandler
.nBusy
= 0;
1726 db
->busyTimeout
= 0;
1727 sqlite3_mutex_leave(db
->mutex
);
1731 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
1733 ** This routine sets the progress callback for an Sqlite database to the
1734 ** given callback function with the given argument. The progress callback will
1735 ** be invoked every nOps opcodes.
1737 void sqlite3_progress_handler(
1740 int (*xProgress
)(void*),
1743 #ifdef SQLITE_ENABLE_API_ARMOR
1744 if( !sqlite3SafetyCheckOk(db
) ){
1745 (void)SQLITE_MISUSE_BKPT
;
1749 sqlite3_mutex_enter(db
->mutex
);
1751 db
->xProgress
= xProgress
;
1752 db
->nProgressOps
= (unsigned)nOps
;
1753 db
->pProgressArg
= pArg
;
1756 db
->nProgressOps
= 0;
1757 db
->pProgressArg
= 0;
1759 sqlite3_mutex_leave(db
->mutex
);
1765 ** This routine installs a default busy handler that waits for the
1766 ** specified number of milliseconds before returning 0.
1768 int sqlite3_busy_timeout(sqlite3
*db
, int ms
){
1769 #ifdef SQLITE_ENABLE_API_ARMOR
1770 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
1773 sqlite3_busy_handler(db
, (int(*)(void*,int))sqliteDefaultBusyCallback
,
1775 db
->busyTimeout
= ms
;
1777 sqlite3_busy_handler(db
, 0, 0);
1783 ** Cause any pending operation to stop at its earliest opportunity.
1785 void sqlite3_interrupt(sqlite3
*db
){
1786 #ifdef SQLITE_ENABLE_API_ARMOR
1787 if( !sqlite3SafetyCheckOk(db
) && (db
==0 || db
->magic
!=SQLITE_MAGIC_ZOMBIE
) ){
1788 (void)SQLITE_MISUSE_BKPT
;
1792 AtomicStore(&db
->u1
.isInterrupted
, 1);
1797 ** This function is exactly the same as sqlite3_create_function(), except
1798 ** that it is designed to be called by internal code. The difference is
1799 ** that if a malloc() fails in sqlite3_create_function(), an error code
1800 ** is returned and the mallocFailed flag cleared.
1802 int sqlite3CreateFunc(
1804 const char *zFunctionName
,
1808 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1809 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1810 void (*xFinal
)(sqlite3_context
*),
1811 void (*xValue
)(sqlite3_context
*),
1812 void (*xInverse
)(sqlite3_context
*,int,sqlite3_value
**),
1813 FuncDestructor
*pDestructor
1819 assert( sqlite3_mutex_held(db
->mutex
) );
1820 assert( xValue
==0 || xSFunc
==0 );
1821 if( zFunctionName
==0 /* Must have a valid name */
1822 || (xSFunc
!=0 && xFinal
!=0) /* Not both xSFunc and xFinal */
1823 || ((xFinal
==0)!=(xStep
==0)) /* Both or neither of xFinal and xStep */
1824 || ((xValue
==0)!=(xInverse
==0)) /* Both or neither of xValue, xInverse */
1825 || (nArg
<-1 || nArg
>SQLITE_MAX_FUNCTION_ARG
)
1826 || (255<(nName
= sqlite3Strlen30( zFunctionName
)))
1828 return SQLITE_MISUSE_BKPT
;
1831 assert( SQLITE_FUNC_CONSTANT
==SQLITE_DETERMINISTIC
);
1832 assert( SQLITE_FUNC_DIRECT
==SQLITE_DIRECTONLY
);
1833 extraFlags
= enc
& (SQLITE_DETERMINISTIC
|SQLITE_DIRECTONLY
|
1834 SQLITE_SUBTYPE
|SQLITE_INNOCUOUS
);
1835 enc
&= (SQLITE_FUNC_ENCMASK
|SQLITE_ANY
);
1837 /* The SQLITE_INNOCUOUS flag is the same bit as SQLITE_FUNC_UNSAFE. But
1838 ** the meaning is inverted. So flip the bit. */
1839 assert( SQLITE_FUNC_UNSAFE
==SQLITE_INNOCUOUS
);
1840 extraFlags
^= SQLITE_FUNC_UNSAFE
;
1843 #ifndef SQLITE_OMIT_UTF16
1844 /* If SQLITE_UTF16 is specified as the encoding type, transform this
1845 ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
1846 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
1848 ** If SQLITE_ANY is specified, add three versions of the function
1849 ** to the hash table.
1851 if( enc
==SQLITE_UTF16
){
1852 enc
= SQLITE_UTF16NATIVE
;
1853 }else if( enc
==SQLITE_ANY
){
1855 rc
= sqlite3CreateFunc(db
, zFunctionName
, nArg
,
1856 (SQLITE_UTF8
|extraFlags
)^SQLITE_FUNC_UNSAFE
,
1857 pUserData
, xSFunc
, xStep
, xFinal
, xValue
, xInverse
, pDestructor
);
1858 if( rc
==SQLITE_OK
){
1859 rc
= sqlite3CreateFunc(db
, zFunctionName
, nArg
,
1860 (SQLITE_UTF16LE
|extraFlags
)^SQLITE_FUNC_UNSAFE
,
1861 pUserData
, xSFunc
, xStep
, xFinal
, xValue
, xInverse
, pDestructor
);
1863 if( rc
!=SQLITE_OK
){
1866 enc
= SQLITE_UTF16BE
;
1872 /* Check if an existing function is being overridden or deleted. If so,
1873 ** and there are active VMs, then return SQLITE_BUSY. If a function
1874 ** is being overridden/deleted but there are no active VMs, allow the
1875 ** operation to continue but invalidate all precompiled statements.
1877 p
= sqlite3FindFunction(db
, zFunctionName
, nArg
, (u8
)enc
, 0);
1878 if( p
&& (p
->funcFlags
& SQLITE_FUNC_ENCMASK
)==(u32
)enc
&& p
->nArg
==nArg
){
1879 if( db
->nVdbeActive
){
1880 sqlite3ErrorWithMsg(db
, SQLITE_BUSY
,
1881 "unable to delete/modify user-function due to active statements");
1882 assert( !db
->mallocFailed
);
1885 sqlite3ExpirePreparedStatements(db
, 0);
1887 }else if( xSFunc
==0 && xFinal
==0 ){
1888 /* Trying to delete a function that does not exist. This is a no-op.
1889 ** https://sqlite.org/forum/forumpost/726219164b */
1893 p
= sqlite3FindFunction(db
, zFunctionName
, nArg
, (u8
)enc
, 1);
1894 assert(p
|| db
->mallocFailed
);
1896 return SQLITE_NOMEM_BKPT
;
1899 /* If an older version of the function with a configured destructor is
1900 ** being replaced invoke the destructor function here. */
1901 functionDestroy(db
, p
);
1904 pDestructor
->nRef
++;
1906 p
->u
.pDestructor
= pDestructor
;
1907 p
->funcFlags
= (p
->funcFlags
& SQLITE_FUNC_ENCMASK
) | extraFlags
;
1908 testcase( p
->funcFlags
& SQLITE_DETERMINISTIC
);
1909 testcase( p
->funcFlags
& SQLITE_DIRECTONLY
);
1910 p
->xSFunc
= xSFunc
? xSFunc
: xStep
;
1911 p
->xFinalize
= xFinal
;
1913 p
->xInverse
= xInverse
;
1914 p
->pUserData
= pUserData
;
1915 p
->nArg
= (u16
)nArg
;
1920 ** Worker function used by utf-8 APIs that create new functions:
1922 ** sqlite3_create_function()
1923 ** sqlite3_create_function_v2()
1924 ** sqlite3_create_window_function()
1926 static int createFunctionApi(
1932 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1933 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1934 void (*xFinal
)(sqlite3_context
*),
1935 void (*xValue
)(sqlite3_context
*),
1936 void (*xInverse
)(sqlite3_context
*,int,sqlite3_value
**),
1937 void(*xDestroy
)(void*)
1939 int rc
= SQLITE_ERROR
;
1940 FuncDestructor
*pArg
= 0;
1942 #ifdef SQLITE_ENABLE_API_ARMOR
1943 if( !sqlite3SafetyCheckOk(db
) ){
1944 return SQLITE_MISUSE_BKPT
;
1947 sqlite3_mutex_enter(db
->mutex
);
1949 pArg
= (FuncDestructor
*)sqlite3Malloc(sizeof(FuncDestructor
));
1951 sqlite3OomFault(db
);
1956 pArg
->xDestroy
= xDestroy
;
1957 pArg
->pUserData
= p
;
1959 rc
= sqlite3CreateFunc(db
, zFunc
, nArg
, enc
, p
,
1960 xSFunc
, xStep
, xFinal
, xValue
, xInverse
, pArg
1962 if( pArg
&& pArg
->nRef
==0 ){
1963 assert( rc
!=SQLITE_OK
);
1969 rc
= sqlite3ApiExit(db
, rc
);
1970 sqlite3_mutex_leave(db
->mutex
);
1975 ** Create new user functions.
1977 int sqlite3_create_function(
1983 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1984 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1985 void (*xFinal
)(sqlite3_context
*)
1987 return createFunctionApi(db
, zFunc
, nArg
, enc
, p
, xSFunc
, xStep
,
1990 int sqlite3_create_function_v2(
1996 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1997 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1998 void (*xFinal
)(sqlite3_context
*),
1999 void (*xDestroy
)(void *)
2001 return createFunctionApi(db
, zFunc
, nArg
, enc
, p
, xSFunc
, xStep
,
2002 xFinal
, 0, 0, xDestroy
);
2004 int sqlite3_create_window_function(
2010 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
2011 void (*xFinal
)(sqlite3_context
*),
2012 void (*xValue
)(sqlite3_context
*),
2013 void (*xInverse
)(sqlite3_context
*,int,sqlite3_value
**),
2014 void (*xDestroy
)(void *)
2016 return createFunctionApi(db
, zFunc
, nArg
, enc
, p
, 0, xStep
,
2017 xFinal
, xValue
, xInverse
, xDestroy
);
2020 #ifndef SQLITE_OMIT_UTF16
2021 int sqlite3_create_function16(
2023 const void *zFunctionName
,
2027 void (*xSFunc
)(sqlite3_context
*,int,sqlite3_value
**),
2028 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
2029 void (*xFinal
)(sqlite3_context
*)
2034 #ifdef SQLITE_ENABLE_API_ARMOR
2035 if( !sqlite3SafetyCheckOk(db
) || zFunctionName
==0 ) return SQLITE_MISUSE_BKPT
;
2037 sqlite3_mutex_enter(db
->mutex
);
2038 assert( !db
->mallocFailed
);
2039 zFunc8
= sqlite3Utf16to8(db
, zFunctionName
, -1, SQLITE_UTF16NATIVE
);
2040 rc
= sqlite3CreateFunc(db
, zFunc8
, nArg
, eTextRep
, p
, xSFunc
,xStep
,xFinal
,0,0,0);
2041 sqlite3DbFree(db
, zFunc8
);
2042 rc
= sqlite3ApiExit(db
, rc
);
2043 sqlite3_mutex_leave(db
->mutex
);
2050 ** The following is the implementation of an SQL function that always
2051 ** fails with an error message stating that the function is used in the
2052 ** wrong context. The sqlite3_overload_function() API might construct
2053 ** SQL function that use this routine so that the functions will exist
2054 ** for name resolution but are actually overloaded by the xFindFunction
2055 ** method of virtual tables.
2057 static void sqlite3InvalidFunction(
2058 sqlite3_context
*context
, /* The function calling context */
2059 int NotUsed
, /* Number of arguments to the function */
2060 sqlite3_value
**NotUsed2
/* Value of each argument */
2062 const char *zName
= (const char*)sqlite3_user_data(context
);
2064 UNUSED_PARAMETER2(NotUsed
, NotUsed2
);
2065 zErr
= sqlite3_mprintf(
2066 "unable to use function %s in the requested context", zName
);
2067 sqlite3_result_error(context
, zErr
, -1);
2072 ** Declare that a function has been overloaded by a virtual table.
2074 ** If the function already exists as a regular global function, then
2075 ** this routine is a no-op. If the function does not exist, then create
2076 ** a new one that always throws a run-time error.
2078 ** When virtual tables intend to provide an overloaded function, they
2079 ** should call this routine to make sure the global function exists.
2080 ** A global function must exist in order for name resolution to work
2083 int sqlite3_overload_function(
2091 #ifdef SQLITE_ENABLE_API_ARMOR
2092 if( !sqlite3SafetyCheckOk(db
) || zName
==0 || nArg
<-2 ){
2093 return SQLITE_MISUSE_BKPT
;
2096 sqlite3_mutex_enter(db
->mutex
);
2097 rc
= sqlite3FindFunction(db
, zName
, nArg
, SQLITE_UTF8
, 0)!=0;
2098 sqlite3_mutex_leave(db
->mutex
);
2099 if( rc
) return SQLITE_OK
;
2100 zCopy
= sqlite3_mprintf(zName
);
2101 if( zCopy
==0 ) return SQLITE_NOMEM
;
2102 return sqlite3_create_function_v2(db
, zName
, nArg
, SQLITE_UTF8
,
2103 zCopy
, sqlite3InvalidFunction
, 0, 0, sqlite3_free
);
2106 #ifndef SQLITE_OMIT_TRACE
2108 ** Register a trace function. The pArg from the previously registered trace
2111 ** A NULL trace function means that no tracing is executes. A non-NULL
2112 ** trace is a pointer to a function that is invoked at the start of each
2115 #ifndef SQLITE_OMIT_DEPRECATED
2116 void *sqlite3_trace(sqlite3
*db
, void(*xTrace
)(void*,const char*), void *pArg
){
2119 #ifdef SQLITE_ENABLE_API_ARMOR
2120 if( !sqlite3SafetyCheckOk(db
) ){
2121 (void)SQLITE_MISUSE_BKPT
;
2125 sqlite3_mutex_enter(db
->mutex
);
2126 pOld
= db
->pTraceArg
;
2127 db
->mTrace
= xTrace
? SQLITE_TRACE_LEGACY
: 0;
2128 db
->trace
.xLegacy
= xTrace
;
2129 db
->pTraceArg
= pArg
;
2130 sqlite3_mutex_leave(db
->mutex
);
2133 #endif /* SQLITE_OMIT_DEPRECATED */
2135 /* Register a trace callback using the version-2 interface.
2137 int sqlite3_trace_v2(
2138 sqlite3
*db
, /* Trace this connection */
2139 unsigned mTrace
, /* Mask of events to be traced */
2140 int(*xTrace
)(unsigned,void*,void*,void*), /* Callback to invoke */
2141 void *pArg
/* Context */
2143 #ifdef SQLITE_ENABLE_API_ARMOR
2144 if( !sqlite3SafetyCheckOk(db
) ){
2145 return SQLITE_MISUSE_BKPT
;
2148 sqlite3_mutex_enter(db
->mutex
);
2149 if( mTrace
==0 ) xTrace
= 0;
2150 if( xTrace
==0 ) mTrace
= 0;
2151 db
->mTrace
= mTrace
;
2152 db
->trace
.xV2
= xTrace
;
2153 db
->pTraceArg
= pArg
;
2154 sqlite3_mutex_leave(db
->mutex
);
2158 #ifndef SQLITE_OMIT_DEPRECATED
2160 ** Register a profile function. The pArg from the previously registered
2161 ** profile function is returned.
2163 ** A NULL profile function means that no profiling is executes. A non-NULL
2164 ** profile is a pointer to a function that is invoked at the conclusion of
2165 ** each SQL statement that is run.
2167 void *sqlite3_profile(
2169 void (*xProfile
)(void*,const char*,sqlite_uint64
),
2174 #ifdef SQLITE_ENABLE_API_ARMOR
2175 if( !sqlite3SafetyCheckOk(db
) ){
2176 (void)SQLITE_MISUSE_BKPT
;
2180 sqlite3_mutex_enter(db
->mutex
);
2181 pOld
= db
->pProfileArg
;
2182 db
->xProfile
= xProfile
;
2183 db
->pProfileArg
= pArg
;
2184 db
->mTrace
&= SQLITE_TRACE_NONLEGACY_MASK
;
2185 if( db
->xProfile
) db
->mTrace
|= SQLITE_TRACE_XPROFILE
;
2186 sqlite3_mutex_leave(db
->mutex
);
2189 #endif /* SQLITE_OMIT_DEPRECATED */
2190 #endif /* SQLITE_OMIT_TRACE */
2193 ** Register a function to be invoked when a transaction commits.
2194 ** If the invoked function returns non-zero, then the commit becomes a
2197 void *sqlite3_commit_hook(
2198 sqlite3
*db
, /* Attach the hook to this database */
2199 int (*xCallback
)(void*), /* Function to invoke on each commit */
2200 void *pArg
/* Argument to the function */
2204 #ifdef SQLITE_ENABLE_API_ARMOR
2205 if( !sqlite3SafetyCheckOk(db
) ){
2206 (void)SQLITE_MISUSE_BKPT
;
2210 sqlite3_mutex_enter(db
->mutex
);
2211 pOld
= db
->pCommitArg
;
2212 db
->xCommitCallback
= xCallback
;
2213 db
->pCommitArg
= pArg
;
2214 sqlite3_mutex_leave(db
->mutex
);
2219 ** Register a callback to be invoked each time a row is updated,
2220 ** inserted or deleted using this database connection.
2222 void *sqlite3_update_hook(
2223 sqlite3
*db
, /* Attach the hook to this database */
2224 void (*xCallback
)(void*,int,char const *,char const *,sqlite_int64
),
2225 void *pArg
/* Argument to the function */
2229 #ifdef SQLITE_ENABLE_API_ARMOR
2230 if( !sqlite3SafetyCheckOk(db
) ){
2231 (void)SQLITE_MISUSE_BKPT
;
2235 sqlite3_mutex_enter(db
->mutex
);
2236 pRet
= db
->pUpdateArg
;
2237 db
->xUpdateCallback
= xCallback
;
2238 db
->pUpdateArg
= pArg
;
2239 sqlite3_mutex_leave(db
->mutex
);
2244 ** Register a callback to be invoked each time a transaction is rolled
2245 ** back by this database connection.
2247 void *sqlite3_rollback_hook(
2248 sqlite3
*db
, /* Attach the hook to this database */
2249 void (*xCallback
)(void*), /* Callback function */
2250 void *pArg
/* Argument to the function */
2254 #ifdef SQLITE_ENABLE_API_ARMOR
2255 if( !sqlite3SafetyCheckOk(db
) ){
2256 (void)SQLITE_MISUSE_BKPT
;
2260 sqlite3_mutex_enter(db
->mutex
);
2261 pRet
= db
->pRollbackArg
;
2262 db
->xRollbackCallback
= xCallback
;
2263 db
->pRollbackArg
= pArg
;
2264 sqlite3_mutex_leave(db
->mutex
);
2268 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
2270 ** Register a callback to be invoked each time a row is updated,
2271 ** inserted or deleted using this database connection.
2273 void *sqlite3_preupdate_hook(
2274 sqlite3
*db
, /* Attach the hook to this database */
2275 void(*xCallback
)( /* Callback function */
2276 void*,sqlite3
*,int,char const*,char const*,sqlite3_int64
,sqlite3_int64
),
2277 void *pArg
/* First callback argument */
2280 sqlite3_mutex_enter(db
->mutex
);
2281 pRet
= db
->pPreUpdateArg
;
2282 db
->xPreUpdateCallback
= xCallback
;
2283 db
->pPreUpdateArg
= pArg
;
2284 sqlite3_mutex_leave(db
->mutex
);
2287 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
2289 #ifndef SQLITE_OMIT_WAL
2291 ** The sqlite3_wal_hook() callback registered by sqlite3_wal_autocheckpoint().
2292 ** Invoke sqlite3_wal_checkpoint if the number of frames in the log file
2293 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
2294 ** wal_autocheckpoint()).
2296 int sqlite3WalDefaultHook(
2297 void *pClientData
, /* Argument */
2298 sqlite3
*db
, /* Connection */
2299 const char *zDb
, /* Database */
2300 int nFrame
/* Size of WAL */
2302 if( nFrame
>=SQLITE_PTR_TO_INT(pClientData
) ){
2303 sqlite3BeginBenignMalloc();
2304 sqlite3_wal_checkpoint(db
, zDb
);
2305 sqlite3EndBenignMalloc();
2309 #endif /* SQLITE_OMIT_WAL */
2312 ** Configure an sqlite3_wal_hook() callback to automatically checkpoint
2313 ** a database after committing a transaction if there are nFrame or
2314 ** more frames in the log file. Passing zero or a negative value as the
2315 ** nFrame parameter disables automatic checkpoints entirely.
2317 ** The callback registered by this function replaces any existing callback
2318 ** registered using sqlite3_wal_hook(). Likewise, registering a callback
2319 ** using sqlite3_wal_hook() disables the automatic checkpoint mechanism
2320 ** configured by this function.
2322 int sqlite3_wal_autocheckpoint(sqlite3
*db
, int nFrame
){
2323 #ifdef SQLITE_OMIT_WAL
2324 UNUSED_PARAMETER(db
);
2325 UNUSED_PARAMETER(nFrame
);
2327 #ifdef SQLITE_ENABLE_API_ARMOR
2328 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
2331 sqlite3_wal_hook(db
, sqlite3WalDefaultHook
, SQLITE_INT_TO_PTR(nFrame
));
2333 sqlite3_wal_hook(db
, 0, 0);
2340 ** Register a callback to be invoked each time a transaction is written
2341 ** into the write-ahead-log by this database connection.
2343 void *sqlite3_wal_hook(
2344 sqlite3
*db
, /* Attach the hook to this db handle */
2345 int(*xCallback
)(void *, sqlite3
*, const char*, int),
2346 void *pArg
/* First argument passed to xCallback() */
2348 #ifndef SQLITE_OMIT_WAL
2350 #ifdef SQLITE_ENABLE_API_ARMOR
2351 if( !sqlite3SafetyCheckOk(db
) ){
2352 (void)SQLITE_MISUSE_BKPT
;
2356 sqlite3_mutex_enter(db
->mutex
);
2358 db
->xWalCallback
= xCallback
;
2360 sqlite3_mutex_leave(db
->mutex
);
2368 ** Checkpoint database zDb.
2370 int sqlite3_wal_checkpoint_v2(
2371 sqlite3
*db
, /* Database handle */
2372 const char *zDb
, /* Name of attached database (or NULL) */
2373 int eMode
, /* SQLITE_CHECKPOINT_* value */
2374 int *pnLog
, /* OUT: Size of WAL log in frames */
2375 int *pnCkpt
/* OUT: Total number of frames checkpointed */
2377 #ifdef SQLITE_OMIT_WAL
2380 int rc
; /* Return code */
2381 int iDb
; /* Schema to checkpoint */
2383 #ifdef SQLITE_ENABLE_API_ARMOR
2384 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
2387 /* Initialize the output variables to -1 in case an error occurs. */
2388 if( pnLog
) *pnLog
= -1;
2389 if( pnCkpt
) *pnCkpt
= -1;
2391 assert( SQLITE_CHECKPOINT_PASSIVE
==0 );
2392 assert( SQLITE_CHECKPOINT_FULL
==1 );
2393 assert( SQLITE_CHECKPOINT_RESTART
==2 );
2394 assert( SQLITE_CHECKPOINT_TRUNCATE
==3 );
2395 if( eMode
<SQLITE_CHECKPOINT_PASSIVE
|| eMode
>SQLITE_CHECKPOINT_TRUNCATE
){
2396 /* EVIDENCE-OF: R-03996-12088 The M parameter must be a valid checkpoint
2398 return SQLITE_MISUSE
;
2401 sqlite3_mutex_enter(db
->mutex
);
2402 if( zDb
&& zDb
[0] ){
2403 iDb
= sqlite3FindDbName(db
, zDb
);
2405 iDb
= SQLITE_MAX_DB
; /* This means process all schemas */
2409 sqlite3ErrorWithMsg(db
, SQLITE_ERROR
, "unknown database: %s", zDb
);
2411 db
->busyHandler
.nBusy
= 0;
2412 rc
= sqlite3Checkpoint(db
, iDb
, eMode
, pnLog
, pnCkpt
);
2413 sqlite3Error(db
, rc
);
2415 rc
= sqlite3ApiExit(db
, rc
);
2417 /* If there are no active statements, clear the interrupt flag at this
2419 if( db
->nVdbeActive
==0 ){
2420 AtomicStore(&db
->u1
.isInterrupted
, 0);
2423 sqlite3_mutex_leave(db
->mutex
);
2430 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
2431 ** to contains a zero-length string, all attached databases are
2434 int sqlite3_wal_checkpoint(sqlite3
*db
, const char *zDb
){
2435 /* EVIDENCE-OF: R-41613-20553 The sqlite3_wal_checkpoint(D,X) is equivalent to
2436 ** sqlite3_wal_checkpoint_v2(D,X,SQLITE_CHECKPOINT_PASSIVE,0,0). */
2437 return sqlite3_wal_checkpoint_v2(db
,zDb
,SQLITE_CHECKPOINT_PASSIVE
,0,0);
2440 #ifndef SQLITE_OMIT_WAL
2442 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
2443 ** not currently open in WAL mode.
2445 ** If a transaction is open on the database being checkpointed, this
2446 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If
2447 ** an error occurs while running the checkpoint, an SQLite error code is
2448 ** returned (i.e. SQLITE_IOERR). Otherwise, SQLITE_OK.
2450 ** The mutex on database handle db should be held by the caller. The mutex
2451 ** associated with the specific b-tree being checkpointed is taken by
2452 ** this function while the checkpoint is running.
2454 ** If iDb is passed SQLITE_MAX_DB then all attached databases are
2455 ** checkpointed. If an error is encountered it is returned immediately -
2456 ** no attempt is made to checkpoint any remaining databases.
2458 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL, RESTART
2461 int sqlite3Checkpoint(sqlite3
*db
, int iDb
, int eMode
, int *pnLog
, int *pnCkpt
){
2462 int rc
= SQLITE_OK
; /* Return code */
2463 int i
; /* Used to iterate through attached dbs */
2464 int bBusy
= 0; /* True if SQLITE_BUSY has been encountered */
2466 assert( sqlite3_mutex_held(db
->mutex
) );
2467 assert( !pnLog
|| *pnLog
==-1 );
2468 assert( !pnCkpt
|| *pnCkpt
==-1 );
2469 testcase( iDb
==SQLITE_MAX_ATTACHED
); /* See forum post a006d86f72 */
2470 testcase( iDb
==SQLITE_MAX_DB
);
2472 for(i
=0; i
<db
->nDb
&& rc
==SQLITE_OK
; i
++){
2473 if( i
==iDb
|| iDb
==SQLITE_MAX_DB
){
2474 rc
= sqlite3BtreeCheckpoint(db
->aDb
[i
].pBt
, eMode
, pnLog
, pnCkpt
);
2477 if( rc
==SQLITE_BUSY
){
2484 return (rc
==SQLITE_OK
&& bBusy
) ? SQLITE_BUSY
: rc
;
2486 #endif /* SQLITE_OMIT_WAL */
2489 ** This function returns true if main-memory should be used instead of
2490 ** a temporary file for transient pager files and statement journals.
2491 ** The value returned depends on the value of db->temp_store (runtime
2492 ** parameter) and the compile time value of SQLITE_TEMP_STORE. The
2493 ** following table describes the relationship between these two values
2494 ** and this functions return value.
2496 ** SQLITE_TEMP_STORE db->temp_store Location of temporary database
2497 ** ----------------- -------------- ------------------------------
2498 ** 0 any file (return 0)
2499 ** 1 1 file (return 0)
2500 ** 1 2 memory (return 1)
2501 ** 1 0 file (return 0)
2502 ** 2 1 file (return 0)
2503 ** 2 2 memory (return 1)
2504 ** 2 0 memory (return 1)
2505 ** 3 any memory (return 1)
2507 int sqlite3TempInMemory(const sqlite3
*db
){
2508 #if SQLITE_TEMP_STORE==1
2509 return ( db
->temp_store
==2 );
2511 #if SQLITE_TEMP_STORE==2
2512 return ( db
->temp_store
!=1 );
2514 #if SQLITE_TEMP_STORE==3
2515 UNUSED_PARAMETER(db
);
2518 #if SQLITE_TEMP_STORE<1 || SQLITE_TEMP_STORE>3
2519 UNUSED_PARAMETER(db
);
2525 ** Return UTF-8 encoded English language explanation of the most recent
2528 const char *sqlite3_errmsg(sqlite3
*db
){
2531 return sqlite3ErrStr(SQLITE_NOMEM_BKPT
);
2533 if( !sqlite3SafetyCheckSickOrOk(db
) ){
2534 return sqlite3ErrStr(SQLITE_MISUSE_BKPT
);
2536 sqlite3_mutex_enter(db
->mutex
);
2537 if( db
->mallocFailed
){
2538 z
= sqlite3ErrStr(SQLITE_NOMEM_BKPT
);
2540 testcase( db
->pErr
==0 );
2541 z
= db
->errCode
? (char*)sqlite3_value_text(db
->pErr
) : 0;
2542 assert( !db
->mallocFailed
);
2544 z
= sqlite3ErrStr(db
->errCode
);
2547 sqlite3_mutex_leave(db
->mutex
);
2551 #ifndef SQLITE_OMIT_UTF16
2553 ** Return UTF-16 encoded English language explanation of the most recent
2556 const void *sqlite3_errmsg16(sqlite3
*db
){
2557 static const u16 outOfMem
[] = {
2558 'o', 'u', 't', ' ', 'o', 'f', ' ', 'm', 'e', 'm', 'o', 'r', 'y', 0
2560 static const u16 misuse
[] = {
2561 'b', 'a', 'd', ' ', 'p', 'a', 'r', 'a', 'm', 'e', 't', 'e', 'r', ' ',
2562 'o', 'r', ' ', 'o', 't', 'h', 'e', 'r', ' ', 'A', 'P', 'I', ' ',
2563 'm', 'i', 's', 'u', 's', 'e', 0
2568 return (void *)outOfMem
;
2570 if( !sqlite3SafetyCheckSickOrOk(db
) ){
2571 return (void *)misuse
;
2573 sqlite3_mutex_enter(db
->mutex
);
2574 if( db
->mallocFailed
){
2575 z
= (void *)outOfMem
;
2577 z
= sqlite3_value_text16(db
->pErr
);
2579 sqlite3ErrorWithMsg(db
, db
->errCode
, sqlite3ErrStr(db
->errCode
));
2580 z
= sqlite3_value_text16(db
->pErr
);
2582 /* A malloc() may have failed within the call to sqlite3_value_text16()
2583 ** above. If this is the case, then the db->mallocFailed flag needs to
2584 ** be cleared before returning. Do this directly, instead of via
2585 ** sqlite3ApiExit(), to avoid setting the database handle error message.
2587 sqlite3OomClear(db
);
2589 sqlite3_mutex_leave(db
->mutex
);
2592 #endif /* SQLITE_OMIT_UTF16 */
2595 ** Return the most recent error code generated by an SQLite routine. If NULL is
2596 ** passed to this function, we assume a malloc() failed during sqlite3_open().
2598 int sqlite3_errcode(sqlite3
*db
){
2599 if( db
&& !sqlite3SafetyCheckSickOrOk(db
) ){
2600 return SQLITE_MISUSE_BKPT
;
2602 if( !db
|| db
->mallocFailed
){
2603 return SQLITE_NOMEM_BKPT
;
2605 return db
->errCode
& db
->errMask
;
2607 int sqlite3_extended_errcode(sqlite3
*db
){
2608 if( db
&& !sqlite3SafetyCheckSickOrOk(db
) ){
2609 return SQLITE_MISUSE_BKPT
;
2611 if( !db
|| db
->mallocFailed
){
2612 return SQLITE_NOMEM_BKPT
;
2616 int sqlite3_system_errno(sqlite3
*db
){
2617 return db
? db
->iSysErrno
: 0;
2621 ** Return a string that describes the kind of error specified in the
2622 ** argument. For now, this simply calls the internal sqlite3ErrStr()
2625 const char *sqlite3_errstr(int rc
){
2626 return sqlite3ErrStr(rc
);
2630 ** Create a new collating function for database "db". The name is zName
2631 ** and the encoding is enc.
2633 static int createCollation(
2638 int(*xCompare
)(void*,int,const void*,int,const void*),
2644 assert( sqlite3_mutex_held(db
->mutex
) );
2646 /* If SQLITE_UTF16 is specified as the encoding type, transform this
2647 ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
2648 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
2651 testcase( enc2
==SQLITE_UTF16
);
2652 testcase( enc2
==SQLITE_UTF16_ALIGNED
);
2653 if( enc2
==SQLITE_UTF16
|| enc2
==SQLITE_UTF16_ALIGNED
){
2654 enc2
= SQLITE_UTF16NATIVE
;
2656 if( enc2
<SQLITE_UTF8
|| enc2
>SQLITE_UTF16BE
){
2657 return SQLITE_MISUSE_BKPT
;
2660 /* Check if this call is removing or replacing an existing collation
2661 ** sequence. If so, and there are active VMs, return busy. If there
2662 ** are no active VMs, invalidate any pre-compiled statements.
2664 pColl
= sqlite3FindCollSeq(db
, (u8
)enc2
, zName
, 0);
2665 if( pColl
&& pColl
->xCmp
){
2666 if( db
->nVdbeActive
){
2667 sqlite3ErrorWithMsg(db
, SQLITE_BUSY
,
2668 "unable to delete/modify collation sequence due to active statements");
2671 sqlite3ExpirePreparedStatements(db
, 0);
2673 /* If collation sequence pColl was created directly by a call to
2674 ** sqlite3_create_collation, and not generated by synthCollSeq(),
2675 ** then any copies made by synthCollSeq() need to be invalidated.
2676 ** Also, collation destructor - CollSeq.xDel() - function may need
2679 if( (pColl
->enc
& ~SQLITE_UTF16_ALIGNED
)==enc2
){
2680 CollSeq
*aColl
= sqlite3HashFind(&db
->aCollSeq
, zName
);
2683 CollSeq
*p
= &aColl
[j
];
2684 if( p
->enc
==pColl
->enc
){
2694 pColl
= sqlite3FindCollSeq(db
, (u8
)enc2
, zName
, 1);
2695 if( pColl
==0 ) return SQLITE_NOMEM_BKPT
;
2696 pColl
->xCmp
= xCompare
;
2697 pColl
->pUser
= pCtx
;
2699 pColl
->enc
= (u8
)(enc2
| (enc
& SQLITE_UTF16_ALIGNED
));
2700 sqlite3Error(db
, SQLITE_OK
);
2706 ** This array defines hard upper bounds on limit values. The
2707 ** initializer must be kept in sync with the SQLITE_LIMIT_*
2708 ** #defines in sqlite3.h.
2710 static const int aHardLimit
[] = {
2712 SQLITE_MAX_SQL_LENGTH
,
2714 SQLITE_MAX_EXPR_DEPTH
,
2715 SQLITE_MAX_COMPOUND_SELECT
,
2717 SQLITE_MAX_FUNCTION_ARG
,
2718 SQLITE_MAX_ATTACHED
,
2719 SQLITE_MAX_LIKE_PATTERN_LENGTH
,
2720 SQLITE_MAX_VARIABLE_NUMBER
, /* IMP: R-38091-32352 */
2721 SQLITE_MAX_TRIGGER_DEPTH
,
2722 SQLITE_MAX_WORKER_THREADS
,
2726 ** Make sure the hard limits are set to reasonable values
2728 #if SQLITE_MAX_LENGTH<100
2729 # error SQLITE_MAX_LENGTH must be at least 100
2731 #if SQLITE_MAX_SQL_LENGTH<100
2732 # error SQLITE_MAX_SQL_LENGTH must be at least 100
2734 #if SQLITE_MAX_SQL_LENGTH>SQLITE_MAX_LENGTH
2735 # error SQLITE_MAX_SQL_LENGTH must not be greater than SQLITE_MAX_LENGTH
2737 #if SQLITE_MAX_COMPOUND_SELECT<2
2738 # error SQLITE_MAX_COMPOUND_SELECT must be at least 2
2740 #if SQLITE_MAX_VDBE_OP<40
2741 # error SQLITE_MAX_VDBE_OP must be at least 40
2743 #if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>127
2744 # error SQLITE_MAX_FUNCTION_ARG must be between 0 and 127
2746 #if SQLITE_MAX_ATTACHED<0 || SQLITE_MAX_ATTACHED>125
2747 # error SQLITE_MAX_ATTACHED must be between 0 and 125
2749 #if SQLITE_MAX_LIKE_PATTERN_LENGTH<1
2750 # error SQLITE_MAX_LIKE_PATTERN_LENGTH must be at least 1
2752 #if SQLITE_MAX_COLUMN>32767
2753 # error SQLITE_MAX_COLUMN must not exceed 32767
2755 #if SQLITE_MAX_TRIGGER_DEPTH<1
2756 # error SQLITE_MAX_TRIGGER_DEPTH must be at least 1
2758 #if SQLITE_MAX_WORKER_THREADS<0 || SQLITE_MAX_WORKER_THREADS>50
2759 # error SQLITE_MAX_WORKER_THREADS must be between 0 and 50
2764 ** Change the value of a limit. Report the old value.
2765 ** If an invalid limit index is supplied, report -1.
2766 ** Make no changes but still report the old value if the
2767 ** new limit is negative.
2769 ** A new lower limit does not shrink existing constructs.
2770 ** It merely prevents new constructs that exceed the limit
2773 int sqlite3_limit(sqlite3
*db
, int limitId
, int newLimit
){
2776 #ifdef SQLITE_ENABLE_API_ARMOR
2777 if( !sqlite3SafetyCheckOk(db
) ){
2778 (void)SQLITE_MISUSE_BKPT
;
2783 /* EVIDENCE-OF: R-30189-54097 For each limit category SQLITE_LIMIT_NAME
2784 ** there is a hard upper bound set at compile-time by a C preprocessor
2785 ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
2788 assert( aHardLimit
[SQLITE_LIMIT_LENGTH
]==SQLITE_MAX_LENGTH
);
2789 assert( aHardLimit
[SQLITE_LIMIT_SQL_LENGTH
]==SQLITE_MAX_SQL_LENGTH
);
2790 assert( aHardLimit
[SQLITE_LIMIT_COLUMN
]==SQLITE_MAX_COLUMN
);
2791 assert( aHardLimit
[SQLITE_LIMIT_EXPR_DEPTH
]==SQLITE_MAX_EXPR_DEPTH
);
2792 assert( aHardLimit
[SQLITE_LIMIT_COMPOUND_SELECT
]==SQLITE_MAX_COMPOUND_SELECT
);
2793 assert( aHardLimit
[SQLITE_LIMIT_VDBE_OP
]==SQLITE_MAX_VDBE_OP
);
2794 assert( aHardLimit
[SQLITE_LIMIT_FUNCTION_ARG
]==SQLITE_MAX_FUNCTION_ARG
);
2795 assert( aHardLimit
[SQLITE_LIMIT_ATTACHED
]==SQLITE_MAX_ATTACHED
);
2796 assert( aHardLimit
[SQLITE_LIMIT_LIKE_PATTERN_LENGTH
]==
2797 SQLITE_MAX_LIKE_PATTERN_LENGTH
);
2798 assert( aHardLimit
[SQLITE_LIMIT_VARIABLE_NUMBER
]==SQLITE_MAX_VARIABLE_NUMBER
);
2799 assert( aHardLimit
[SQLITE_LIMIT_TRIGGER_DEPTH
]==SQLITE_MAX_TRIGGER_DEPTH
);
2800 assert( aHardLimit
[SQLITE_LIMIT_WORKER_THREADS
]==SQLITE_MAX_WORKER_THREADS
);
2801 assert( SQLITE_LIMIT_WORKER_THREADS
==(SQLITE_N_LIMIT
-1) );
2804 if( limitId
<0 || limitId
>=SQLITE_N_LIMIT
){
2807 oldLimit
= db
->aLimit
[limitId
];
2808 if( newLimit
>=0 ){ /* IMP: R-52476-28732 */
2809 if( newLimit
>aHardLimit
[limitId
] ){
2810 newLimit
= aHardLimit
[limitId
]; /* IMP: R-51463-25634 */
2812 db
->aLimit
[limitId
] = newLimit
;
2814 return oldLimit
; /* IMP: R-53341-35419 */
2818 ** This function is used to parse both URIs and non-URI filenames passed by the
2819 ** user to API functions sqlite3_open() or sqlite3_open_v2(), and for database
2820 ** URIs specified as part of ATTACH statements.
2822 ** The first argument to this function is the name of the VFS to use (or
2823 ** a NULL to signify the default VFS) if the URI does not contain a "vfs=xxx"
2824 ** query parameter. The second argument contains the URI (or non-URI filename)
2825 ** itself. When this function is called the *pFlags variable should contain
2826 ** the default flags to open the database handle with. The value stored in
2827 ** *pFlags may be updated before returning if the URI filename contains
2828 ** "cache=xxx" or "mode=xxx" query parameters.
2830 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
2831 ** the VFS that should be used to open the database file. *pzFile is set to
2832 ** point to a buffer containing the name of the file to open. The value
2833 ** stored in *pzFile is a database name acceptable to sqlite3_uri_parameter()
2834 ** and is in the same format as names created using sqlite3_create_filename().
2835 ** The caller must invoke sqlite3_free_filename() (not sqlite3_free()!) on
2836 ** the value returned in *pzFile to avoid a memory leak.
2838 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
2839 ** may be set to point to a buffer containing an English language error
2840 ** message. It is the responsibility of the caller to eventually release
2841 ** this buffer by calling sqlite3_free().
2843 int sqlite3ParseUri(
2844 const char *zDefaultVfs
, /* VFS to use if no "vfs=xxx" query option */
2845 const char *zUri
, /* Nul-terminated URI to parse */
2846 unsigned int *pFlags
, /* IN/OUT: SQLITE_OPEN_XXX flags */
2847 sqlite3_vfs
**ppVfs
, /* OUT: VFS to use */
2848 char **pzFile
, /* OUT: Filename component of URI */
2849 char **pzErrMsg
/* OUT: Error message (if rc!=SQLITE_OK) */
2852 unsigned int flags
= *pFlags
;
2853 const char *zVfs
= zDefaultVfs
;
2856 int nUri
= sqlite3Strlen30(zUri
);
2858 assert( *pzErrMsg
==0 );
2860 if( ((flags
& SQLITE_OPEN_URI
) /* IMP: R-48725-32206 */
2861 || sqlite3GlobalConfig
.bOpenUri
) /* IMP: R-51689-46548 */
2862 && nUri
>=5 && memcmp(zUri
, "file:", 5)==0 /* IMP: R-57884-37496 */
2865 int eState
; /* Parser state when parsing URI */
2866 int iIn
; /* Input character index */
2867 int iOut
= 0; /* Output character index */
2868 u64 nByte
= nUri
+8; /* Bytes of space to allocate */
2870 /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen
2871 ** method that there may be extra parameters following the file-name. */
2872 flags
|= SQLITE_OPEN_URI
;
2874 for(iIn
=0; iIn
<nUri
; iIn
++) nByte
+= (zUri
[iIn
]=='&');
2875 zFile
= sqlite3_malloc64(nByte
);
2876 if( !zFile
) return SQLITE_NOMEM_BKPT
;
2878 memset(zFile
, 0, 4); /* 4-byte of 0x00 is the start of DB name marker */
2882 #ifdef SQLITE_ALLOW_URI_AUTHORITY
2883 if( strncmp(zUri
+5, "///", 3)==0 ){
2885 /* The following condition causes URIs with five leading / characters
2886 ** like file://///host/path to be converted into UNCs like //host/path.
2887 ** The correct URI for that UNC has only two or four leading / characters
2888 ** file://host/path or file:////host/path. But 5 leading slashes is a
2889 ** common error, we are told, so we handle it as a special case. */
2890 if( strncmp(zUri
+7, "///", 3)==0 ){ iIn
++; }
2891 }else if( strncmp(zUri
+5, "//localhost/", 12)==0 ){
2895 /* Discard the scheme and authority segments of the URI. */
2896 if( zUri
[5]=='/' && zUri
[6]=='/' ){
2898 while( zUri
[iIn
] && zUri
[iIn
]!='/' ) iIn
++;
2899 if( iIn
!=7 && (iIn
!=16 || memcmp("localhost", &zUri
[7], 9)) ){
2900 *pzErrMsg
= sqlite3_mprintf("invalid uri authority: %.*s",
2908 /* Copy the filename and any query parameters into the zFile buffer.
2909 ** Decode %HH escape codes along the way.
2911 ** Within this loop, variable eState may be set to 0, 1 or 2, depending
2912 ** on the parsing context. As follows:
2914 ** 0: Parsing file-name.
2915 ** 1: Parsing name section of a name=value query parameter.
2916 ** 2: Parsing value section of a name=value query parameter.
2919 while( (c
= zUri
[iIn
])!=0 && c
!='#' ){
2922 && sqlite3Isxdigit(zUri
[iIn
])
2923 && sqlite3Isxdigit(zUri
[iIn
+1])
2925 int octet
= (sqlite3HexToInt(zUri
[iIn
++]) << 4);
2926 octet
+= sqlite3HexToInt(zUri
[iIn
++]);
2928 assert( octet
>=0 && octet
<256 );
2930 #ifndef SQLITE_ENABLE_URI_00_ERROR
2931 /* This branch is taken when "%00" appears within the URI. In this
2932 ** case we ignore all text in the remainder of the path, name or
2933 ** value currently being parsed. So ignore the current character
2934 ** and skip to the next "?", "=" or "&", as appropriate. */
2935 while( (c
= zUri
[iIn
])!=0 && c
!='#'
2936 && (eState
!=0 || c
!='?')
2937 && (eState
!=1 || (c
!='=' && c
!='&'))
2938 && (eState
!=2 || c
!='&')
2944 /* If ENABLE_URI_00_ERROR is defined, "%00" in a URI is an error. */
2945 *pzErrMsg
= sqlite3_mprintf("unexpected %%00 in uri");
2951 }else if( eState
==1 && (c
=='&' || c
=='=') ){
2952 if( zFile
[iOut
-1]==0 ){
2953 /* An empty option name. Ignore this option altogether. */
2954 while( zUri
[iIn
] && zUri
[iIn
]!='#' && zUri
[iIn
-1]!='&' ) iIn
++;
2958 zFile
[iOut
++] = '\0';
2963 }else if( (eState
==0 && c
=='?') || (eState
==2 && c
=='&') ){
2969 if( eState
==1 ) zFile
[iOut
++] = '\0';
2970 memset(zFile
+iOut
, 0, 4); /* end-of-options + empty journal filenames */
2972 /* Check if there were any options specified that should be interpreted
2973 ** here. Options that are interpreted here include "vfs" and those that
2974 ** correspond to flags that may be passed to the sqlite3_open_v2()
2976 zOpt
= &zFile
[sqlite3Strlen30(zFile
)+1];
2978 int nOpt
= sqlite3Strlen30(zOpt
);
2979 char *zVal
= &zOpt
[nOpt
+1];
2980 int nVal
= sqlite3Strlen30(zVal
);
2982 if( nOpt
==3 && memcmp("vfs", zOpt
, 3)==0 ){
2989 char *zModeType
= 0;
2993 if( nOpt
==5 && memcmp("cache", zOpt
, 5)==0 ){
2994 static struct OpenMode aCacheMode
[] = {
2995 { "shared", SQLITE_OPEN_SHAREDCACHE
},
2996 { "private", SQLITE_OPEN_PRIVATECACHE
},
3000 mask
= SQLITE_OPEN_SHAREDCACHE
|SQLITE_OPEN_PRIVATECACHE
;
3003 zModeType
= "cache";
3005 if( nOpt
==4 && memcmp("mode", zOpt
, 4)==0 ){
3006 static struct OpenMode aOpenMode
[] = {
3007 { "ro", SQLITE_OPEN_READONLY
},
3008 { "rw", SQLITE_OPEN_READWRITE
},
3009 { "rwc", SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
},
3010 { "memory", SQLITE_OPEN_MEMORY
},
3014 mask
= SQLITE_OPEN_READONLY
| SQLITE_OPEN_READWRITE
3015 | SQLITE_OPEN_CREATE
| SQLITE_OPEN_MEMORY
;
3017 limit
= mask
& flags
;
3018 zModeType
= "access";
3024 for(i
=0; aMode
[i
].z
; i
++){
3025 const char *z
= aMode
[i
].z
;
3026 if( nVal
==sqlite3Strlen30(z
) && 0==memcmp(zVal
, z
, nVal
) ){
3027 mode
= aMode
[i
].mode
;
3032 *pzErrMsg
= sqlite3_mprintf("no such %s mode: %s", zModeType
, zVal
);
3036 if( (mode
& ~SQLITE_OPEN_MEMORY
)>limit
){
3037 *pzErrMsg
= sqlite3_mprintf("%s mode not allowed: %s",
3042 flags
= (flags
& ~mask
) | mode
;
3046 zOpt
= &zVal
[nVal
+1];
3050 zFile
= sqlite3_malloc64(nUri
+8);
3051 if( !zFile
) return SQLITE_NOMEM_BKPT
;
3052 memset(zFile
, 0, 4);
3055 memcpy(zFile
, zUri
, nUri
);
3057 memset(zFile
+nUri
, 0, 4);
3058 flags
&= ~SQLITE_OPEN_URI
;
3061 *ppVfs
= sqlite3_vfs_find(zVfs
);
3063 *pzErrMsg
= sqlite3_mprintf("no such vfs: %s", zVfs
);
3067 if( rc
!=SQLITE_OK
){
3068 sqlite3_free_filename(zFile
);
3077 ** This routine does the core work of extracting URI parameters from a
3078 ** database filename for the sqlite3_uri_parameter() interface.
3080 static const char *uriParameter(const char *zFilename
, const char *zParam
){
3081 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3082 while( zFilename
[0] ){
3083 int x
= strcmp(zFilename
, zParam
);
3084 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3085 if( x
==0 ) return zFilename
;
3086 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3091 /* BEGIN SQLCIPHER */
3092 #if defined(SQLITE_HAS_CODEC)
3094 ** Process URI filename query parameters relevant to the SQLite Encryption
3095 ** Extension. Return true if any of the relevant query parameters are
3096 ** seen and return false if not.
3098 int sqlite3CodecQueryParameters(
3099 sqlite3
*db
, /* Database connection */
3100 const char *zDb
, /* Which schema is being created/attached */
3101 const char *zUri
/* URI filename */
3106 }else if( (zKey
= uriParameter(zUri
, "hexkey"))!=0 && zKey
[0] ){
3110 for(i
=0, iByte
=0; i
<sizeof(zDecoded
)*2 && sqlite3Isxdigit(zKey
[i
]); i
++){
3111 iByte
= (iByte
<<4) + sqlite3HexToInt(zKey
[i
]);
3112 if( (i
&1)!=0 ) zDecoded
[i
/2] = iByte
;
3114 sqlite3_key_v2(db
, zDb
, zDecoded
, i
/2);
3116 }else if( (zKey
= uriParameter(zUri
, "key"))!=0 ){
3117 sqlite3_key_v2(db
, zDb
, zKey
, sqlite3Strlen30(zKey
));
3119 }else if( (zKey
= uriParameter(zUri
, "textkey"))!=0 ){
3120 sqlite3_key_v2(db
, zDb
, zKey
, -1);
3131 ** This routine does the work of opening a database on behalf of
3132 ** sqlite3_open() and sqlite3_open16(). The database filename "zFilename"
3133 ** is UTF-8 encoded.
3135 static int openDatabase(
3136 const char *zFilename
, /* Database filename UTF-8 encoded */
3137 sqlite3
**ppDb
, /* OUT: Returned database handle */
3138 unsigned int flags
, /* Operational flags */
3139 const char *zVfs
/* Name of the VFS to use */
3141 sqlite3
*db
; /* Store allocated handle here */
3142 int rc
; /* Return code */
3143 int isThreadsafe
; /* True for threadsafe connections */
3144 char *zOpen
= 0; /* Filename argument to pass to BtreeOpen() */
3145 char *zErrMsg
= 0; /* Error message from sqlite3ParseUri() */
3146 int i
; /* Loop counter */
3148 #ifdef SQLITE_ENABLE_API_ARMOR
3149 if( ppDb
==0 ) return SQLITE_MISUSE_BKPT
;
3152 #ifndef SQLITE_OMIT_AUTOINIT
3153 rc
= sqlite3_initialize();
3157 if( sqlite3GlobalConfig
.bCoreMutex
==0 ){
3159 }else if( flags
& SQLITE_OPEN_NOMUTEX
){
3161 }else if( flags
& SQLITE_OPEN_FULLMUTEX
){
3164 isThreadsafe
= sqlite3GlobalConfig
.bFullMutex
;
3167 if( flags
& SQLITE_OPEN_PRIVATECACHE
){
3168 flags
&= ~SQLITE_OPEN_SHAREDCACHE
;
3169 }else if( sqlite3GlobalConfig
.sharedCacheEnabled
){
3170 flags
|= SQLITE_OPEN_SHAREDCACHE
;
3173 /* Remove harmful bits from the flags parameter
3175 ** The SQLITE_OPEN_NOMUTEX and SQLITE_OPEN_FULLMUTEX flags were
3176 ** dealt with in the previous code block. Besides these, the only
3177 ** valid input flags for sqlite3_open_v2() are SQLITE_OPEN_READONLY,
3178 ** SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_SHAREDCACHE,
3179 ** SQLITE_OPEN_PRIVATECACHE, and some reserved bits. Silently mask
3180 ** off all other flags.
3182 flags
&= ~( SQLITE_OPEN_DELETEONCLOSE
|
3183 SQLITE_OPEN_EXCLUSIVE
|
3184 SQLITE_OPEN_MAIN_DB
|
3185 SQLITE_OPEN_TEMP_DB
|
3186 SQLITE_OPEN_TRANSIENT_DB
|
3187 SQLITE_OPEN_MAIN_JOURNAL
|
3188 SQLITE_OPEN_TEMP_JOURNAL
|
3189 SQLITE_OPEN_SUBJOURNAL
|
3190 SQLITE_OPEN_SUPER_JOURNAL
|
3191 SQLITE_OPEN_NOMUTEX
|
3192 SQLITE_OPEN_FULLMUTEX
|
3196 /* Allocate the sqlite data structure */
3197 db
= sqlite3MallocZero( sizeof(sqlite3
) );
3198 if( db
==0 ) goto opendb_out
;
3200 #ifdef SQLITE_ENABLE_MULTITHREADED_CHECKS
3201 || sqlite3GlobalConfig
.bCoreMutex
3204 db
->mutex
= sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE
);
3210 if( isThreadsafe
==0 ){
3211 sqlite3MutexWarnOnContention(db
->mutex
);
3214 sqlite3_mutex_enter(db
->mutex
);
3217 db
->magic
= SQLITE_MAGIC_BUSY
;
3218 db
->aDb
= db
->aDbStatic
;
3219 db
->lookaside
.bDisable
= 1;
3220 db
->lookaside
.sz
= 0;
3222 assert( sizeof(db
->aLimit
)==sizeof(aHardLimit
) );
3223 memcpy(db
->aLimit
, aHardLimit
, sizeof(db
->aLimit
));
3224 db
->aLimit
[SQLITE_LIMIT_WORKER_THREADS
] = SQLITE_DEFAULT_WORKER_THREADS
;
3226 db
->nextAutovac
= -1;
3227 db
->szMmap
= sqlite3GlobalConfig
.szMmap
;
3228 db
->nextPagesize
= 0;
3229 db
->nMaxSorterMmap
= 0x7FFFFFFF;
3230 db
->flags
|= SQLITE_ShortColNames
3231 | SQLITE_EnableTrigger
3234 #if !defined(SQLITE_TRUSTED_SCHEMA) || SQLITE_TRUSTED_SCHEMA+0!=0
3235 | SQLITE_TrustedSchema
3237 /* The SQLITE_DQS compile-time option determines the default settings
3238 ** for SQLITE_DBCONFIG_DQS_DDL and SQLITE_DBCONFIG_DQS_DML.
3240 ** SQLITE_DQS SQLITE_DBCONFIG_DQS_DDL SQLITE_DBCONFIG_DQS_DML
3241 ** ---------- ----------------------- -----------------------
3248 ** Legacy behavior is 3 (double-quoted string literals are allowed anywhere)
3249 ** and so that is the default. But developers are encouranged to use
3250 ** -DSQLITE_DQS=0 (best) or -DSQLITE_DQS=1 (second choice) if possible.
3252 #if !defined(SQLITE_DQS)
3253 # define SQLITE_DQS 3
3255 #if (SQLITE_DQS&1)==1
3258 #if (SQLITE_DQS&2)==2
3262 #if !defined(SQLITE_DEFAULT_AUTOMATIC_INDEX) || SQLITE_DEFAULT_AUTOMATIC_INDEX
3265 #if SQLITE_DEFAULT_CKPTFULLFSYNC
3266 | SQLITE_CkptFullFSync
3268 #if SQLITE_DEFAULT_FILE_FORMAT<4
3269 | SQLITE_LegacyFileFmt
3271 #ifdef SQLITE_ENABLE_LOAD_EXTENSION
3272 | SQLITE_LoadExtension
3274 #if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
3275 | SQLITE_RecTriggers
3277 #if defined(SQLITE_DEFAULT_FOREIGN_KEYS) && SQLITE_DEFAULT_FOREIGN_KEYS
3278 | SQLITE_ForeignKeys
3280 #if defined(SQLITE_REVERSE_UNORDERED_SELECTS)
3281 | SQLITE_ReverseOrder
3283 #if defined(SQLITE_ENABLE_OVERSIZE_CELL_CHECK)
3286 #if defined(SQLITE_ENABLE_FTS3_TOKENIZER)
3287 | SQLITE_Fts3Tokenizer
3289 #if defined(SQLITE_ENABLE_QPSG)
3292 #if defined(SQLITE_DEFAULT_DEFENSIVE)
3295 #if defined(SQLITE_DEFAULT_LEGACY_ALTER_TABLE)
3296 | SQLITE_LegacyAlter
3299 sqlite3HashInit(&db
->aCollSeq
);
3300 #ifndef SQLITE_OMIT_VIRTUALTABLE
3301 sqlite3HashInit(&db
->aModule
);
3304 /* Add the default collation sequence BINARY. BINARY works for both UTF-8
3305 ** and UTF-16, so add a version for each to avoid any unnecessary
3306 ** conversions. The only error that can occur here is a malloc() failure.
3308 ** EVIDENCE-OF: R-52786-44878 SQLite defines three built-in collating
3311 createCollation(db
, sqlite3StrBINARY
, SQLITE_UTF8
, 0, binCollFunc
, 0);
3312 createCollation(db
, sqlite3StrBINARY
, SQLITE_UTF16BE
, 0, binCollFunc
, 0);
3313 createCollation(db
, sqlite3StrBINARY
, SQLITE_UTF16LE
, 0, binCollFunc
, 0);
3314 createCollation(db
, "NOCASE", SQLITE_UTF8
, 0, nocaseCollatingFunc
, 0);
3315 createCollation(db
, "RTRIM", SQLITE_UTF8
, 0, rtrimCollFunc
, 0);
3316 if( db
->mallocFailed
){
3320 /* Parse the filename/URI argument
3322 ** Only allow sensible combinations of bits in the flags argument.
3323 ** Throw an error if any non-sense combination is used. If we
3324 ** do not block illegal combinations here, it could trigger
3325 ** assert() statements in deeper layers. Sensible combinations
3328 ** 1: SQLITE_OPEN_READONLY
3329 ** 2: SQLITE_OPEN_READWRITE
3330 ** 6: SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
3332 db
->openFlags
= flags
;
3333 assert( SQLITE_OPEN_READONLY
== 0x01 );
3334 assert( SQLITE_OPEN_READWRITE
== 0x02 );
3335 assert( SQLITE_OPEN_CREATE
== 0x04 );
3336 testcase( (1<<(flags
&7))==0x02 ); /* READONLY */
3337 testcase( (1<<(flags
&7))==0x04 ); /* READWRITE */
3338 testcase( (1<<(flags
&7))==0x40 ); /* READWRITE | CREATE */
3339 if( ((1<<(flags
&7)) & 0x46)==0 ){
3340 rc
= SQLITE_MISUSE_BKPT
; /* IMP: R-18321-05872 */
3342 rc
= sqlite3ParseUri(zVfs
, zFilename
, &flags
, &db
->pVfs
, &zOpen
, &zErrMsg
);
3344 if( rc
!=SQLITE_OK
){
3345 if( rc
==SQLITE_NOMEM
) sqlite3OomFault(db
);
3346 sqlite3ErrorWithMsg(db
, rc
, zErrMsg
? "%s" : 0, zErrMsg
);
3347 sqlite3_free(zErrMsg
);
3351 /* Open the backend database driver */
3352 rc
= sqlite3BtreeOpen(db
->pVfs
, zOpen
, db
, &db
->aDb
[0].pBt
, 0,
3353 flags
| SQLITE_OPEN_MAIN_DB
);
3354 if( rc
!=SQLITE_OK
){
3355 if( rc
==SQLITE_IOERR_NOMEM
){
3356 rc
= SQLITE_NOMEM_BKPT
;
3358 sqlite3Error(db
, rc
);
3361 sqlite3BtreeEnter(db
->aDb
[0].pBt
);
3362 db
->aDb
[0].pSchema
= sqlite3SchemaGet(db
, db
->aDb
[0].pBt
);
3363 if( !db
->mallocFailed
){
3364 sqlite3SetTextEncoding(db
, SCHEMA_ENC(db
));
3366 sqlite3BtreeLeave(db
->aDb
[0].pBt
);
3367 db
->aDb
[1].pSchema
= sqlite3SchemaGet(db
, 0);
3369 /* The default safety_level for the main database is FULL; for the temp
3370 ** database it is OFF. This matches the pager layer defaults.
3372 db
->aDb
[0].zDbSName
= "main";
3373 db
->aDb
[0].safety_level
= SQLITE_DEFAULT_SYNCHRONOUS
+1;
3374 db
->aDb
[1].zDbSName
= "temp";
3375 db
->aDb
[1].safety_level
= PAGER_SYNCHRONOUS_OFF
;
3377 db
->magic
= SQLITE_MAGIC_OPEN
;
3378 if( db
->mallocFailed
){
3382 /* Register all built-in functions, but do not attempt to read the
3383 ** database schema yet. This is delayed until the first time the database
3386 sqlite3Error(db
, SQLITE_OK
);
3387 sqlite3RegisterPerConnectionBuiltinFunctions(db
);
3388 rc
= sqlite3_errcode(db
);
3391 /* Load compiled-in extensions */
3392 for(i
=0; rc
==SQLITE_OK
&& i
<ArraySize(sqlite3BuiltinExtensions
); i
++){
3393 rc
= sqlite3BuiltinExtensions
[i
](db
);
3396 /* Load automatic extensions - extensions that have been registered
3397 ** using the sqlite3_automatic_extension() API.
3399 if( rc
==SQLITE_OK
){
3400 sqlite3AutoLoadExtensions(db
);
3401 rc
= sqlite3_errcode(db
);
3402 if( rc
!=SQLITE_OK
){
3407 #ifdef SQLCIPHER_EXT
3408 if( !db
->mallocFailed
&& rc
==SQLITE_OK
){
3409 extern int sqlcipherVtabInit(sqlite3
*);
3410 rc
= sqlcipherVtabInit(db
);
3414 #ifdef SQLITE_ENABLE_INTERNAL_FUNCTIONS
3415 /* Testing use only!!! The -DSQLITE_ENABLE_INTERNAL_FUNCTIONS=1 compile-time
3416 ** option gives access to internal functions by default.
3417 ** Testing use only!!! */
3418 db
->mDbFlags
|= DBFLAG_InternalFunc
;
3421 /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking
3422 ** mode. -DSQLITE_DEFAULT_LOCKING_MODE=0 make NORMAL the default locking
3423 ** mode. Doing nothing at all also makes NORMAL the default.
3425 #ifdef SQLITE_DEFAULT_LOCKING_MODE
3426 db
->dfltLockMode
= SQLITE_DEFAULT_LOCKING_MODE
;
3427 sqlite3PagerLockingMode(sqlite3BtreePager(db
->aDb
[0].pBt
),
3428 SQLITE_DEFAULT_LOCKING_MODE
);
3431 if( rc
) sqlite3Error(db
, rc
);
3433 /* Enable the lookaside-malloc subsystem */
3434 setupLookaside(db
, 0, sqlite3GlobalConfig
.szLookaside
,
3435 sqlite3GlobalConfig
.nLookaside
);
3437 sqlite3_wal_autocheckpoint(db
, SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
);
3441 assert( db
->mutex
!=0 || isThreadsafe
==0
3442 || sqlite3GlobalConfig
.bFullMutex
==0 );
3443 sqlite3_mutex_leave(db
->mutex
);
3445 rc
= sqlite3_errcode(db
);
3446 assert( db
!=0 || rc
==SQLITE_NOMEM
);
3447 if( rc
==SQLITE_NOMEM
){
3450 }else if( rc
!=SQLITE_OK
){
3451 db
->magic
= SQLITE_MAGIC_SICK
;
3454 #ifdef SQLITE_ENABLE_SQLLOG
3455 if( sqlite3GlobalConfig
.xSqllog
){
3456 /* Opening a db handle. Fourth parameter is passed 0. */
3457 void *pArg
= sqlite3GlobalConfig
.pSqllogArg
;
3458 sqlite3GlobalConfig
.xSqllog(pArg
, db
, zFilename
, 0);
3461 /* BEGIN SQLCIPHER */
3462 #if defined(SQLITE_HAS_CODEC)
3463 if( rc
==SQLITE_OK
) sqlite3CodecQueryParameters(db
, 0, zOpen
);
3466 sqlite3_free_filename(zOpen
);
3472 ** Open a new database handle.
3475 const char *zFilename
,
3478 return openDatabase(zFilename
, ppDb
,
3479 SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
, 0);
3481 int sqlite3_open_v2(
3482 const char *filename
, /* Database filename (UTF-8) */
3483 sqlite3
**ppDb
, /* OUT: SQLite db handle */
3484 int flags
, /* Flags */
3485 const char *zVfs
/* Name of VFS module to use */
3487 return openDatabase(filename
, ppDb
, (unsigned int)flags
, zVfs
);
3490 #ifndef SQLITE_OMIT_UTF16
3492 ** Open a new database handle.
3495 const void *zFilename
,
3498 char const *zFilename8
; /* zFilename encoded in UTF-8 instead of UTF-16 */
3499 sqlite3_value
*pVal
;
3502 #ifdef SQLITE_ENABLE_API_ARMOR
3503 if( ppDb
==0 ) return SQLITE_MISUSE_BKPT
;
3506 #ifndef SQLITE_OMIT_AUTOINIT
3507 rc
= sqlite3_initialize();
3510 if( zFilename
==0 ) zFilename
= "\000\000";
3511 pVal
= sqlite3ValueNew(0);
3512 sqlite3ValueSetStr(pVal
, -1, zFilename
, SQLITE_UTF16NATIVE
, SQLITE_STATIC
);
3513 zFilename8
= sqlite3ValueText(pVal
, SQLITE_UTF8
);
3515 rc
= openDatabase(zFilename8
, ppDb
,
3516 SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
, 0);
3517 assert( *ppDb
|| rc
==SQLITE_NOMEM
);
3518 if( rc
==SQLITE_OK
&& !DbHasProperty(*ppDb
, 0, DB_SchemaLoaded
) ){
3519 SCHEMA_ENC(*ppDb
) = ENC(*ppDb
) = SQLITE_UTF16NATIVE
;
3522 rc
= SQLITE_NOMEM_BKPT
;
3524 sqlite3ValueFree(pVal
);
3528 #endif /* SQLITE_OMIT_UTF16 */
3531 ** Register a new collation sequence with the database handle db.
3533 int sqlite3_create_collation(
3538 int(*xCompare
)(void*,int,const void*,int,const void*)
3540 return sqlite3_create_collation_v2(db
, zName
, enc
, pCtx
, xCompare
, 0);
3544 ** Register a new collation sequence with the database handle db.
3546 int sqlite3_create_collation_v2(
3551 int(*xCompare
)(void*,int,const void*,int,const void*),
3556 #ifdef SQLITE_ENABLE_API_ARMOR
3557 if( !sqlite3SafetyCheckOk(db
) || zName
==0 ) return SQLITE_MISUSE_BKPT
;
3559 sqlite3_mutex_enter(db
->mutex
);
3560 assert( !db
->mallocFailed
);
3561 rc
= createCollation(db
, zName
, (u8
)enc
, pCtx
, xCompare
, xDel
);
3562 rc
= sqlite3ApiExit(db
, rc
);
3563 sqlite3_mutex_leave(db
->mutex
);
3567 #ifndef SQLITE_OMIT_UTF16
3569 ** Register a new collation sequence with the database handle db.
3571 int sqlite3_create_collation16(
3576 int(*xCompare
)(void*,int,const void*,int,const void*)
3581 #ifdef SQLITE_ENABLE_API_ARMOR
3582 if( !sqlite3SafetyCheckOk(db
) || zName
==0 ) return SQLITE_MISUSE_BKPT
;
3584 sqlite3_mutex_enter(db
->mutex
);
3585 assert( !db
->mallocFailed
);
3586 zName8
= sqlite3Utf16to8(db
, zName
, -1, SQLITE_UTF16NATIVE
);
3588 rc
= createCollation(db
, zName8
, (u8
)enc
, pCtx
, xCompare
, 0);
3589 sqlite3DbFree(db
, zName8
);
3591 rc
= sqlite3ApiExit(db
, rc
);
3592 sqlite3_mutex_leave(db
->mutex
);
3595 #endif /* SQLITE_OMIT_UTF16 */
3598 ** Register a collation sequence factory callback with the database handle
3599 ** db. Replace any previously installed collation sequence factory.
3601 int sqlite3_collation_needed(
3603 void *pCollNeededArg
,
3604 void(*xCollNeeded
)(void*,sqlite3
*,int eTextRep
,const char*)
3606 #ifdef SQLITE_ENABLE_API_ARMOR
3607 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
3609 sqlite3_mutex_enter(db
->mutex
);
3610 db
->xCollNeeded
= xCollNeeded
;
3611 db
->xCollNeeded16
= 0;
3612 db
->pCollNeededArg
= pCollNeededArg
;
3613 sqlite3_mutex_leave(db
->mutex
);
3617 #ifndef SQLITE_OMIT_UTF16
3619 ** Register a collation sequence factory callback with the database handle
3620 ** db. Replace any previously installed collation sequence factory.
3622 int sqlite3_collation_needed16(
3624 void *pCollNeededArg
,
3625 void(*xCollNeeded16
)(void*,sqlite3
*,int eTextRep
,const void*)
3627 #ifdef SQLITE_ENABLE_API_ARMOR
3628 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
3630 sqlite3_mutex_enter(db
->mutex
);
3631 db
->xCollNeeded
= 0;
3632 db
->xCollNeeded16
= xCollNeeded16
;
3633 db
->pCollNeededArg
= pCollNeededArg
;
3634 sqlite3_mutex_leave(db
->mutex
);
3637 #endif /* SQLITE_OMIT_UTF16 */
3639 #ifndef SQLITE_OMIT_DEPRECATED
3641 ** This function is now an anachronism. It used to be used to recover from a
3642 ** malloc() failure, but SQLite now does this automatically.
3644 int sqlite3_global_recover(void){
3650 ** Test to see whether or not the database connection is in autocommit
3651 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
3652 ** by default. Autocommit is disabled by a BEGIN statement and reenabled
3653 ** by the next COMMIT or ROLLBACK.
3655 int sqlite3_get_autocommit(sqlite3
*db
){
3656 #ifdef SQLITE_ENABLE_API_ARMOR
3657 if( !sqlite3SafetyCheckOk(db
) ){
3658 (void)SQLITE_MISUSE_BKPT
;
3662 return db
->autoCommit
;
3666 ** The following routines are substitutes for constants SQLITE_CORRUPT,
3667 ** SQLITE_MISUSE, SQLITE_CANTOPEN, SQLITE_NOMEM and possibly other error
3668 ** constants. They serve two purposes:
3670 ** 1. Serve as a convenient place to set a breakpoint in a debugger
3671 ** to detect when version error conditions occurs.
3673 ** 2. Invoke sqlite3_log() to provide the source code location where
3674 ** a low-level error is first detected.
3676 int sqlite3ReportError(int iErr
, int lineno
, const char *zType
){
3677 sqlite3_log(iErr
, "%s at line %d of [%.10s]",
3678 zType
, lineno
, 20+sqlite3_sourceid());
3681 int sqlite3CorruptError(int lineno
){
3682 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3683 return sqlite3ReportError(SQLITE_CORRUPT
, lineno
, "database corruption");
3685 int sqlite3MisuseError(int lineno
){
3686 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3687 return sqlite3ReportError(SQLITE_MISUSE
, lineno
, "misuse");
3689 int sqlite3CantopenError(int lineno
){
3690 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3691 return sqlite3ReportError(SQLITE_CANTOPEN
, lineno
, "cannot open file");
3693 #if defined(SQLITE_DEBUG) || defined(SQLITE_ENABLE_CORRUPT_PGNO)
3694 int sqlite3CorruptPgnoError(int lineno
, Pgno pgno
){
3696 sqlite3_snprintf(sizeof(zMsg
), zMsg
, "database corruption page %d", pgno
);
3697 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3698 return sqlite3ReportError(SQLITE_CORRUPT
, lineno
, zMsg
);
3702 int sqlite3NomemError(int lineno
){
3703 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3704 return sqlite3ReportError(SQLITE_NOMEM
, lineno
, "OOM");
3706 int sqlite3IoerrnomemError(int lineno
){
3707 testcase( sqlite3GlobalConfig
.xLog
!=0 );
3708 return sqlite3ReportError(SQLITE_IOERR_NOMEM
, lineno
, "I/O OOM error");
3712 #ifndef SQLITE_OMIT_DEPRECATED
3714 ** This is a convenience routine that makes sure that all thread-specific
3715 ** data for this thread has been deallocated.
3717 ** SQLite no longer uses thread-specific data so this routine is now a
3718 ** no-op. It is retained for historical compatibility.
3720 void sqlite3_thread_cleanup(void){
3725 ** Return meta information about a specific column of a database table.
3726 ** See comment in sqlite3.h (sqlite.h.in) for details.
3728 int sqlite3_table_column_metadata(
3729 sqlite3
*db
, /* Connection handle */
3730 const char *zDbName
, /* Database name or NULL */
3731 const char *zTableName
, /* Table name */
3732 const char *zColumnName
, /* Column name */
3733 char const **pzDataType
, /* OUTPUT: Declared data type */
3734 char const **pzCollSeq
, /* OUTPUT: Collation sequence name */
3735 int *pNotNull
, /* OUTPUT: True if NOT NULL constraint exists */
3736 int *pPrimaryKey
, /* OUTPUT: True if column part of PK */
3737 int *pAutoinc
/* OUTPUT: True if column is auto-increment */
3744 char const *zDataType
= 0;
3745 char const *zCollSeq
= 0;
3751 #ifdef SQLITE_ENABLE_API_ARMOR
3752 if( !sqlite3SafetyCheckOk(db
) || zTableName
==0 ){
3753 return SQLITE_MISUSE_BKPT
;
3757 /* Ensure the database schema has been loaded */
3758 sqlite3_mutex_enter(db
->mutex
);
3759 sqlite3BtreeEnterAll(db
);
3760 rc
= sqlite3Init(db
, &zErrMsg
);
3761 if( SQLITE_OK
!=rc
){
3765 /* Locate the table in question */
3766 pTab
= sqlite3FindTable(db
, zTableName
, zDbName
);
3767 if( !pTab
|| pTab
->pSelect
){
3772 /* Find the column for which info is requested */
3773 if( zColumnName
==0 ){
3774 /* Query for existance of table only */
3776 for(iCol
=0; iCol
<pTab
->nCol
; iCol
++){
3777 pCol
= &pTab
->aCol
[iCol
];
3778 if( 0==sqlite3StrICmp(pCol
->zName
, zColumnName
) ){
3782 if( iCol
==pTab
->nCol
){
3783 if( HasRowid(pTab
) && sqlite3IsRowid(zColumnName
) ){
3785 pCol
= iCol
>=0 ? &pTab
->aCol
[iCol
] : 0;
3793 /* The following block stores the meta information that will be returned
3794 ** to the caller in local variables zDataType, zCollSeq, notnull, primarykey
3795 ** and autoinc. At this point there are two possibilities:
3797 ** 1. The specified column name was rowid", "oid" or "_rowid_"
3798 ** and there is no explicitly declared IPK column.
3800 ** 2. The table is not a view and the column name identified an
3801 ** explicitly declared column. Copy meta information from *pCol.
3804 zDataType
= sqlite3ColumnType(pCol
,0);
3805 zCollSeq
= pCol
->zColl
;
3806 notnull
= pCol
->notNull
!=0;
3807 primarykey
= (pCol
->colFlags
& COLFLAG_PRIMKEY
)!=0;
3808 autoinc
= pTab
->iPKey
==iCol
&& (pTab
->tabFlags
& TF_Autoincrement
)!=0;
3810 zDataType
= "INTEGER";
3814 zCollSeq
= sqlite3StrBINARY
;
3818 sqlite3BtreeLeaveAll(db
);
3820 /* Whether the function call succeeded or failed, set the output parameters
3821 ** to whatever their local counterparts contain. If an error did occur,
3822 ** this has the effect of zeroing all output parameters.
3824 if( pzDataType
) *pzDataType
= zDataType
;
3825 if( pzCollSeq
) *pzCollSeq
= zCollSeq
;
3826 if( pNotNull
) *pNotNull
= notnull
;
3827 if( pPrimaryKey
) *pPrimaryKey
= primarykey
;
3828 if( pAutoinc
) *pAutoinc
= autoinc
;
3830 if( SQLITE_OK
==rc
&& !pTab
){
3831 sqlite3DbFree(db
, zErrMsg
);
3832 zErrMsg
= sqlite3MPrintf(db
, "no such table column: %s.%s", zTableName
,
3836 sqlite3ErrorWithMsg(db
, rc
, (zErrMsg
?"%s":0), zErrMsg
);
3837 sqlite3DbFree(db
, zErrMsg
);
3838 rc
= sqlite3ApiExit(db
, rc
);
3839 sqlite3_mutex_leave(db
->mutex
);
3844 ** Sleep for a little while. Return the amount of time slept.
3846 int sqlite3_sleep(int ms
){
3849 pVfs
= sqlite3_vfs_find(0);
3850 if( pVfs
==0 ) return 0;
3852 /* This function works in milliseconds, but the underlying OsSleep()
3853 ** API uses microseconds. Hence the 1000's.
3855 rc
= (sqlite3OsSleep(pVfs
, 1000*ms
)/1000);
3860 ** Enable or disable the extended result codes.
3862 int sqlite3_extended_result_codes(sqlite3
*db
, int onoff
){
3863 #ifdef SQLITE_ENABLE_API_ARMOR
3864 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
3866 sqlite3_mutex_enter(db
->mutex
);
3867 db
->errMask
= onoff
? 0xffffffff : 0xff;
3868 sqlite3_mutex_leave(db
->mutex
);
3873 ** Invoke the xFileControl method on a particular database.
3875 int sqlite3_file_control(sqlite3
*db
, const char *zDbName
, int op
, void *pArg
){
3876 int rc
= SQLITE_ERROR
;
3879 #ifdef SQLITE_ENABLE_API_ARMOR
3880 if( !sqlite3SafetyCheckOk(db
) ) return SQLITE_MISUSE_BKPT
;
3882 sqlite3_mutex_enter(db
->mutex
);
3883 pBtree
= sqlite3DbNameToBtree(db
, zDbName
);
3887 sqlite3BtreeEnter(pBtree
);
3888 pPager
= sqlite3BtreePager(pBtree
);
3889 assert( pPager
!=0 );
3890 fd
= sqlite3PagerFile(pPager
);
3892 if( op
==SQLITE_FCNTL_FILE_POINTER
){
3893 *(sqlite3_file
**)pArg
= fd
;
3895 }else if( op
==SQLITE_FCNTL_VFS_POINTER
){
3896 *(sqlite3_vfs
**)pArg
= sqlite3PagerVfs(pPager
);
3898 }else if( op
==SQLITE_FCNTL_JOURNAL_POINTER
){
3899 *(sqlite3_file
**)pArg
= sqlite3PagerJrnlFile(pPager
);
3901 }else if( op
==SQLITE_FCNTL_DATA_VERSION
){
3902 *(unsigned int*)pArg
= sqlite3PagerDataVersion(pPager
);
3904 }else if( op
==SQLITE_FCNTL_RESERVE_BYTES
){
3905 int iNew
= *(int*)pArg
;
3906 *(int*)pArg
= sqlite3BtreeGetRequestedReserve(pBtree
);
3907 if( iNew
>=0 && iNew
<=255 ){
3908 sqlite3BtreeSetPageSize(pBtree
, 0, iNew
, 0);
3912 int nSave
= db
->busyHandler
.nBusy
;
3913 rc
= sqlite3OsFileControl(fd
, op
, pArg
);
3914 db
->busyHandler
.nBusy
= nSave
;
3916 sqlite3BtreeLeave(pBtree
);
3918 sqlite3_mutex_leave(db
->mutex
);
3923 ** Interface to the testing logic.
3925 int sqlite3_test_control(int op
, ...){
3927 #ifdef SQLITE_UNTESTABLE
3928 UNUSED_PARAMETER(op
);
3935 ** Save the current state of the PRNG.
3937 case SQLITE_TESTCTRL_PRNG_SAVE
: {
3938 sqlite3PrngSaveState();
3943 ** Restore the state of the PRNG to the last state saved using
3944 ** PRNG_SAVE. If PRNG_SAVE has never before been called, then
3945 ** this verb acts like PRNG_RESET.
3947 case SQLITE_TESTCTRL_PRNG_RESTORE
: {
3948 sqlite3PrngRestoreState();
3952 /* sqlite3_test_control(SQLITE_TESTCTRL_PRNG_SEED, int x, sqlite3 *db);
3954 ** Control the seed for the pseudo-random number generator (PRNG) that
3955 ** is built into SQLite. Cases:
3957 ** x!=0 && db!=0 Seed the PRNG to the current value of the
3958 ** schema cookie in the main database for db, or
3959 ** x if the schema cookie is zero. This case
3960 ** is convenient to use with database fuzzers
3961 ** as it allows the fuzzer some control over the
3964 ** x!=0 && db==0 Seed the PRNG to the value of x.
3966 ** x==0 && db==0 Revert to default behavior of using the
3967 ** xRandomness method on the primary VFS.
3969 ** This test-control also resets the PRNG so that the new seed will
3970 ** be used for the next call to sqlite3_randomness().
3972 #ifndef SQLITE_OMIT_WSD
3973 case SQLITE_TESTCTRL_PRNG_SEED
: {
3974 int x
= va_arg(ap
, int);
3976 sqlite3
*db
= va_arg(ap
, sqlite3
*);
3977 assert( db
==0 || db
->aDb
[0].pSchema
!=0 );
3978 if( db
&& (y
= db
->aDb
[0].pSchema
->schema_cookie
)!=0 ){ x
= y
; }
3979 sqlite3Config
.iPrngSeed
= x
;
3980 sqlite3_randomness(0,0);
3986 ** sqlite3_test_control(BITVEC_TEST, size, program)
3988 ** Run a test against a Bitvec object of size. The program argument
3989 ** is an array of integers that defines the test. Return -1 on a
3990 ** memory allocation error, 0 on success, or non-zero for an error.
3991 ** See the sqlite3BitvecBuiltinTest() for additional information.
3993 case SQLITE_TESTCTRL_BITVEC_TEST
: {
3994 int sz
= va_arg(ap
, int);
3995 int *aProg
= va_arg(ap
, int*);
3996 rc
= sqlite3BitvecBuiltinTest(sz
, aProg
);
4001 ** sqlite3_test_control(FAULT_INSTALL, xCallback)
4003 ** Arrange to invoke xCallback() whenever sqlite3FaultSim() is called,
4004 ** if xCallback is not NULL.
4006 ** As a test of the fault simulator mechanism itself, sqlite3FaultSim(0)
4007 ** is called immediately after installing the new callback and the return
4008 ** value from sqlite3FaultSim(0) becomes the return from
4009 ** sqlite3_test_control().
4011 case SQLITE_TESTCTRL_FAULT_INSTALL
: {
4012 /* MSVC is picky about pulling func ptrs from va lists.
4013 ** http://support.microsoft.com/kb/47961
4014 ** sqlite3GlobalConfig.xTestCallback = va_arg(ap, int(*)(int));
4016 typedef int(*TESTCALLBACKFUNC_t
)(int);
4017 sqlite3GlobalConfig
.xTestCallback
= va_arg(ap
, TESTCALLBACKFUNC_t
);
4018 rc
= sqlite3FaultSim(0);
4023 ** sqlite3_test_control(BENIGN_MALLOC_HOOKS, xBegin, xEnd)
4025 ** Register hooks to call to indicate which malloc() failures
4028 case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS
: {
4029 typedef void (*void_function
)(void);
4030 void_function xBenignBegin
;
4031 void_function xBenignEnd
;
4032 xBenignBegin
= va_arg(ap
, void_function
);
4033 xBenignEnd
= va_arg(ap
, void_function
);
4034 sqlite3BenignMallocHooks(xBenignBegin
, xBenignEnd
);
4039 ** sqlite3_test_control(SQLITE_TESTCTRL_PENDING_BYTE, unsigned int X)
4041 ** Set the PENDING byte to the value in the argument, if X>0.
4042 ** Make no changes if X==0. Return the value of the pending byte
4043 ** as it existing before this routine was called.
4045 ** IMPORTANT: Changing the PENDING byte from 0x40000000 results in
4046 ** an incompatible database file format. Changing the PENDING byte
4047 ** while any database connection is open results in undefined and
4048 ** deleterious behavior.
4050 case SQLITE_TESTCTRL_PENDING_BYTE
: {
4052 #ifndef SQLITE_OMIT_WSD
4054 unsigned int newVal
= va_arg(ap
, unsigned int);
4055 if( newVal
) sqlite3PendingByte
= newVal
;
4062 ** sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, int X)
4064 ** This action provides a run-time test to see whether or not
4065 ** assert() was enabled at compile-time. If X is true and assert()
4066 ** is enabled, then the return value is true. If X is true and
4067 ** assert() is disabled, then the return value is zero. If X is
4068 ** false and assert() is enabled, then the assertion fires and the
4069 ** process aborts. If X is false and assert() is disabled, then the
4070 ** return value is zero.
4072 case SQLITE_TESTCTRL_ASSERT
: {
4074 assert( /*side-effects-ok*/ (x
= va_arg(ap
,int))!=0 );
4081 ** sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, int X)
4083 ** This action provides a run-time test to see how the ALWAYS and
4084 ** NEVER macros were defined at compile-time.
4086 ** The return value is ALWAYS(X) if X is true, or 0 if X is false.
4088 ** The recommended test is X==2. If the return value is 2, that means
4089 ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
4090 ** default setting. If the return value is 1, then ALWAYS() is either
4091 ** hard-coded to true or else it asserts if its argument is false.
4092 ** The first behavior (hard-coded to true) is the case if
4093 ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
4094 ** behavior (assert if the argument to ALWAYS() is false) is the case if
4095 ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
4097 ** The run-time test procedure might look something like this:
4099 ** if( sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, 2)==2 ){
4100 ** // ALWAYS() and NEVER() are no-op pass-through macros
4101 ** }else if( sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, 1) ){
4102 ** // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
4104 ** // ALWAYS(x) is a constant 1. NEVER(x) is a constant 0.
4107 case SQLITE_TESTCTRL_ALWAYS
: {
4108 int x
= va_arg(ap
,int);
4109 rc
= x
? ALWAYS(x
) : 0;
4114 ** sqlite3_test_control(SQLITE_TESTCTRL_BYTEORDER);
4116 ** The integer returned reveals the byte-order of the computer on which
4117 ** SQLite is running:
4119 ** 1 big-endian, determined at run-time
4120 ** 10 little-endian, determined at run-time
4121 ** 432101 big-endian, determined at compile-time
4122 ** 123410 little-endian, determined at compile-time
4124 case SQLITE_TESTCTRL_BYTEORDER
: {
4125 rc
= SQLITE_BYTEORDER
*100 + SQLITE_LITTLEENDIAN
*10 + SQLITE_BIGENDIAN
;
4129 /* sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS, sqlite3 *db, int N)
4131 ** Enable or disable various optimizations for testing purposes. The
4132 ** argument N is a bitmask of optimizations to be disabled. For normal
4133 ** operation N should be 0. The idea is that a test program (like the
4134 ** SQL Logic Test or SLT test module) can run the same SQL multiple times
4135 ** with various optimizations disabled to verify that the same answer
4136 ** is obtained in every case.
4138 case SQLITE_TESTCTRL_OPTIMIZATIONS
: {
4139 sqlite3
*db
= va_arg(ap
, sqlite3
*);
4140 db
->dbOptFlags
= va_arg(ap
, u32
);
4144 /* sqlite3_test_control(SQLITE_TESTCTRL_LOCALTIME_FAULT, int onoff);
4146 ** If parameter onoff is non-zero, subsequent calls to localtime()
4147 ** and its variants fail. If onoff is zero, undo this setting.
4149 case SQLITE_TESTCTRL_LOCALTIME_FAULT
: {
4150 sqlite3GlobalConfig
.bLocaltimeFault
= va_arg(ap
, int);
4154 /* sqlite3_test_control(SQLITE_TESTCTRL_INTERNAL_FUNCTIONS, sqlite3*);
4156 ** Toggle the ability to use internal functions on or off for
4157 ** the database connection given in the argument.
4159 case SQLITE_TESTCTRL_INTERNAL_FUNCTIONS
: {
4160 sqlite3
*db
= va_arg(ap
, sqlite3
*);
4161 db
->mDbFlags
^= DBFLAG_InternalFunc
;
4165 /* sqlite3_test_control(SQLITE_TESTCTRL_NEVER_CORRUPT, int);
4167 ** Set or clear a flag that indicates that the database file is always well-
4168 ** formed and never corrupt. This flag is clear by default, indicating that
4169 ** database files might have arbitrary corruption. Setting the flag during
4170 ** testing causes certain assert() statements in the code to be activated
4171 ** that demonstrat invariants on well-formed database files.
4173 case SQLITE_TESTCTRL_NEVER_CORRUPT
: {
4174 sqlite3GlobalConfig
.neverCorrupt
= va_arg(ap
, int);
4178 /* sqlite3_test_control(SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS, int);
4180 ** Set or clear a flag that causes SQLite to verify that type, name,
4181 ** and tbl_name fields of the sqlite_schema table. This is normally
4182 ** on, but it is sometimes useful to turn it off for testing.
4184 ** 2020-07-22: Disabling EXTRA_SCHEMA_CHECKS also disables the
4185 ** verification of rootpage numbers when parsing the schema. This
4186 ** is useful to make it easier to reach strange internal error states
4187 ** during testing. The EXTRA_SCHEMA_CHECKS setting is always enabled
4190 case SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS
: {
4191 sqlite3GlobalConfig
.bExtraSchemaChecks
= va_arg(ap
, int);
4195 /* Set the threshold at which OP_Once counters reset back to zero.
4196 ** By default this is 0x7ffffffe (over 2 billion), but that value is
4197 ** too big to test in a reasonable amount of time, so this control is
4198 ** provided to set a small and easily reachable reset value.
4200 case SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD
: {
4201 sqlite3GlobalConfig
.iOnceResetThreshold
= va_arg(ap
, int);
4205 /* sqlite3_test_control(SQLITE_TESTCTRL_VDBE_COVERAGE, xCallback, ptr);
4207 ** Set the VDBE coverage callback function to xCallback with context
4210 case SQLITE_TESTCTRL_VDBE_COVERAGE
: {
4211 #ifdef SQLITE_VDBE_COVERAGE
4212 typedef void (*branch_callback
)(void*,unsigned int,
4213 unsigned char,unsigned char);
4214 sqlite3GlobalConfig
.xVdbeBranch
= va_arg(ap
,branch_callback
);
4215 sqlite3GlobalConfig
.pVdbeBranchArg
= va_arg(ap
,void*);
4220 /* sqlite3_test_control(SQLITE_TESTCTRL_SORTER_MMAP, db, nMax); */
4221 case SQLITE_TESTCTRL_SORTER_MMAP
: {
4222 sqlite3
*db
= va_arg(ap
, sqlite3
*);
4223 db
->nMaxSorterMmap
= va_arg(ap
, int);
4227 /* sqlite3_test_control(SQLITE_TESTCTRL_ISINIT);
4229 ** Return SQLITE_OK if SQLite has been initialized and SQLITE_ERROR if
4232 case SQLITE_TESTCTRL_ISINIT
: {
4233 if( sqlite3GlobalConfig
.isInit
==0 ) rc
= SQLITE_ERROR
;
4237 /* sqlite3_test_control(SQLITE_TESTCTRL_IMPOSTER, db, dbName, onOff, tnum);
4239 ** This test control is used to create imposter tables. "db" is a pointer
4240 ** to the database connection. dbName is the database name (ex: "main" or
4241 ** "temp") which will receive the imposter. "onOff" turns imposter mode on
4242 ** or off. "tnum" is the root page of the b-tree to which the imposter
4243 ** table should connect.
4245 ** Enable imposter mode only when the schema has already been parsed. Then
4246 ** run a single CREATE TABLE statement to construct the imposter table in
4247 ** the parsed schema. Then turn imposter mode back off again.
4249 ** If onOff==0 and tnum>0 then reset the schema for all databases, causing
4250 ** the schema to be reparsed the next time it is needed. This has the
4251 ** effect of erasing all imposter tables.
4253 case SQLITE_TESTCTRL_IMPOSTER
: {
4254 sqlite3
*db
= va_arg(ap
, sqlite3
*);
4255 sqlite3_mutex_enter(db
->mutex
);
4256 db
->init
.iDb
= sqlite3FindDbName(db
, va_arg(ap
,const char*));
4257 db
->init
.busy
= db
->init
.imposterTable
= va_arg(ap
,int);
4258 db
->init
.newTnum
= va_arg(ap
,int);
4259 if( db
->init
.busy
==0 && db
->init
.newTnum
>0 ){
4260 sqlite3ResetAllSchemasOfConnection(db
);
4262 sqlite3_mutex_leave(db
->mutex
);
4266 #if defined(YYCOVERAGE)
4267 /* sqlite3_test_control(SQLITE_TESTCTRL_PARSER_COVERAGE, FILE *out)
4269 ** This test control (only available when SQLite is compiled with
4270 ** -DYYCOVERAGE) writes a report onto "out" that shows all
4271 ** state/lookahead combinations in the parser state machine
4272 ** which are never exercised. If any state is missed, make the
4273 ** return code SQLITE_ERROR.
4275 case SQLITE_TESTCTRL_PARSER_COVERAGE
: {
4276 FILE *out
= va_arg(ap
, FILE*);
4277 if( sqlite3ParserCoverage(out
) ) rc
= SQLITE_ERROR
;
4280 #endif /* defined(YYCOVERAGE) */
4282 /* sqlite3_test_control(SQLITE_TESTCTRL_RESULT_INTREAL, sqlite3_context*);
4284 ** This test-control causes the most recent sqlite3_result_int64() value
4285 ** to be interpreted as a MEM_IntReal instead of as an MEM_Int. Normally,
4286 ** MEM_IntReal values only arise during an INSERT operation of integer
4287 ** values into a REAL column, so they can be challenging to test. This
4288 ** test-control enables us to write an intreal() SQL function that can
4289 ** inject an intreal() value at arbitrary places in an SQL statement,
4290 ** for testing purposes.
4292 case SQLITE_TESTCTRL_RESULT_INTREAL
: {
4293 sqlite3_context
*pCtx
= va_arg(ap
, sqlite3_context
*);
4294 sqlite3ResultIntReal(pCtx
);
4298 /* sqlite3_test_control(SQLITE_TESTCTRL_SEEK_COUNT,
4299 ** sqlite3 *db, // Database connection
4300 ** u64 *pnSeek // Write seek count here
4303 ** This test-control queries the seek-counter on the "main" database
4304 ** file. The seek-counter is written into *pnSeek and is then reset.
4305 ** The seek-count is only available if compiled with SQLITE_DEBUG.
4307 case SQLITE_TESTCTRL_SEEK_COUNT
: {
4308 sqlite3
*db
= va_arg(ap
, sqlite3
*);
4309 u64
*pn
= va_arg(ap
, sqlite3_uint64
*);
4310 *pn
= sqlite3BtreeSeekCount(db
->aDb
->pBt
);
4311 (void)db
; /* Silence harmless unused variable warning */
4315 /* sqlite3_test_control(SQLITE_TESTCTRL_TRACEFLAGS, op, ptr)
4317 ** "ptr" is a pointer to a u32.
4319 ** op==0 Store the current sqlite3SelectTrace in *ptr
4320 ** op==1 Set sqlite3SelectTrace to the value *ptr
4321 ** op==3 Store the current sqlite3WhereTrace in *ptr
4322 ** op==3 Set sqlite3WhereTrace to the value *ptr
4324 case SQLITE_TESTCTRL_TRACEFLAGS
: {
4325 int opTrace
= va_arg(ap
, int);
4326 u32
*ptr
= va_arg(ap
, u32
*);
4328 case 0: *ptr
= sqlite3SelectTrace
; break;
4329 case 1: sqlite3SelectTrace
= *ptr
; break;
4330 case 2: *ptr
= sqlite3WhereTrace
; break;
4331 case 3: sqlite3WhereTrace
= *ptr
; break;
4336 #if defined(SQLITE_DEBUG) && !defined(SQLITE_OMIT_WSD)
4337 /* sqlite3_test_control(SQLITE_TESTCTRL_TUNE, id, *piValue)
4339 ** If "id" is an integer between 1 and SQLITE_NTUNE then set the value
4340 ** of the id-th tuning parameter to *piValue. If "id" is between -1
4341 ** and -SQLITE_NTUNE, then write the current value of the (-id)-th
4342 ** tuning parameter into *piValue.
4344 ** Tuning parameters are for use during transient development builds,
4345 ** to help find the best values for constants in the query planner.
4346 ** Access tuning parameters using the Tuning(ID) macro. Set the
4347 ** parameters in the CLI using ".testctrl tune ID VALUE".
4349 ** Transient use only. Tuning parameters should not be used in
4352 case SQLITE_TESTCTRL_TUNE
: {
4353 int id
= va_arg(ap
, int);
4354 int *piValue
= va_arg(ap
, int*);
4355 if( id
>0 && id
<=SQLITE_NTUNE
){
4356 Tuning(id
) = *piValue
;
4357 }else if( id
<0 && id
>=-SQLITE_NTUNE
){
4358 *piValue
= Tuning(-id
);
4360 rc
= SQLITE_NOTFOUND
;
4367 #endif /* SQLITE_UNTESTABLE */
4372 ** The Pager stores the Database filename, Journal filename, and WAL filename
4373 ** consecutively in memory, in that order. The database filename is prefixed
4374 ** by four zero bytes. Locate the start of the database filename by searching
4375 ** backwards for the first byte following four consecutive zero bytes.
4377 ** This only works if the filename passed in was obtained from the Pager.
4379 static const char *databaseName(const char *zName
){
4380 while( zName
[-1]!=0 || zName
[-2]!=0 || zName
[-3]!=0 || zName
[-4]!=0 ){
4387 ** Append text z[] to the end of p[]. Return a pointer to the first
4388 ** character after then zero terminator on the new text in p[].
4390 static char *appendText(char *p
, const char *z
){
4391 size_t n
= strlen(z
);
4397 ** Allocate memory to hold names for a database, journal file, WAL file,
4398 ** and query parameters. The pointer returned is valid for use by
4399 ** sqlite3_filename_database() and sqlite3_uri_parameter() and related
4402 ** Memory layout must be compatible with that generated by the pager
4403 ** and expected by sqlite3_uri_parameter() and databaseName().
4405 char *sqlite3_create_filename(
4406 const char *zDatabase
,
4407 const char *zJournal
,
4410 const char **azParam
4412 sqlite3_int64 nByte
;
4415 nByte
= strlen(zDatabase
) + strlen(zJournal
) + strlen(zWal
) + 10;
4416 for(i
=0; i
<nParam
*2; i
++){
4417 nByte
+= strlen(azParam
[i
])+1;
4419 pResult
= p
= sqlite3_malloc64( nByte
);
4420 if( p
==0 ) return 0;
4423 p
= appendText(p
, zDatabase
);
4424 for(i
=0; i
<nParam
*2; i
++){
4425 p
= appendText(p
, azParam
[i
]);
4428 p
= appendText(p
, zJournal
);
4429 p
= appendText(p
, zWal
);
4432 assert( (sqlite3_int64
)(p
- pResult
)==nByte
);
4437 ** Free memory obtained from sqlite3_create_filename(). It is a severe
4438 ** error to call this routine with any parameter other than a pointer
4439 ** previously obtained from sqlite3_create_filename() or a NULL pointer.
4441 void sqlite3_free_filename(char *p
){
4443 p
= (char*)databaseName(p
);
4444 sqlite3_free(p
- 4);
4449 ** This is a utility routine, useful to VFS implementations, that checks
4450 ** to see if a database file was a URI that contained a specific query
4451 ** parameter, and if so obtains the value of the query parameter.
4453 ** The zFilename argument is the filename pointer passed into the xOpen()
4454 ** method of a VFS implementation. The zParam argument is the name of the
4455 ** query parameter we seek. This routine returns the value of the zParam
4456 ** parameter if it exists. If the parameter does not exist, this routine
4457 ** returns a NULL pointer.
4459 const char *sqlite3_uri_parameter(const char *zFilename
, const char *zParam
){
4460 if( zFilename
==0 || zParam
==0 ) return 0;
4461 zFilename
= databaseName(zFilename
);
4462 return uriParameter(zFilename
, zParam
);
4466 ** Return a pointer to the name of Nth query parameter of the filename.
4468 const char *sqlite3_uri_key(const char *zFilename
, int N
){
4469 if( zFilename
==0 || N
<0 ) return 0;
4470 zFilename
= databaseName(zFilename
);
4471 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4472 while( zFilename
[0] && (N
--)>0 ){
4473 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4474 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4476 return zFilename
[0] ? zFilename
: 0;
4480 ** Return a boolean value for a query parameter.
4482 int sqlite3_uri_boolean(const char *zFilename
, const char *zParam
, int bDflt
){
4483 const char *z
= sqlite3_uri_parameter(zFilename
, zParam
);
4485 return z
? sqlite3GetBoolean(z
, bDflt
) : bDflt
;
4489 ** Return a 64-bit integer value for a query parameter.
4491 sqlite3_int64
sqlite3_uri_int64(
4492 const char *zFilename
, /* Filename as passed to xOpen */
4493 const char *zParam
, /* URI parameter sought */
4494 sqlite3_int64 bDflt
/* return if parameter is missing */
4496 const char *z
= sqlite3_uri_parameter(zFilename
, zParam
);
4498 if( z
&& sqlite3DecOrHexToI64(z
, &v
)==0 ){
4505 ** Translate a filename that was handed to a VFS routine into the corresponding
4506 ** database, journal, or WAL file.
4508 ** It is an error to pass this routine a filename string that was not
4509 ** passed into the VFS from the SQLite core. Doing so is similar to
4510 ** passing free() a pointer that was not obtained from malloc() - it is
4511 ** an error that we cannot easily detect but that will likely cause memory
4514 const char *sqlite3_filename_database(const char *zFilename
){
4515 return databaseName(zFilename
);
4517 const char *sqlite3_filename_journal(const char *zFilename
){
4518 zFilename
= databaseName(zFilename
);
4519 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4520 while( zFilename
[0] ){
4521 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4522 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4524 return zFilename
+ 1;
4526 const char *sqlite3_filename_wal(const char *zFilename
){
4527 #ifdef SQLITE_OMIT_WAL
4530 zFilename
= sqlite3_filename_journal(zFilename
);
4531 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
4537 ** Return the Btree pointer identified by zDbName. Return NULL if not found.
4539 Btree
*sqlite3DbNameToBtree(sqlite3
*db
, const char *zDbName
){
4540 int iDb
= zDbName
? sqlite3FindDbName(db
, zDbName
) : 0;
4541 return iDb
<0 ? 0 : db
->aDb
[iDb
].pBt
;
4545 ** Return the filename of the database associated with a database
4548 const char *sqlite3_db_filename(sqlite3
*db
, const char *zDbName
){
4550 #ifdef SQLITE_ENABLE_API_ARMOR
4551 if( !sqlite3SafetyCheckOk(db
) ){
4552 (void)SQLITE_MISUSE_BKPT
;
4556 pBt
= sqlite3DbNameToBtree(db
, zDbName
);
4557 return pBt
? sqlite3BtreeGetFilename(pBt
) : 0;
4561 ** Return 1 if database is read-only or 0 if read/write. Return -1 if
4562 ** no such database exists.
4564 int sqlite3_db_readonly(sqlite3
*db
, const char *zDbName
){
4566 #ifdef SQLITE_ENABLE_API_ARMOR
4567 if( !sqlite3SafetyCheckOk(db
) ){
4568 (void)SQLITE_MISUSE_BKPT
;
4572 pBt
= sqlite3DbNameToBtree(db
, zDbName
);
4573 return pBt
? sqlite3BtreeIsReadonly(pBt
) : -1;
4576 #ifdef SQLITE_ENABLE_SNAPSHOT
4578 ** Obtain a snapshot handle for the snapshot of database zDb currently
4579 ** being read by handle db.
4581 int sqlite3_snapshot_get(
4584 sqlite3_snapshot
**ppSnapshot
4586 int rc
= SQLITE_ERROR
;
4587 #ifndef SQLITE_OMIT_WAL
4589 #ifdef SQLITE_ENABLE_API_ARMOR
4590 if( !sqlite3SafetyCheckOk(db
) ){
4591 return SQLITE_MISUSE_BKPT
;
4594 sqlite3_mutex_enter(db
->mutex
);
4596 if( db
->autoCommit
==0 ){
4597 int iDb
= sqlite3FindDbName(db
, zDb
);
4598 if( iDb
==0 || iDb
>1 ){
4599 Btree
*pBt
= db
->aDb
[iDb
].pBt
;
4600 if( SQLITE_TXN_WRITE
!=sqlite3BtreeTxnState(pBt
) ){
4601 rc
= sqlite3BtreeBeginTrans(pBt
, 0, 0);
4602 if( rc
==SQLITE_OK
){
4603 rc
= sqlite3PagerSnapshotGet(sqlite3BtreePager(pBt
), ppSnapshot
);
4609 sqlite3_mutex_leave(db
->mutex
);
4610 #endif /* SQLITE_OMIT_WAL */
4615 ** Open a read-transaction on the snapshot idendified by pSnapshot.
4617 int sqlite3_snapshot_open(
4620 sqlite3_snapshot
*pSnapshot
4622 int rc
= SQLITE_ERROR
;
4623 #ifndef SQLITE_OMIT_WAL
4625 #ifdef SQLITE_ENABLE_API_ARMOR
4626 if( !sqlite3SafetyCheckOk(db
) ){
4627 return SQLITE_MISUSE_BKPT
;
4630 sqlite3_mutex_enter(db
->mutex
);
4631 if( db
->autoCommit
==0 ){
4633 iDb
= sqlite3FindDbName(db
, zDb
);
4634 if( iDb
==0 || iDb
>1 ){
4635 Btree
*pBt
= db
->aDb
[iDb
].pBt
;
4636 if( sqlite3BtreeTxnState(pBt
)!=SQLITE_TXN_WRITE
){
4637 Pager
*pPager
= sqlite3BtreePager(pBt
);
4639 if( sqlite3BtreeTxnState(pBt
)!=SQLITE_TXN_NONE
){
4640 if( db
->nVdbeActive
==0 ){
4641 rc
= sqlite3PagerSnapshotCheck(pPager
, pSnapshot
);
4642 if( rc
==SQLITE_OK
){
4644 rc
= sqlite3BtreeCommit(pBt
);
4650 if( rc
==SQLITE_OK
){
4651 rc
= sqlite3PagerSnapshotOpen(pPager
, pSnapshot
);
4653 if( rc
==SQLITE_OK
){
4654 rc
= sqlite3BtreeBeginTrans(pBt
, 0, 0);
4655 sqlite3PagerSnapshotOpen(pPager
, 0);
4658 sqlite3PagerSnapshotUnlock(pPager
);
4664 sqlite3_mutex_leave(db
->mutex
);
4665 #endif /* SQLITE_OMIT_WAL */
4670 ** Recover as many snapshots as possible from the wal file associated with
4671 ** schema zDb of database db.
4673 int sqlite3_snapshot_recover(sqlite3
*db
, const char *zDb
){
4674 int rc
= SQLITE_ERROR
;
4676 #ifndef SQLITE_OMIT_WAL
4678 #ifdef SQLITE_ENABLE_API_ARMOR
4679 if( !sqlite3SafetyCheckOk(db
) ){
4680 return SQLITE_MISUSE_BKPT
;
4684 sqlite3_mutex_enter(db
->mutex
);
4685 iDb
= sqlite3FindDbName(db
, zDb
);
4686 if( iDb
==0 || iDb
>1 ){
4687 Btree
*pBt
= db
->aDb
[iDb
].pBt
;
4688 if( SQLITE_TXN_NONE
==sqlite3BtreeTxnState(pBt
) ){
4689 rc
= sqlite3BtreeBeginTrans(pBt
, 0, 0);
4690 if( rc
==SQLITE_OK
){
4691 rc
= sqlite3PagerSnapshotRecover(sqlite3BtreePager(pBt
));
4692 sqlite3BtreeCommit(pBt
);
4696 sqlite3_mutex_leave(db
->mutex
);
4697 #endif /* SQLITE_OMIT_WAL */
4702 ** Free a snapshot handle obtained from sqlite3_snapshot_get().
4704 void sqlite3_snapshot_free(sqlite3_snapshot
*pSnapshot
){
4705 sqlite3_free(pSnapshot
);
4707 #endif /* SQLITE_ENABLE_SNAPSHOT */
4709 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
4711 ** Given the name of a compile-time option, return true if that option
4712 ** was used and false if not.
4714 ** The name can optionally begin with "SQLITE_" but the "SQLITE_" prefix
4715 ** is not required for a match.
4717 int sqlite3_compileoption_used(const char *zOptName
){
4720 const char **azCompileOpt
;
4722 #if SQLITE_ENABLE_API_ARMOR
4724 (void)SQLITE_MISUSE_BKPT
;
4729 azCompileOpt
= sqlite3CompileOptions(&nOpt
);
4731 if( sqlite3StrNICmp(zOptName
, "SQLITE_", 7)==0 ) zOptName
+= 7;
4732 n
= sqlite3Strlen30(zOptName
);
4734 /* Since nOpt is normally in single digits, a linear search is
4735 ** adequate. No need for a binary search. */
4736 for(i
=0; i
<nOpt
; i
++){
4737 if( sqlite3StrNICmp(zOptName
, azCompileOpt
[i
], n
)==0
4738 && sqlite3IsIdChar((unsigned char)azCompileOpt
[i
][n
])==0
4747 ** Return the N-th compile-time option string. If N is out of range,
4748 ** return a NULL pointer.
4750 const char *sqlite3_compileoption_get(int N
){
4752 const char **azCompileOpt
;
4753 azCompileOpt
= sqlite3CompileOptions(&nOpt
);
4754 if( N
>=0 && N
<nOpt
){
4755 return azCompileOpt
[N
];
4759 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */