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 #ifdef SQLITE_ENABLE_ICU
26 # include "sqliteicu.h"
29 #ifndef SQLITE_AMALGAMATION
30 /* IMPLEMENTATION-OF: R-46656-45156 The sqlite3_version[] string constant
31 ** contains the text of SQLITE_VERSION macro.
33 const char sqlite3_version
[] = SQLITE_VERSION
;
36 /* IMPLEMENTATION-OF: R-53536-42575 The sqlite3_libversion() function returns
37 ** a pointer to the to the sqlite3_version[] string constant.
39 const char *sqlite3_libversion(void){ return sqlite3_version
; }
41 /* IMPLEMENTATION-OF: R-63124-39300 The sqlite3_sourceid() function returns a
42 ** pointer to a string constant whose value is the same as the
43 ** SQLITE_SOURCE_ID C preprocessor macro.
45 const char *sqlite3_sourceid(void){ return SQLITE_SOURCE_ID
; }
47 /* IMPLEMENTATION-OF: R-35210-63508 The sqlite3_libversion_number() function
48 ** returns an integer equal to SQLITE_VERSION_NUMBER.
50 int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER
; }
52 /* IMPLEMENTATION-OF: R-20790-14025 The sqlite3_threadsafe() function returns
53 ** zero if and only if SQLite was compiled with mutexing code omitted due to
54 ** the SQLITE_THREADSAFE compile-time option being set to 0.
56 int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE
; }
58 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
60 ** If the following function pointer is not NULL and if
61 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
62 ** I/O active are written using this function. These messages
63 ** are intended for debugging activity only.
65 void (*sqlite3IoTrace
)(const char*, ...) = 0;
69 ** If the following global variable points to a string which is the
70 ** name of a directory, then that directory will be used to store
73 ** See also the "PRAGMA temp_store_directory" SQL command.
75 char *sqlite3_temp_directory
= 0;
78 ** If the following global variable points to a string which is the
79 ** name of a directory, then that directory will be used to store
80 ** all database files specified with a relative pathname.
82 ** See also the "PRAGMA data_store_directory" SQL command.
84 char *sqlite3_data_directory
= 0;
89 ** This routine must be called to initialize the memory allocation,
90 ** VFS, and mutex subsystems prior to doing any serious work with
91 ** SQLite. But as long as you do not compile with SQLITE_OMIT_AUTOINIT
92 ** this routine will be called automatically by key routines such as
95 ** This routine is a no-op except on its very first call for the process,
96 ** or for the first call after a call to sqlite3_shutdown.
98 ** The first thread to call this routine runs the initialization to
99 ** completion. If subsequent threads call this routine before the first
100 ** thread has finished the initialization process, then the subsequent
101 ** threads must block until the first thread finishes with the initialization.
103 ** The first thread might call this routine recursively. Recursive
104 ** calls to this routine should not block, of course. Otherwise the
105 ** initialization process would never complete.
107 ** Let X be the first thread to enter this routine. Let Y be some other
108 ** thread. Then while the initial invocation of this routine by X is
109 ** incomplete, it is required that:
111 ** * Calls to this routine from Y must block until the outer-most
112 ** call by X completes.
114 ** * Recursive calls to this routine from thread X return immediately
117 int sqlite3_initialize(void){
118 MUTEX_LOGIC( sqlite3_mutex
*pMaster
; ) /* The main static mutex */
119 int rc
; /* Result code */
121 #ifdef SQLITE_OMIT_WSD
122 rc
= sqlite3_wsd_init(4096, 24);
128 /* If SQLite is already completely initialized, then this call
129 ** to sqlite3_initialize() should be a no-op. But the initialization
130 ** must be complete. So isInit must not be set until the very end
133 if( sqlite3GlobalConfig
.isInit
) return SQLITE_OK
;
135 #ifdef SQLITE_ENABLE_SQLLOG
137 extern void sqlite3_init_sqllog(void);
138 sqlite3_init_sqllog();
142 /* Make sure the mutex subsystem is initialized. If unable to
143 ** initialize the mutex subsystem, return early with the error.
144 ** If the system is so sick that we are unable to allocate a mutex,
145 ** there is not much SQLite is going to be able to do.
147 ** The mutex subsystem must take care of serializing its own
150 rc
= sqlite3MutexInit();
153 /* Initialize the malloc() system and the recursive pInitMutex mutex.
154 ** This operation is protected by the STATIC_MASTER mutex. Note that
155 ** MutexAlloc() is called for a static mutex prior to initializing the
156 ** malloc subsystem - this implies that the allocation of a static
157 ** mutex must not require support from the malloc subsystem.
159 MUTEX_LOGIC( pMaster
= sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER
); )
160 sqlite3_mutex_enter(pMaster
);
161 sqlite3GlobalConfig
.isMutexInit
= 1;
162 if( !sqlite3GlobalConfig
.isMallocInit
){
163 rc
= sqlite3MallocInit();
166 sqlite3GlobalConfig
.isMallocInit
= 1;
167 if( !sqlite3GlobalConfig
.pInitMutex
){
168 sqlite3GlobalConfig
.pInitMutex
=
169 sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE
);
170 if( sqlite3GlobalConfig
.bCoreMutex
&& !sqlite3GlobalConfig
.pInitMutex
){
176 sqlite3GlobalConfig
.nRefInitMutex
++;
178 sqlite3_mutex_leave(pMaster
);
180 /* If rc is not SQLITE_OK at this point, then either the malloc
181 ** subsystem could not be initialized or the system failed to allocate
182 ** the pInitMutex mutex. Return an error in either case. */
187 /* Do the rest of the initialization under the recursive mutex so
188 ** that we will be able to handle recursive calls into
189 ** sqlite3_initialize(). The recursive calls normally come through
190 ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other
191 ** recursive calls might also be possible.
193 ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls
194 ** to the xInit method, so the xInit method need not be threadsafe.
196 ** The following mutex is what serializes access to the appdef pcache xInit
197 ** methods. The sqlite3_pcache_methods.xInit() all is embedded in the
198 ** call to sqlite3PcacheInitialize().
200 sqlite3_mutex_enter(sqlite3GlobalConfig
.pInitMutex
);
201 if( sqlite3GlobalConfig
.isInit
==0 && sqlite3GlobalConfig
.inProgress
==0 ){
202 FuncDefHash
*pHash
= &GLOBAL(FuncDefHash
, sqlite3GlobalFunctions
);
203 sqlite3GlobalConfig
.inProgress
= 1;
204 memset(pHash
, 0, sizeof(sqlite3GlobalFunctions
));
205 sqlite3RegisterGlobalFunctions();
206 if( sqlite3GlobalConfig
.isPCacheInit
==0 ){
207 rc
= sqlite3PcacheInitialize();
210 sqlite3GlobalConfig
.isPCacheInit
= 1;
211 rc
= sqlite3OsInit();
214 sqlite3PCacheBufferSetup( sqlite3GlobalConfig
.pPage
,
215 sqlite3GlobalConfig
.szPage
, sqlite3GlobalConfig
.nPage
);
216 sqlite3GlobalConfig
.isInit
= 1;
218 sqlite3GlobalConfig
.inProgress
= 0;
220 sqlite3_mutex_leave(sqlite3GlobalConfig
.pInitMutex
);
222 /* Go back under the static mutex and clean up the recursive
223 ** mutex to prevent a resource leak.
225 sqlite3_mutex_enter(pMaster
);
226 sqlite3GlobalConfig
.nRefInitMutex
--;
227 if( sqlite3GlobalConfig
.nRefInitMutex
<=0 ){
228 assert( sqlite3GlobalConfig
.nRefInitMutex
==0 );
229 sqlite3_mutex_free(sqlite3GlobalConfig
.pInitMutex
);
230 sqlite3GlobalConfig
.pInitMutex
= 0;
232 sqlite3_mutex_leave(pMaster
);
234 /* The following is just a sanity check to make sure SQLite has
235 ** been compiled correctly. It is important to run this code, but
236 ** we don't want to run it too often and soak up CPU cycles for no
237 ** reason. So we run it once during initialization.
240 #ifndef SQLITE_OMIT_FLOATING_POINT
241 /* This section of code's only "output" is via assert() statements. */
242 if ( rc
==SQLITE_OK
){
243 u64 x
= (((u64
)1)<<63)-1;
245 assert(sizeof(x
)==8);
246 assert(sizeof(x
)==sizeof(y
));
248 assert( sqlite3IsNaN(y
) );
253 /* Do extra initialization steps requested by the SQLITE_EXTRA_INIT
254 ** compile-time option.
256 #ifdef SQLITE_EXTRA_INIT
257 if( rc
==SQLITE_OK
&& sqlite3GlobalConfig
.isInit
){
258 int SQLITE_EXTRA_INIT(const char*);
259 rc
= SQLITE_EXTRA_INIT(0);
267 ** Undo the effects of sqlite3_initialize(). Must not be called while
268 ** there are outstanding database connections or memory allocations or
269 ** while any part of SQLite is otherwise in use in any thread. This
270 ** routine is not threadsafe. But it is safe to invoke this routine
271 ** on when SQLite is already shut down. If SQLite is already shut down
272 ** when this routine is invoked, then this routine is a harmless no-op.
274 int sqlite3_shutdown(void){
275 if( sqlite3GlobalConfig
.isInit
){
276 #ifdef SQLITE_EXTRA_SHUTDOWN
277 void SQLITE_EXTRA_SHUTDOWN(void);
278 SQLITE_EXTRA_SHUTDOWN();
281 sqlite3_reset_auto_extension();
282 sqlite3GlobalConfig
.isInit
= 0;
284 if( sqlite3GlobalConfig
.isPCacheInit
){
285 sqlite3PcacheShutdown();
286 sqlite3GlobalConfig
.isPCacheInit
= 0;
288 if( sqlite3GlobalConfig
.isMallocInit
){
290 sqlite3GlobalConfig
.isMallocInit
= 0;
292 #ifndef SQLITE_OMIT_SHUTDOWN_DIRECTORIES
293 /* The heap subsystem has now been shutdown and these values are supposed
294 ** to be NULL or point to memory that was obtained from sqlite3_malloc(),
295 ** which would rely on that heap subsystem; therefore, make sure these
296 ** values cannot refer to heap memory that was just invalidated when the
297 ** heap subsystem was shutdown. This is only done if the current call to
298 ** this function resulted in the heap subsystem actually being shutdown.
300 sqlite3_data_directory
= 0;
301 sqlite3_temp_directory
= 0;
304 if( sqlite3GlobalConfig
.isMutexInit
){
306 sqlite3GlobalConfig
.isMutexInit
= 0;
313 ** This API allows applications to modify the global configuration of
314 ** the SQLite library at run-time.
316 ** This routine should only be called when there are no outstanding
317 ** database connections or memory allocations. This routine is not
318 ** threadsafe. Failure to heed these warnings can lead to unpredictable
321 int sqlite3_config(int op
, ...){
325 /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while
326 ** the SQLite library is in use. */
327 if( sqlite3GlobalConfig
.isInit
) return SQLITE_MISUSE_BKPT
;
332 /* Mutex configuration options are only available in a threadsafe
335 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0
336 case SQLITE_CONFIG_SINGLETHREAD
: {
337 /* Disable all mutexing */
338 sqlite3GlobalConfig
.bCoreMutex
= 0;
339 sqlite3GlobalConfig
.bFullMutex
= 0;
342 case SQLITE_CONFIG_MULTITHREAD
: {
343 /* Disable mutexing of database connections */
344 /* Enable mutexing of core data structures */
345 sqlite3GlobalConfig
.bCoreMutex
= 1;
346 sqlite3GlobalConfig
.bFullMutex
= 0;
349 case SQLITE_CONFIG_SERIALIZED
: {
350 /* Enable all mutexing */
351 sqlite3GlobalConfig
.bCoreMutex
= 1;
352 sqlite3GlobalConfig
.bFullMutex
= 1;
355 case SQLITE_CONFIG_MUTEX
: {
356 /* Specify an alternative mutex implementation */
357 sqlite3GlobalConfig
.mutex
= *va_arg(ap
, sqlite3_mutex_methods
*);
360 case SQLITE_CONFIG_GETMUTEX
: {
361 /* Retrieve the current mutex implementation */
362 *va_arg(ap
, sqlite3_mutex_methods
*) = sqlite3GlobalConfig
.mutex
;
368 case SQLITE_CONFIG_MALLOC
: {
369 /* Specify an alternative malloc implementation */
370 sqlite3GlobalConfig
.m
= *va_arg(ap
, sqlite3_mem_methods
*);
373 case SQLITE_CONFIG_GETMALLOC
: {
374 /* Retrieve the current malloc() implementation */
375 if( sqlite3GlobalConfig
.m
.xMalloc
==0 ) sqlite3MemSetDefault();
376 *va_arg(ap
, sqlite3_mem_methods
*) = sqlite3GlobalConfig
.m
;
379 case SQLITE_CONFIG_MEMSTATUS
: {
380 /* Enable or disable the malloc status collection */
381 sqlite3GlobalConfig
.bMemstat
= va_arg(ap
, int);
384 case SQLITE_CONFIG_SCRATCH
: {
385 /* Designate a buffer for scratch memory space */
386 sqlite3GlobalConfig
.pScratch
= va_arg(ap
, void*);
387 sqlite3GlobalConfig
.szScratch
= va_arg(ap
, int);
388 sqlite3GlobalConfig
.nScratch
= va_arg(ap
, int);
391 case SQLITE_CONFIG_PAGECACHE
: {
392 /* Designate a buffer for page cache memory space */
393 sqlite3GlobalConfig
.pPage
= va_arg(ap
, void*);
394 sqlite3GlobalConfig
.szPage
= va_arg(ap
, int);
395 sqlite3GlobalConfig
.nPage
= va_arg(ap
, int);
399 case SQLITE_CONFIG_PCACHE
: {
403 case SQLITE_CONFIG_GETPCACHE
: {
409 case SQLITE_CONFIG_PCACHE2
: {
410 /* Specify an alternative page cache implementation */
411 sqlite3GlobalConfig
.pcache2
= *va_arg(ap
, sqlite3_pcache_methods2
*);
414 case SQLITE_CONFIG_GETPCACHE2
: {
415 if( sqlite3GlobalConfig
.pcache2
.xInit
==0 ){
416 sqlite3PCacheSetDefault();
418 *va_arg(ap
, sqlite3_pcache_methods2
*) = sqlite3GlobalConfig
.pcache2
;
422 #if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
423 case SQLITE_CONFIG_HEAP
: {
424 /* Designate a buffer for heap memory space */
425 sqlite3GlobalConfig
.pHeap
= va_arg(ap
, void*);
426 sqlite3GlobalConfig
.nHeap
= va_arg(ap
, int);
427 sqlite3GlobalConfig
.mnReq
= va_arg(ap
, int);
429 if( sqlite3GlobalConfig
.mnReq
<1 ){
430 sqlite3GlobalConfig
.mnReq
= 1;
431 }else if( sqlite3GlobalConfig
.mnReq
>(1<<12) ){
432 /* cap min request size at 2^12 */
433 sqlite3GlobalConfig
.mnReq
= (1<<12);
436 if( sqlite3GlobalConfig
.pHeap
==0 ){
437 /* If the heap pointer is NULL, then restore the malloc implementation
438 ** back to NULL pointers too. This will cause the malloc to go
439 ** back to its default implementation when sqlite3_initialize() is
442 memset(&sqlite3GlobalConfig
.m
, 0, sizeof(sqlite3GlobalConfig
.m
));
444 /* The heap pointer is not NULL, then install one of the
445 ** mem5.c/mem3.c methods. If neither ENABLE_MEMSYS3 nor
446 ** ENABLE_MEMSYS5 is defined, return an error.
448 #ifdef SQLITE_ENABLE_MEMSYS3
449 sqlite3GlobalConfig
.m
= *sqlite3MemGetMemsys3();
451 #ifdef SQLITE_ENABLE_MEMSYS5
452 sqlite3GlobalConfig
.m
= *sqlite3MemGetMemsys5();
459 case SQLITE_CONFIG_LOOKASIDE
: {
460 sqlite3GlobalConfig
.szLookaside
= va_arg(ap
, int);
461 sqlite3GlobalConfig
.nLookaside
= va_arg(ap
, int);
465 /* Record a pointer to the logger funcction and its first argument.
466 ** The default is NULL. Logging is disabled if the function pointer is
469 case SQLITE_CONFIG_LOG
: {
470 /* MSVC is picky about pulling func ptrs from va lists.
471 ** http://support.microsoft.com/kb/47961
472 ** sqlite3GlobalConfig.xLog = va_arg(ap, void(*)(void*,int,const char*));
474 typedef void(*LOGFUNC_t
)(void*,int,const char*);
475 sqlite3GlobalConfig
.xLog
= va_arg(ap
, LOGFUNC_t
);
476 sqlite3GlobalConfig
.pLogArg
= va_arg(ap
, void*);
480 case SQLITE_CONFIG_URI
: {
481 sqlite3GlobalConfig
.bOpenUri
= va_arg(ap
, int);
485 case SQLITE_CONFIG_COVERING_INDEX_SCAN
: {
486 sqlite3GlobalConfig
.bUseCis
= va_arg(ap
, int);
490 #ifdef SQLITE_ENABLE_SQLLOG
491 case SQLITE_CONFIG_SQLLOG
: {
492 typedef void(*SQLLOGFUNC_t
)(void*, sqlite3
*, const char*, int);
493 sqlite3GlobalConfig
.xSqllog
= va_arg(ap
, SQLLOGFUNC_t
);
494 sqlite3GlobalConfig
.pSqllogArg
= va_arg(ap
, void *);
499 case SQLITE_CONFIG_MMAP_SIZE
: {
500 sqlite3_int64 szMmap
= va_arg(ap
, sqlite3_int64
);
501 sqlite3_int64 mxMmap
= va_arg(ap
, sqlite3_int64
);
502 if( mxMmap
<0 || mxMmap
>SQLITE_MAX_MMAP_SIZE
){
503 mxMmap
= SQLITE_MAX_MMAP_SIZE
;
505 sqlite3GlobalConfig
.mxMmap
= mxMmap
;
506 if( szMmap
<0 ) szMmap
= SQLITE_DEFAULT_MMAP_SIZE
;
507 if( szMmap
>mxMmap
) szMmap
= mxMmap
;
508 sqlite3GlobalConfig
.szMmap
= szMmap
;
522 ** Set up the lookaside buffers for a database connection.
523 ** Return SQLITE_OK on success.
524 ** If lookaside is already active, return SQLITE_BUSY.
526 ** The sz parameter is the number of bytes in each lookaside slot.
527 ** The cnt parameter is the number of slots. If pStart is NULL the
528 ** space for the lookaside memory is obtained from sqlite3_malloc().
529 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
530 ** the lookaside memory.
532 static int setupLookaside(sqlite3
*db
, void *pBuf
, int sz
, int cnt
){
534 if( db
->lookaside
.nOut
){
537 /* Free any existing lookaside buffer for this handle before
538 ** allocating a new one so we don't have to have space for
539 ** both at the same time.
541 if( db
->lookaside
.bMalloced
){
542 sqlite3_free(db
->lookaside
.pStart
);
544 /* The size of a lookaside slot after ROUNDDOWN8 needs to be larger
545 ** than a pointer to be useful.
547 sz
= ROUNDDOWN8(sz
); /* IMP: R-33038-09382 */
548 if( sz
<=(int)sizeof(LookasideSlot
*) ) sz
= 0;
550 if( sz
==0 || cnt
==0 ){
554 sqlite3BeginBenignMalloc();
555 pStart
= sqlite3Malloc( sz
*cnt
); /* IMP: R-61949-35727 */
556 sqlite3EndBenignMalloc();
557 if( pStart
) cnt
= sqlite3MallocSize(pStart
)/sz
;
561 db
->lookaside
.pStart
= pStart
;
562 db
->lookaside
.pFree
= 0;
563 db
->lookaside
.sz
= (u16
)sz
;
567 assert( sz
> (int)sizeof(LookasideSlot
*) );
568 p
= (LookasideSlot
*)pStart
;
569 for(i
=cnt
-1; i
>=0; i
--){
570 p
->pNext
= db
->lookaside
.pFree
;
571 db
->lookaside
.pFree
= p
;
572 p
= (LookasideSlot
*)&((u8
*)p
)[sz
];
574 db
->lookaside
.pEnd
= p
;
575 db
->lookaside
.bEnabled
= 1;
576 db
->lookaside
.bMalloced
= pBuf
==0 ?1:0;
578 db
->lookaside
.pEnd
= 0;
579 db
->lookaside
.bEnabled
= 0;
580 db
->lookaside
.bMalloced
= 0;
586 ** Return the mutex associated with a database connection.
588 sqlite3_mutex
*sqlite3_db_mutex(sqlite3
*db
){
593 ** Free up as much memory as we can from the given database
596 int sqlite3_db_release_memory(sqlite3
*db
){
598 sqlite3_mutex_enter(db
->mutex
);
599 sqlite3BtreeEnterAll(db
);
600 for(i
=0; i
<db
->nDb
; i
++){
601 Btree
*pBt
= db
->aDb
[i
].pBt
;
603 Pager
*pPager
= sqlite3BtreePager(pBt
);
604 sqlite3PagerShrink(pPager
);
607 sqlite3BtreeLeaveAll(db
);
608 sqlite3_mutex_leave(db
->mutex
);
613 ** Configuration settings for an individual database connection
615 int sqlite3_db_config(sqlite3
*db
, int op
, ...){
620 case SQLITE_DBCONFIG_LOOKASIDE
: {
621 void *pBuf
= va_arg(ap
, void*); /* IMP: R-26835-10964 */
622 int sz
= va_arg(ap
, int); /* IMP: R-47871-25994 */
623 int cnt
= va_arg(ap
, int); /* IMP: R-04460-53386 */
624 rc
= setupLookaside(db
, pBuf
, sz
, cnt
);
628 static const struct {
629 int op
; /* The opcode */
630 u32 mask
; /* Mask of the bit in sqlite3.flags to set/clear */
632 { SQLITE_DBCONFIG_ENABLE_FKEY
, SQLITE_ForeignKeys
},
633 { SQLITE_DBCONFIG_ENABLE_TRIGGER
, SQLITE_EnableTrigger
},
636 rc
= SQLITE_ERROR
; /* IMP: R-42790-23372 */
637 for(i
=0; i
<ArraySize(aFlagOp
); i
++){
638 if( aFlagOp
[i
].op
==op
){
639 int onoff
= va_arg(ap
, int);
640 int *pRes
= va_arg(ap
, int*);
641 int oldFlags
= db
->flags
;
643 db
->flags
|= aFlagOp
[i
].mask
;
644 }else if( onoff
==0 ){
645 db
->flags
&= ~aFlagOp
[i
].mask
;
647 if( oldFlags
!=db
->flags
){
648 sqlite3ExpirePreparedStatements(db
);
651 *pRes
= (db
->flags
& aFlagOp
[i
].mask
)!=0;
666 ** Return true if the buffer z[0..n-1] contains all spaces.
668 static int allSpaces(const char *z
, int n
){
669 while( n
>0 && z
[n
-1]==' ' ){ n
--; }
674 ** This is the default collating function named "BINARY" which is always
677 ** If the padFlag argument is not NULL then space padding at the end
678 ** of strings is ignored. This implements the RTRIM collation.
680 static int binCollFunc(
682 int nKey1
, const void *pKey1
,
683 int nKey2
, const void *pKey2
686 n
= nKey1
<nKey2
? nKey1
: nKey2
;
687 rc
= memcmp(pKey1
, pKey2
, n
);
690 && allSpaces(((char*)pKey1
)+n
, nKey1
-n
)
691 && allSpaces(((char*)pKey2
)+n
, nKey2
-n
)
693 /* Leave rc unchanged at 0 */
702 ** Another built-in collating sequence: NOCASE.
704 ** This collating sequence is intended to be used for "case independant
705 ** comparison". SQLite's knowledge of upper and lower case equivalents
706 ** extends only to the 26 characters used in the English language.
708 ** At the moment there is only a UTF-8 implementation.
710 static int nocaseCollatingFunc(
712 int nKey1
, const void *pKey1
,
713 int nKey2
, const void *pKey2
715 int r
= sqlite3StrNICmp(
716 (const char *)pKey1
, (const char *)pKey2
, (nKey1
<nKey2
)?nKey1
:nKey2
);
717 UNUSED_PARAMETER(NotUsed
);
725 ** Return the ROWID of the most recent insert
727 sqlite_int64
sqlite3_last_insert_rowid(sqlite3
*db
){
728 return db
->lastRowid
;
732 ** Return the number of changes in the most recent call to sqlite3_exec().
734 int sqlite3_changes(sqlite3
*db
){
739 ** Return the number of changes since the database handle was opened.
741 int sqlite3_total_changes(sqlite3
*db
){
742 return db
->nTotalChange
;
746 ** Close all open savepoints. This function only manipulates fields of the
747 ** database handle object, it does not close any savepoints that may be open
748 ** at the b-tree/pager level.
750 void sqlite3CloseSavepoints(sqlite3
*db
){
751 while( db
->pSavepoint
){
752 Savepoint
*pTmp
= db
->pSavepoint
;
753 db
->pSavepoint
= pTmp
->pNext
;
754 sqlite3DbFree(db
, pTmp
);
758 db
->isTransactionSavepoint
= 0;
762 ** Invoke the destructor function associated with FuncDef p, if any. Except,
763 ** if this is not the last copy of the function, do not invoke it. Multiple
764 ** copies of a single function are created when create_function() is called
765 ** with SQLITE_ANY as the encoding.
767 static void functionDestroy(sqlite3
*db
, FuncDef
*p
){
768 FuncDestructor
*pDestructor
= p
->pDestructor
;
771 if( pDestructor
->nRef
==0 ){
772 pDestructor
->xDestroy(pDestructor
->pUserData
);
773 sqlite3DbFree(db
, pDestructor
);
779 ** Disconnect all sqlite3_vtab objects that belong to database connection
780 ** db. This is called when db is being closed.
782 static void disconnectAllVtab(sqlite3
*db
){
783 #ifndef SQLITE_OMIT_VIRTUALTABLE
785 sqlite3BtreeEnterAll(db
);
786 for(i
=0; i
<db
->nDb
; i
++){
787 Schema
*pSchema
= db
->aDb
[i
].pSchema
;
788 if( db
->aDb
[i
].pSchema
){
790 for(p
=sqliteHashFirst(&pSchema
->tblHash
); p
; p
=sqliteHashNext(p
)){
791 Table
*pTab
= (Table
*)sqliteHashData(p
);
792 if( IsVirtual(pTab
) ) sqlite3VtabDisconnect(db
, pTab
);
796 sqlite3BtreeLeaveAll(db
);
798 UNUSED_PARAMETER(db
);
803 ** Return TRUE if database connection db has unfinalized prepared
804 ** statements or unfinished sqlite3_backup objects.
806 static int connectionIsBusy(sqlite3
*db
){
808 assert( sqlite3_mutex_held(db
->mutex
) );
809 if( db
->pVdbe
) return 1;
810 for(j
=0; j
<db
->nDb
; j
++){
811 Btree
*pBt
= db
->aDb
[j
].pBt
;
812 if( pBt
&& sqlite3BtreeIsInBackup(pBt
) ) return 1;
818 ** Close an existing SQLite database
820 static int sqlite3Close(sqlite3
*db
, int forceZombie
){
824 if( !sqlite3SafetyCheckSickOrOk(db
) ){
825 return SQLITE_MISUSE_BKPT
;
827 sqlite3_mutex_enter(db
->mutex
);
829 /* Force xDisconnect calls on all virtual tables */
830 disconnectAllVtab(db
);
832 /* If a transaction is open, the disconnectAllVtab() call above
833 ** will not have called the xDisconnect() method on any virtual
834 ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()
835 ** call will do so. We need to do this before the check for active
836 ** SQL statements below, as the v-table implementation may be storing
837 ** some prepared statements internally.
839 sqlite3VtabRollback(db
);
841 /* Legacy behavior (sqlite3_close() behavior) is to return
842 ** SQLITE_BUSY if the connection can not be closed immediately.
844 if( !forceZombie
&& connectionIsBusy(db
) ){
845 sqlite3Error(db
, SQLITE_BUSY
, "unable to close due to unfinalized "
846 "statements or unfinished backups");
847 sqlite3_mutex_leave(db
->mutex
);
851 #ifdef SQLITE_ENABLE_SQLLOG
852 if( sqlite3GlobalConfig
.xSqllog
){
853 /* Closing the handle. Fourth parameter is passed the value 2. */
854 sqlite3GlobalConfig
.xSqllog(sqlite3GlobalConfig
.pSqllogArg
, db
, 0, 2);
858 /* Convert the connection into a zombie and then close it.
860 db
->magic
= SQLITE_MAGIC_ZOMBIE
;
861 sqlite3LeaveMutexAndCloseZombie(db
);
866 ** Two variations on the public interface for closing a database
867 ** connection. The sqlite3_close() version returns SQLITE_BUSY and
868 ** leaves the connection option if there are unfinalized prepared
869 ** statements or unfinished sqlite3_backups. The sqlite3_close_v2()
870 ** version forces the connection to become a zombie if there are
871 ** unclosed resources, and arranges for deallocation when the last
872 ** prepare statement or sqlite3_backup closes.
874 int sqlite3_close(sqlite3
*db
){ return sqlite3Close(db
,0); }
875 int sqlite3_close_v2(sqlite3
*db
){ return sqlite3Close(db
,1); }
879 ** Close the mutex on database connection db.
881 ** Furthermore, if database connection db is a zombie (meaning that there
882 ** has been a prior call to sqlite3_close(db) or sqlite3_close_v2(db)) and
883 ** every sqlite3_stmt has now been finalized and every sqlite3_backup has
884 ** finished, then free all resources.
886 void sqlite3LeaveMutexAndCloseZombie(sqlite3
*db
){
887 HashElem
*i
; /* Hash table iterator */
890 /* If there are outstanding sqlite3_stmt or sqlite3_backup objects
891 ** or if the connection has not yet been closed by sqlite3_close_v2(),
892 ** then just leave the mutex and return.
894 if( db
->magic
!=SQLITE_MAGIC_ZOMBIE
|| connectionIsBusy(db
) ){
895 sqlite3_mutex_leave(db
->mutex
);
899 /* If we reach this point, it means that the database connection has
900 ** closed all sqlite3_stmt and sqlite3_backup objects and has been
901 ** passed to sqlite3_close (meaning that it is a zombie). Therefore,
902 ** go ahead and free all resources.
905 /* If a transaction is open, roll it back. This also ensures that if
906 ** any database schemas have been modified by an uncommitted transaction
907 ** they are reset. And that the required b-tree mutex is held to make
908 ** the pager rollback and schema reset an atomic operation. */
909 sqlite3RollbackAll(db
, SQLITE_OK
);
911 /* Free any outstanding Savepoint structures. */
912 sqlite3CloseSavepoints(db
);
914 /* Close all database connections */
915 for(j
=0; j
<db
->nDb
; j
++){
916 struct Db
*pDb
= &db
->aDb
[j
];
918 sqlite3BtreeClose(pDb
->pBt
);
925 /* Clear the TEMP schema separately and last */
926 if( db
->aDb
[1].pSchema
){
927 sqlite3SchemaClear(db
->aDb
[1].pSchema
);
929 sqlite3VtabUnlockList(db
);
931 /* Free up the array of auxiliary databases */
932 sqlite3CollapseDatabaseArray(db
);
933 assert( db
->nDb
<=2 );
934 assert( db
->aDb
==db
->aDbStatic
);
936 /* Tell the code in notify.c that the connection no longer holds any
937 ** locks and does not require any further unlock-notify callbacks.
939 sqlite3ConnectionClosed(db
);
941 for(j
=0; j
<ArraySize(db
->aFunc
.a
); j
++){
942 FuncDef
*pNext
, *pHash
, *p
;
943 for(p
=db
->aFunc
.a
[j
]; p
; p
=pHash
){
946 functionDestroy(db
, p
);
948 sqlite3DbFree(db
, p
);
953 for(i
=sqliteHashFirst(&db
->aCollSeq
); i
; i
=sqliteHashNext(i
)){
954 CollSeq
*pColl
= (CollSeq
*)sqliteHashData(i
);
955 /* Invoke any destructors registered for collation sequence user data. */
958 pColl
[j
].xDel(pColl
[j
].pUser
);
961 sqlite3DbFree(db
, pColl
);
963 sqlite3HashClear(&db
->aCollSeq
);
964 #ifndef SQLITE_OMIT_VIRTUALTABLE
965 for(i
=sqliteHashFirst(&db
->aModule
); i
; i
=sqliteHashNext(i
)){
966 Module
*pMod
= (Module
*)sqliteHashData(i
);
967 if( pMod
->xDestroy
){
968 pMod
->xDestroy(pMod
->pAux
);
970 sqlite3DbFree(db
, pMod
);
972 sqlite3HashClear(&db
->aModule
);
975 sqlite3Error(db
, SQLITE_OK
, 0); /* Deallocates any cached error strings. */
977 sqlite3ValueFree(db
->pErr
);
979 sqlite3CloseExtensions(db
);
981 db
->magic
= SQLITE_MAGIC_ERROR
;
983 /* The temp-database schema is allocated differently from the other schema
984 ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).
985 ** So it needs to be freed here. Todo: Why not roll the temp schema into
986 ** the same sqliteMalloc() as the one that allocates the database
989 sqlite3DbFree(db
, db
->aDb
[1].pSchema
);
990 sqlite3_mutex_leave(db
->mutex
);
991 db
->magic
= SQLITE_MAGIC_CLOSED
;
992 sqlite3_mutex_free(db
->mutex
);
993 assert( db
->lookaside
.nOut
==0 ); /* Fails on a lookaside memory leak */
994 if( db
->lookaside
.bMalloced
){
995 sqlite3_free(db
->lookaside
.pStart
);
1001 ** Rollback all database files. If tripCode is not SQLITE_OK, then
1002 ** any open cursors are invalidated ("tripped" - as in "tripping a circuit
1003 ** breaker") and made to return tripCode if there are any further
1004 ** attempts to use that cursor.
1006 void sqlite3RollbackAll(sqlite3
*db
, int tripCode
){
1009 assert( sqlite3_mutex_held(db
->mutex
) );
1010 sqlite3BeginBenignMalloc();
1012 /* Obtain all b-tree mutexes before making any calls to BtreeRollback().
1013 ** This is important in case the transaction being rolled back has
1014 ** modified the database schema. If the b-tree mutexes are not taken
1015 ** here, then another shared-cache connection might sneak in between
1016 ** the database rollback and schema reset, which can cause false
1017 ** corruption reports in some cases. */
1018 sqlite3BtreeEnterAll(db
);
1020 for(i
=0; i
<db
->nDb
; i
++){
1021 Btree
*p
= db
->aDb
[i
].pBt
;
1023 if( sqlite3BtreeIsInTrans(p
) ){
1026 sqlite3BtreeRollback(p
, tripCode
);
1027 db
->aDb
[i
].inTrans
= 0;
1030 sqlite3VtabRollback(db
);
1031 sqlite3EndBenignMalloc();
1033 if( (db
->flags
&SQLITE_InternChanges
)!=0 && db
->init
.busy
==0 ){
1034 sqlite3ExpirePreparedStatements(db
);
1035 sqlite3ResetAllSchemasOfConnection(db
);
1037 sqlite3BtreeLeaveAll(db
);
1039 /* Any deferred constraint violations have now been resolved. */
1040 db
->nDeferredCons
= 0;
1042 /* If one has been configured, invoke the rollback-hook callback */
1043 if( db
->xRollbackCallback
&& (inTrans
|| !db
->autoCommit
) ){
1044 db
->xRollbackCallback(db
->pRollbackArg
);
1049 ** Return a static string containing the name corresponding to the error code
1050 ** specified in the argument.
1052 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) || \
1053 defined(SQLITE_DEBUG_OS_TRACE)
1054 const char *sqlite3ErrName(int rc
){
1055 const char *zName
= 0;
1057 for(i
=0; i
<2 && zName
==0; i
++, rc
&= 0xff){
1059 case SQLITE_OK
: zName
= "SQLITE_OK"; break;
1060 case SQLITE_ERROR
: zName
= "SQLITE_ERROR"; break;
1061 case SQLITE_INTERNAL
: zName
= "SQLITE_INTERNAL"; break;
1062 case SQLITE_PERM
: zName
= "SQLITE_PERM"; break;
1063 case SQLITE_ABORT
: zName
= "SQLITE_ABORT"; break;
1064 case SQLITE_ABORT_ROLLBACK
: zName
= "SQLITE_ABORT_ROLLBACK"; break;
1065 case SQLITE_BUSY
: zName
= "SQLITE_BUSY"; break;
1066 case SQLITE_BUSY_RECOVERY
: zName
= "SQLITE_BUSY_RECOVERY"; break;
1067 case SQLITE_LOCKED
: zName
= "SQLITE_LOCKED"; break;
1068 case SQLITE_LOCKED_SHAREDCACHE
: zName
= "SQLITE_LOCKED_SHAREDCACHE";break;
1069 case SQLITE_NOMEM
: zName
= "SQLITE_NOMEM"; break;
1070 case SQLITE_READONLY
: zName
= "SQLITE_READONLY"; break;
1071 case SQLITE_READONLY_RECOVERY
: zName
= "SQLITE_READONLY_RECOVERY"; break;
1072 case SQLITE_READONLY_CANTLOCK
: zName
= "SQLITE_READONLY_CANTLOCK"; break;
1073 case SQLITE_READONLY_ROLLBACK
: zName
= "SQLITE_READONLY_ROLLBACK"; break;
1074 case SQLITE_INTERRUPT
: zName
= "SQLITE_INTERRUPT"; break;
1075 case SQLITE_IOERR
: zName
= "SQLITE_IOERR"; break;
1076 case SQLITE_IOERR_READ
: zName
= "SQLITE_IOERR_READ"; break;
1077 case SQLITE_IOERR_SHORT_READ
: zName
= "SQLITE_IOERR_SHORT_READ"; break;
1078 case SQLITE_IOERR_WRITE
: zName
= "SQLITE_IOERR_WRITE"; break;
1079 case SQLITE_IOERR_FSYNC
: zName
= "SQLITE_IOERR_FSYNC"; break;
1080 case SQLITE_IOERR_DIR_FSYNC
: zName
= "SQLITE_IOERR_DIR_FSYNC"; break;
1081 case SQLITE_IOERR_TRUNCATE
: zName
= "SQLITE_IOERR_TRUNCATE"; break;
1082 case SQLITE_IOERR_FSTAT
: zName
= "SQLITE_IOERR_FSTAT"; break;
1083 case SQLITE_IOERR_UNLOCK
: zName
= "SQLITE_IOERR_UNLOCK"; break;
1084 case SQLITE_IOERR_RDLOCK
: zName
= "SQLITE_IOERR_RDLOCK"; break;
1085 case SQLITE_IOERR_DELETE
: zName
= "SQLITE_IOERR_DELETE"; break;
1086 case SQLITE_IOERR_BLOCKED
: zName
= "SQLITE_IOERR_BLOCKED"; break;
1087 case SQLITE_IOERR_NOMEM
: zName
= "SQLITE_IOERR_NOMEM"; break;
1088 case SQLITE_IOERR_ACCESS
: zName
= "SQLITE_IOERR_ACCESS"; break;
1089 case SQLITE_IOERR_CHECKRESERVEDLOCK
:
1090 zName
= "SQLITE_IOERR_CHECKRESERVEDLOCK"; break;
1091 case SQLITE_IOERR_LOCK
: zName
= "SQLITE_IOERR_LOCK"; break;
1092 case SQLITE_IOERR_CLOSE
: zName
= "SQLITE_IOERR_CLOSE"; break;
1093 case SQLITE_IOERR_DIR_CLOSE
: zName
= "SQLITE_IOERR_DIR_CLOSE"; break;
1094 case SQLITE_IOERR_SHMOPEN
: zName
= "SQLITE_IOERR_SHMOPEN"; break;
1095 case SQLITE_IOERR_SHMSIZE
: zName
= "SQLITE_IOERR_SHMSIZE"; break;
1096 case SQLITE_IOERR_SHMLOCK
: zName
= "SQLITE_IOERR_SHMLOCK"; break;
1097 case SQLITE_IOERR_SHMMAP
: zName
= "SQLITE_IOERR_SHMMAP"; break;
1098 case SQLITE_IOERR_SEEK
: zName
= "SQLITE_IOERR_SEEK"; break;
1099 case SQLITE_IOERR_DELETE_NOENT
: zName
= "SQLITE_IOERR_DELETE_NOENT";break;
1100 case SQLITE_IOERR_MMAP
: zName
= "SQLITE_IOERR_MMAP"; break;
1101 case SQLITE_CORRUPT
: zName
= "SQLITE_CORRUPT"; break;
1102 case SQLITE_CORRUPT_VTAB
: zName
= "SQLITE_CORRUPT_VTAB"; break;
1103 case SQLITE_NOTFOUND
: zName
= "SQLITE_NOTFOUND"; break;
1104 case SQLITE_FULL
: zName
= "SQLITE_FULL"; break;
1105 case SQLITE_CANTOPEN
: zName
= "SQLITE_CANTOPEN"; break;
1106 case SQLITE_CANTOPEN_NOTEMPDIR
: zName
= "SQLITE_CANTOPEN_NOTEMPDIR";break;
1107 case SQLITE_CANTOPEN_ISDIR
: zName
= "SQLITE_CANTOPEN_ISDIR"; break;
1108 case SQLITE_CANTOPEN_FULLPATH
: zName
= "SQLITE_CANTOPEN_FULLPATH"; break;
1109 case SQLITE_PROTOCOL
: zName
= "SQLITE_PROTOCOL"; break;
1110 case SQLITE_EMPTY
: zName
= "SQLITE_EMPTY"; break;
1111 case SQLITE_SCHEMA
: zName
= "SQLITE_SCHEMA"; break;
1112 case SQLITE_TOOBIG
: zName
= "SQLITE_TOOBIG"; break;
1113 case SQLITE_CONSTRAINT
: zName
= "SQLITE_CONSTRAINT"; break;
1114 case SQLITE_CONSTRAINT_UNIQUE
: zName
= "SQLITE_CONSTRAINT_UNIQUE"; break;
1115 case SQLITE_CONSTRAINT_TRIGGER
: zName
= "SQLITE_CONSTRAINT_TRIGGER";break;
1116 case SQLITE_CONSTRAINT_FOREIGNKEY
:
1117 zName
= "SQLITE_CONSTRAINT_FOREIGNKEY"; break;
1118 case SQLITE_CONSTRAINT_CHECK
: zName
= "SQLITE_CONSTRAINT_CHECK"; break;
1119 case SQLITE_CONSTRAINT_PRIMARYKEY
:
1120 zName
= "SQLITE_CONSTRAINT_PRIMARYKEY"; break;
1121 case SQLITE_CONSTRAINT_NOTNULL
: zName
= "SQLITE_CONSTRAINT_NOTNULL";break;
1122 case SQLITE_CONSTRAINT_COMMITHOOK
:
1123 zName
= "SQLITE_CONSTRAINT_COMMITHOOK"; break;
1124 case SQLITE_CONSTRAINT_VTAB
: zName
= "SQLITE_CONSTRAINT_VTAB"; break;
1125 case SQLITE_CONSTRAINT_FUNCTION
:
1126 zName
= "SQLITE_CONSTRAINT_FUNCTION"; break;
1127 case SQLITE_MISMATCH
: zName
= "SQLITE_MISMATCH"; break;
1128 case SQLITE_MISUSE
: zName
= "SQLITE_MISUSE"; break;
1129 case SQLITE_NOLFS
: zName
= "SQLITE_NOLFS"; break;
1130 case SQLITE_AUTH
: zName
= "SQLITE_AUTH"; break;
1131 case SQLITE_FORMAT
: zName
= "SQLITE_FORMAT"; break;
1132 case SQLITE_RANGE
: zName
= "SQLITE_RANGE"; break;
1133 case SQLITE_NOTADB
: zName
= "SQLITE_NOTADB"; break;
1134 case SQLITE_ROW
: zName
= "SQLITE_ROW"; break;
1135 case SQLITE_NOTICE
: zName
= "SQLITE_NOTICE"; break;
1136 case SQLITE_NOTICE_RECOVER_WAL
: zName
= "SQLITE_NOTICE_RECOVER_WAL";break;
1137 case SQLITE_NOTICE_RECOVER_ROLLBACK
:
1138 zName
= "SQLITE_NOTICE_RECOVER_ROLLBACK"; break;
1139 case SQLITE_WARNING
: zName
= "SQLITE_WARNING"; break;
1140 case SQLITE_DONE
: zName
= "SQLITE_DONE"; break;
1144 static char zBuf
[50];
1145 sqlite3_snprintf(sizeof(zBuf
), zBuf
, "SQLITE_UNKNOWN(%d)", origRc
);
1153 ** Return a static string that describes the kind of error specified in the
1156 const char *sqlite3ErrStr(int rc
){
1157 static const char* const aMsg
[] = {
1158 /* SQLITE_OK */ "not an error",
1159 /* SQLITE_ERROR */ "SQL logic error or missing database",
1160 /* SQLITE_INTERNAL */ 0,
1161 /* SQLITE_PERM */ "access permission denied",
1162 /* SQLITE_ABORT */ "callback requested query abort",
1163 /* SQLITE_BUSY */ "database is locked",
1164 /* SQLITE_LOCKED */ "database table is locked",
1165 /* SQLITE_NOMEM */ "out of memory",
1166 /* SQLITE_READONLY */ "attempt to write a readonly database",
1167 /* SQLITE_INTERRUPT */ "interrupted",
1168 /* SQLITE_IOERR */ "disk I/O error",
1169 /* SQLITE_CORRUPT */ "database disk image is malformed",
1170 /* SQLITE_NOTFOUND */ "unknown operation",
1171 /* SQLITE_FULL */ "database or disk is full",
1172 /* SQLITE_CANTOPEN */ "unable to open database file",
1173 /* SQLITE_PROTOCOL */ "locking protocol",
1174 /* SQLITE_EMPTY */ "table contains no data",
1175 /* SQLITE_SCHEMA */ "database schema has changed",
1176 /* SQLITE_TOOBIG */ "string or blob too big",
1177 /* SQLITE_CONSTRAINT */ "constraint failed",
1178 /* SQLITE_MISMATCH */ "datatype mismatch",
1179 /* SQLITE_MISUSE */ "library routine called out of sequence",
1180 /* SQLITE_NOLFS */ "large file support is disabled",
1181 /* SQLITE_AUTH */ "authorization denied",
1182 /* SQLITE_FORMAT */ "auxiliary database format error",
1183 /* SQLITE_RANGE */ "bind or column index out of range",
1184 /* SQLITE_NOTADB */ "file is encrypted or is not a database",
1186 const char *zErr
= "unknown error";
1188 case SQLITE_ABORT_ROLLBACK
: {
1189 zErr
= "abort due to ROLLBACK";
1194 if( ALWAYS(rc
>=0) && rc
<ArraySize(aMsg
) && aMsg
[rc
]!=0 ){
1204 ** This routine implements a busy callback that sleeps and tries
1205 ** again until a timeout value is reached. The timeout value is
1206 ** an integer number of milliseconds passed in as the first
1209 static int sqliteDefaultBusyCallback(
1210 void *ptr
, /* Database connection */
1211 int count
/* Number of times table has been busy */
1213 #if SQLITE_OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)
1214 static const u8 delays
[] =
1215 { 1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100 };
1216 static const u8 totals
[] =
1217 { 0, 1, 3, 8, 18, 33, 53, 78, 103, 128, 178, 228 };
1218 # define NDELAY ArraySize(delays)
1219 sqlite3
*db
= (sqlite3
*)ptr
;
1220 int timeout
= db
->busyTimeout
;
1224 if( count
< NDELAY
){
1225 delay
= delays
[count
];
1226 prior
= totals
[count
];
1228 delay
= delays
[NDELAY
-1];
1229 prior
= totals
[NDELAY
-1] + delay
*(count
-(NDELAY
-1));
1231 if( prior
+ delay
> timeout
){
1232 delay
= timeout
- prior
;
1233 if( delay
<=0 ) return 0;
1235 sqlite3OsSleep(db
->pVfs
, delay
*1000);
1238 sqlite3
*db
= (sqlite3
*)ptr
;
1239 int timeout
= ((sqlite3
*)ptr
)->busyTimeout
;
1240 if( (count
+1)*1000 > timeout
){
1243 sqlite3OsSleep(db
->pVfs
, 1000000);
1249 ** Invoke the given busy handler.
1251 ** This routine is called when an operation failed with a lock.
1252 ** If this routine returns non-zero, the lock is retried. If it
1253 ** returns 0, the operation aborts with an SQLITE_BUSY error.
1255 int sqlite3InvokeBusyHandler(BusyHandler
*p
){
1257 if( NEVER(p
==0) || p
->xFunc
==0 || p
->nBusy
<0 ) return 0;
1258 rc
= p
->xFunc(p
->pArg
, p
->nBusy
);
1268 ** This routine sets the busy callback for an Sqlite database to the
1269 ** given callback function with the given argument.
1271 int sqlite3_busy_handler(
1273 int (*xBusy
)(void*,int),
1276 sqlite3_mutex_enter(db
->mutex
);
1277 db
->busyHandler
.xFunc
= xBusy
;
1278 db
->busyHandler
.pArg
= pArg
;
1279 db
->busyHandler
.nBusy
= 0;
1280 db
->busyTimeout
= 0;
1281 sqlite3_mutex_leave(db
->mutex
);
1285 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
1287 ** This routine sets the progress callback for an Sqlite database to the
1288 ** given callback function with the given argument. The progress callback will
1289 ** be invoked every nOps opcodes.
1291 void sqlite3_progress_handler(
1294 int (*xProgress
)(void*),
1297 sqlite3_mutex_enter(db
->mutex
);
1299 db
->xProgress
= xProgress
;
1300 db
->nProgressOps
= nOps
;
1301 db
->pProgressArg
= pArg
;
1304 db
->nProgressOps
= 0;
1305 db
->pProgressArg
= 0;
1307 sqlite3_mutex_leave(db
->mutex
);
1313 ** This routine installs a default busy handler that waits for the
1314 ** specified number of milliseconds before returning 0.
1316 int sqlite3_busy_timeout(sqlite3
*db
, int ms
){
1318 sqlite3_busy_handler(db
, sqliteDefaultBusyCallback
, (void*)db
);
1319 db
->busyTimeout
= ms
;
1321 sqlite3_busy_handler(db
, 0, 0);
1327 ** Cause any pending operation to stop at its earliest opportunity.
1329 void sqlite3_interrupt(sqlite3
*db
){
1330 db
->u1
.isInterrupted
= 1;
1335 ** This function is exactly the same as sqlite3_create_function(), except
1336 ** that it is designed to be called by internal code. The difference is
1337 ** that if a malloc() fails in sqlite3_create_function(), an error code
1338 ** is returned and the mallocFailed flag cleared.
1340 int sqlite3CreateFunc(
1342 const char *zFunctionName
,
1346 void (*xFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1347 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1348 void (*xFinal
)(sqlite3_context
*),
1349 FuncDestructor
*pDestructor
1354 assert( sqlite3_mutex_held(db
->mutex
) );
1355 if( zFunctionName
==0 ||
1356 (xFunc
&& (xFinal
|| xStep
)) ||
1357 (!xFunc
&& (xFinal
&& !xStep
)) ||
1358 (!xFunc
&& (!xFinal
&& xStep
)) ||
1359 (nArg
<-1 || nArg
>SQLITE_MAX_FUNCTION_ARG
) ||
1360 (255<(nName
= sqlite3Strlen30( zFunctionName
))) ){
1361 return SQLITE_MISUSE_BKPT
;
1364 #ifndef SQLITE_OMIT_UTF16
1365 /* If SQLITE_UTF16 is specified as the encoding type, transform this
1366 ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
1367 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
1369 ** If SQLITE_ANY is specified, add three versions of the function
1370 ** to the hash table.
1372 if( enc
==SQLITE_UTF16
){
1373 enc
= SQLITE_UTF16NATIVE
;
1374 }else if( enc
==SQLITE_ANY
){
1376 rc
= sqlite3CreateFunc(db
, zFunctionName
, nArg
, SQLITE_UTF8
,
1377 pUserData
, xFunc
, xStep
, xFinal
, pDestructor
);
1378 if( rc
==SQLITE_OK
){
1379 rc
= sqlite3CreateFunc(db
, zFunctionName
, nArg
, SQLITE_UTF16LE
,
1380 pUserData
, xFunc
, xStep
, xFinal
, pDestructor
);
1382 if( rc
!=SQLITE_OK
){
1385 enc
= SQLITE_UTF16BE
;
1391 /* Check if an existing function is being overridden or deleted. If so,
1392 ** and there are active VMs, then return SQLITE_BUSY. If a function
1393 ** is being overridden/deleted but there are no active VMs, allow the
1394 ** operation to continue but invalidate all precompiled statements.
1396 p
= sqlite3FindFunction(db
, zFunctionName
, nName
, nArg
, (u8
)enc
, 0);
1397 if( p
&& p
->iPrefEnc
==enc
&& p
->nArg
==nArg
){
1398 if( db
->activeVdbeCnt
){
1399 sqlite3Error(db
, SQLITE_BUSY
,
1400 "unable to delete/modify user-function due to active statements");
1401 assert( !db
->mallocFailed
);
1404 sqlite3ExpirePreparedStatements(db
);
1408 p
= sqlite3FindFunction(db
, zFunctionName
, nName
, nArg
, (u8
)enc
, 1);
1409 assert(p
|| db
->mallocFailed
);
1411 return SQLITE_NOMEM
;
1414 /* If an older version of the function with a configured destructor is
1415 ** being replaced invoke the destructor function here. */
1416 functionDestroy(db
, p
);
1419 pDestructor
->nRef
++;
1421 p
->pDestructor
= pDestructor
;
1425 p
->xFinalize
= xFinal
;
1426 p
->pUserData
= pUserData
;
1427 p
->nArg
= (u16
)nArg
;
1432 ** Create new user functions.
1434 int sqlite3_create_function(
1440 void (*xFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1441 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1442 void (*xFinal
)(sqlite3_context
*)
1444 return sqlite3_create_function_v2(db
, zFunc
, nArg
, enc
, p
, xFunc
, xStep
,
1448 int sqlite3_create_function_v2(
1454 void (*xFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1455 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1456 void (*xFinal
)(sqlite3_context
*),
1457 void (*xDestroy
)(void *)
1459 int rc
= SQLITE_ERROR
;
1460 FuncDestructor
*pArg
= 0;
1461 sqlite3_mutex_enter(db
->mutex
);
1463 pArg
= (FuncDestructor
*)sqlite3DbMallocZero(db
, sizeof(FuncDestructor
));
1468 pArg
->xDestroy
= xDestroy
;
1469 pArg
->pUserData
= p
;
1471 rc
= sqlite3CreateFunc(db
, zFunc
, nArg
, enc
, p
, xFunc
, xStep
, xFinal
, pArg
);
1472 if( pArg
&& pArg
->nRef
==0 ){
1473 assert( rc
!=SQLITE_OK
);
1475 sqlite3DbFree(db
, pArg
);
1479 rc
= sqlite3ApiExit(db
, rc
);
1480 sqlite3_mutex_leave(db
->mutex
);
1484 #ifndef SQLITE_OMIT_UTF16
1485 int sqlite3_create_function16(
1487 const void *zFunctionName
,
1491 void (*xFunc
)(sqlite3_context
*,int,sqlite3_value
**),
1492 void (*xStep
)(sqlite3_context
*,int,sqlite3_value
**),
1493 void (*xFinal
)(sqlite3_context
*)
1497 sqlite3_mutex_enter(db
->mutex
);
1498 assert( !db
->mallocFailed
);
1499 zFunc8
= sqlite3Utf16to8(db
, zFunctionName
, -1, SQLITE_UTF16NATIVE
);
1500 rc
= sqlite3CreateFunc(db
, zFunc8
, nArg
, eTextRep
, p
, xFunc
, xStep
, xFinal
,0);
1501 sqlite3DbFree(db
, zFunc8
);
1502 rc
= sqlite3ApiExit(db
, rc
);
1503 sqlite3_mutex_leave(db
->mutex
);
1510 ** Declare that a function has been overloaded by a virtual table.
1512 ** If the function already exists as a regular global function, then
1513 ** this routine is a no-op. If the function does not exist, then create
1514 ** a new one that always throws a run-time error.
1516 ** When virtual tables intend to provide an overloaded function, they
1517 ** should call this routine to make sure the global function exists.
1518 ** A global function must exist in order for name resolution to work
1521 int sqlite3_overload_function(
1526 int nName
= sqlite3Strlen30(zName
);
1528 sqlite3_mutex_enter(db
->mutex
);
1529 if( sqlite3FindFunction(db
, zName
, nName
, nArg
, SQLITE_UTF8
, 0)==0 ){
1530 rc
= sqlite3CreateFunc(db
, zName
, nArg
, SQLITE_UTF8
,
1531 0, sqlite3InvalidFunction
, 0, 0, 0);
1533 rc
= sqlite3ApiExit(db
, rc
);
1534 sqlite3_mutex_leave(db
->mutex
);
1538 #ifndef SQLITE_OMIT_TRACE
1540 ** Register a trace function. The pArg from the previously registered trace
1543 ** A NULL trace function means that no tracing is executes. A non-NULL
1544 ** trace is a pointer to a function that is invoked at the start of each
1547 void *sqlite3_trace(sqlite3
*db
, void (*xTrace
)(void*,const char*), void *pArg
){
1549 sqlite3_mutex_enter(db
->mutex
);
1550 pOld
= db
->pTraceArg
;
1551 db
->xTrace
= xTrace
;
1552 db
->pTraceArg
= pArg
;
1553 sqlite3_mutex_leave(db
->mutex
);
1557 ** Register a profile function. The pArg from the previously registered
1558 ** profile function is returned.
1560 ** A NULL profile function means that no profiling is executes. A non-NULL
1561 ** profile is a pointer to a function that is invoked at the conclusion of
1562 ** each SQL statement that is run.
1564 void *sqlite3_profile(
1566 void (*xProfile
)(void*,const char*,sqlite_uint64
),
1570 sqlite3_mutex_enter(db
->mutex
);
1571 pOld
= db
->pProfileArg
;
1572 db
->xProfile
= xProfile
;
1573 db
->pProfileArg
= pArg
;
1574 sqlite3_mutex_leave(db
->mutex
);
1577 #endif /* SQLITE_OMIT_TRACE */
1580 ** Register a function to be invoked when a transaction commits.
1581 ** If the invoked function returns non-zero, then the commit becomes a
1584 void *sqlite3_commit_hook(
1585 sqlite3
*db
, /* Attach the hook to this database */
1586 int (*xCallback
)(void*), /* Function to invoke on each commit */
1587 void *pArg
/* Argument to the function */
1590 sqlite3_mutex_enter(db
->mutex
);
1591 pOld
= db
->pCommitArg
;
1592 db
->xCommitCallback
= xCallback
;
1593 db
->pCommitArg
= pArg
;
1594 sqlite3_mutex_leave(db
->mutex
);
1599 ** Register a callback to be invoked each time a row is updated,
1600 ** inserted or deleted using this database connection.
1602 void *sqlite3_update_hook(
1603 sqlite3
*db
, /* Attach the hook to this database */
1604 void (*xCallback
)(void*,int,char const *,char const *,sqlite_int64
),
1605 void *pArg
/* Argument to the function */
1608 sqlite3_mutex_enter(db
->mutex
);
1609 pRet
= db
->pUpdateArg
;
1610 db
->xUpdateCallback
= xCallback
;
1611 db
->pUpdateArg
= pArg
;
1612 sqlite3_mutex_leave(db
->mutex
);
1617 ** Register a callback to be invoked each time a transaction is rolled
1618 ** back by this database connection.
1620 void *sqlite3_rollback_hook(
1621 sqlite3
*db
, /* Attach the hook to this database */
1622 void (*xCallback
)(void*), /* Callback function */
1623 void *pArg
/* Argument to the function */
1626 sqlite3_mutex_enter(db
->mutex
);
1627 pRet
= db
->pRollbackArg
;
1628 db
->xRollbackCallback
= xCallback
;
1629 db
->pRollbackArg
= pArg
;
1630 sqlite3_mutex_leave(db
->mutex
);
1634 #ifndef SQLITE_OMIT_WAL
1636 ** The sqlite3_wal_hook() callback registered by sqlite3_wal_autocheckpoint().
1637 ** Invoke sqlite3_wal_checkpoint if the number of frames in the log file
1638 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
1639 ** wal_autocheckpoint()).
1641 int sqlite3WalDefaultHook(
1642 void *pClientData
, /* Argument */
1643 sqlite3
*db
, /* Connection */
1644 const char *zDb
, /* Database */
1645 int nFrame
/* Size of WAL */
1647 if( nFrame
>=SQLITE_PTR_TO_INT(pClientData
) ){
1648 sqlite3BeginBenignMalloc();
1649 sqlite3_wal_checkpoint(db
, zDb
);
1650 sqlite3EndBenignMalloc();
1654 #endif /* SQLITE_OMIT_WAL */
1657 ** Configure an sqlite3_wal_hook() callback to automatically checkpoint
1658 ** a database after committing a transaction if there are nFrame or
1659 ** more frames in the log file. Passing zero or a negative value as the
1660 ** nFrame parameter disables automatic checkpoints entirely.
1662 ** The callback registered by this function replaces any existing callback
1663 ** registered using sqlite3_wal_hook(). Likewise, registering a callback
1664 ** using sqlite3_wal_hook() disables the automatic checkpoint mechanism
1665 ** configured by this function.
1667 int sqlite3_wal_autocheckpoint(sqlite3
*db
, int nFrame
){
1668 #ifdef SQLITE_OMIT_WAL
1669 UNUSED_PARAMETER(db
);
1670 UNUSED_PARAMETER(nFrame
);
1673 sqlite3_wal_hook(db
, sqlite3WalDefaultHook
, SQLITE_INT_TO_PTR(nFrame
));
1675 sqlite3_wal_hook(db
, 0, 0);
1682 ** Register a callback to be invoked each time a transaction is written
1683 ** into the write-ahead-log by this database connection.
1685 void *sqlite3_wal_hook(
1686 sqlite3
*db
, /* Attach the hook to this db handle */
1687 int(*xCallback
)(void *, sqlite3
*, const char*, int),
1688 void *pArg
/* First argument passed to xCallback() */
1690 #ifndef SQLITE_OMIT_WAL
1692 sqlite3_mutex_enter(db
->mutex
);
1694 db
->xWalCallback
= xCallback
;
1696 sqlite3_mutex_leave(db
->mutex
);
1704 ** Checkpoint database zDb.
1706 int sqlite3_wal_checkpoint_v2(
1707 sqlite3
*db
, /* Database handle */
1708 const char *zDb
, /* Name of attached database (or NULL) */
1709 int eMode
, /* SQLITE_CHECKPOINT_* value */
1710 int *pnLog
, /* OUT: Size of WAL log in frames */
1711 int *pnCkpt
/* OUT: Total number of frames checkpointed */
1713 #ifdef SQLITE_OMIT_WAL
1716 int rc
; /* Return code */
1717 int iDb
= SQLITE_MAX_ATTACHED
; /* sqlite3.aDb[] index of db to checkpoint */
1719 /* Initialize the output variables to -1 in case an error occurs. */
1720 if( pnLog
) *pnLog
= -1;
1721 if( pnCkpt
) *pnCkpt
= -1;
1723 assert( SQLITE_CHECKPOINT_FULL
>SQLITE_CHECKPOINT_PASSIVE
);
1724 assert( SQLITE_CHECKPOINT_FULL
<SQLITE_CHECKPOINT_RESTART
);
1725 assert( SQLITE_CHECKPOINT_PASSIVE
+2==SQLITE_CHECKPOINT_RESTART
);
1726 if( eMode
<SQLITE_CHECKPOINT_PASSIVE
|| eMode
>SQLITE_CHECKPOINT_RESTART
){
1727 return SQLITE_MISUSE
;
1730 sqlite3_mutex_enter(db
->mutex
);
1731 if( zDb
&& zDb
[0] ){
1732 iDb
= sqlite3FindDbName(db
, zDb
);
1736 sqlite3Error(db
, SQLITE_ERROR
, "unknown database: %s", zDb
);
1738 rc
= sqlite3Checkpoint(db
, iDb
, eMode
, pnLog
, pnCkpt
);
1739 sqlite3Error(db
, rc
, 0);
1741 rc
= sqlite3ApiExit(db
, rc
);
1742 sqlite3_mutex_leave(db
->mutex
);
1749 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
1750 ** to contains a zero-length string, all attached databases are
1753 int sqlite3_wal_checkpoint(sqlite3
*db
, const char *zDb
){
1754 return sqlite3_wal_checkpoint_v2(db
, zDb
, SQLITE_CHECKPOINT_PASSIVE
, 0, 0);
1757 #ifndef SQLITE_OMIT_WAL
1759 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
1760 ** not currently open in WAL mode.
1762 ** If a transaction is open on the database being checkpointed, this
1763 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If
1764 ** an error occurs while running the checkpoint, an SQLite error code is
1765 ** returned (i.e. SQLITE_IOERR). Otherwise, SQLITE_OK.
1767 ** The mutex on database handle db should be held by the caller. The mutex
1768 ** associated with the specific b-tree being checkpointed is taken by
1769 ** this function while the checkpoint is running.
1771 ** If iDb is passed SQLITE_MAX_ATTACHED, then all attached databases are
1772 ** checkpointed. If an error is encountered it is returned immediately -
1773 ** no attempt is made to checkpoint any remaining databases.
1775 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
1777 int sqlite3Checkpoint(sqlite3
*db
, int iDb
, int eMode
, int *pnLog
, int *pnCkpt
){
1778 int rc
= SQLITE_OK
; /* Return code */
1779 int i
; /* Used to iterate through attached dbs */
1780 int bBusy
= 0; /* True if SQLITE_BUSY has been encountered */
1782 assert( sqlite3_mutex_held(db
->mutex
) );
1783 assert( !pnLog
|| *pnLog
==-1 );
1784 assert( !pnCkpt
|| *pnCkpt
==-1 );
1786 for(i
=0; i
<db
->nDb
&& rc
==SQLITE_OK
; i
++){
1787 if( i
==iDb
|| iDb
==SQLITE_MAX_ATTACHED
){
1788 rc
= sqlite3BtreeCheckpoint(db
->aDb
[i
].pBt
, eMode
, pnLog
, pnCkpt
);
1791 if( rc
==SQLITE_BUSY
){
1798 return (rc
==SQLITE_OK
&& bBusy
) ? SQLITE_BUSY
: rc
;
1800 #endif /* SQLITE_OMIT_WAL */
1803 ** This function returns true if main-memory should be used instead of
1804 ** a temporary file for transient pager files and statement journals.
1805 ** The value returned depends on the value of db->temp_store (runtime
1806 ** parameter) and the compile time value of SQLITE_TEMP_STORE. The
1807 ** following table describes the relationship between these two values
1808 ** and this functions return value.
1810 ** SQLITE_TEMP_STORE db->temp_store Location of temporary database
1811 ** ----------------- -------------- ------------------------------
1812 ** 0 any file (return 0)
1813 ** 1 1 file (return 0)
1814 ** 1 2 memory (return 1)
1815 ** 1 0 file (return 0)
1816 ** 2 1 file (return 0)
1817 ** 2 2 memory (return 1)
1818 ** 2 0 memory (return 1)
1819 ** 3 any memory (return 1)
1821 int sqlite3TempInMemory(const sqlite3
*db
){
1822 #if SQLITE_TEMP_STORE==1
1823 return ( db
->temp_store
==2 );
1825 #if SQLITE_TEMP_STORE==2
1826 return ( db
->temp_store
!=1 );
1828 #if SQLITE_TEMP_STORE==3
1831 #if SQLITE_TEMP_STORE<1 || SQLITE_TEMP_STORE>3
1837 ** Return UTF-8 encoded English language explanation of the most recent
1840 const char *sqlite3_errmsg(sqlite3
*db
){
1843 return sqlite3ErrStr(SQLITE_NOMEM
);
1845 if( !sqlite3SafetyCheckSickOrOk(db
) ){
1846 return sqlite3ErrStr(SQLITE_MISUSE_BKPT
);
1848 sqlite3_mutex_enter(db
->mutex
);
1849 if( db
->mallocFailed
){
1850 z
= sqlite3ErrStr(SQLITE_NOMEM
);
1852 z
= (char*)sqlite3_value_text(db
->pErr
);
1853 assert( !db
->mallocFailed
);
1855 z
= sqlite3ErrStr(db
->errCode
);
1858 sqlite3_mutex_leave(db
->mutex
);
1862 #ifndef SQLITE_OMIT_UTF16
1864 ** Return UTF-16 encoded English language explanation of the most recent
1867 const void *sqlite3_errmsg16(sqlite3
*db
){
1868 static const u16 outOfMem
[] = {
1869 'o', 'u', 't', ' ', 'o', 'f', ' ', 'm', 'e', 'm', 'o', 'r', 'y', 0
1871 static const u16 misuse
[] = {
1872 'l', 'i', 'b', 'r', 'a', 'r', 'y', ' ',
1873 'r', 'o', 'u', 't', 'i', 'n', 'e', ' ',
1874 'c', 'a', 'l', 'l', 'e', 'd', ' ',
1877 's', 'e', 'q', 'u', 'e', 'n', 'c', 'e', 0
1882 return (void *)outOfMem
;
1884 if( !sqlite3SafetyCheckSickOrOk(db
) ){
1885 return (void *)misuse
;
1887 sqlite3_mutex_enter(db
->mutex
);
1888 if( db
->mallocFailed
){
1889 z
= (void *)outOfMem
;
1891 z
= sqlite3_value_text16(db
->pErr
);
1893 sqlite3ValueSetStr(db
->pErr
, -1, sqlite3ErrStr(db
->errCode
),
1894 SQLITE_UTF8
, SQLITE_STATIC
);
1895 z
= sqlite3_value_text16(db
->pErr
);
1897 /* A malloc() may have failed within the call to sqlite3_value_text16()
1898 ** above. If this is the case, then the db->mallocFailed flag needs to
1899 ** be cleared before returning. Do this directly, instead of via
1900 ** sqlite3ApiExit(), to avoid setting the database handle error message.
1902 db
->mallocFailed
= 0;
1904 sqlite3_mutex_leave(db
->mutex
);
1907 #endif /* SQLITE_OMIT_UTF16 */
1910 ** Return the most recent error code generated by an SQLite routine. If NULL is
1911 ** passed to this function, we assume a malloc() failed during sqlite3_open().
1913 int sqlite3_errcode(sqlite3
*db
){
1914 if( db
&& !sqlite3SafetyCheckSickOrOk(db
) ){
1915 return SQLITE_MISUSE_BKPT
;
1917 if( !db
|| db
->mallocFailed
){
1918 return SQLITE_NOMEM
;
1920 return db
->errCode
& db
->errMask
;
1922 int sqlite3_extended_errcode(sqlite3
*db
){
1923 if( db
&& !sqlite3SafetyCheckSickOrOk(db
) ){
1924 return SQLITE_MISUSE_BKPT
;
1926 if( !db
|| db
->mallocFailed
){
1927 return SQLITE_NOMEM
;
1933 ** Return a string that describes the kind of error specified in the
1934 ** argument. For now, this simply calls the internal sqlite3ErrStr()
1937 const char *sqlite3_errstr(int rc
){
1938 return sqlite3ErrStr(rc
);
1942 ** Create a new collating function for database "db". The name is zName
1943 ** and the encoding is enc.
1945 static int createCollation(
1950 int(*xCompare
)(void*,int,const void*,int,const void*),
1955 int nName
= sqlite3Strlen30(zName
);
1957 assert( sqlite3_mutex_held(db
->mutex
) );
1959 /* If SQLITE_UTF16 is specified as the encoding type, transform this
1960 ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
1961 ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
1964 testcase( enc2
==SQLITE_UTF16
);
1965 testcase( enc2
==SQLITE_UTF16_ALIGNED
);
1966 if( enc2
==SQLITE_UTF16
|| enc2
==SQLITE_UTF16_ALIGNED
){
1967 enc2
= SQLITE_UTF16NATIVE
;
1969 if( enc2
<SQLITE_UTF8
|| enc2
>SQLITE_UTF16BE
){
1970 return SQLITE_MISUSE_BKPT
;
1973 /* Check if this call is removing or replacing an existing collation
1974 ** sequence. If so, and there are active VMs, return busy. If there
1975 ** are no active VMs, invalidate any pre-compiled statements.
1977 pColl
= sqlite3FindCollSeq(db
, (u8
)enc2
, zName
, 0);
1978 if( pColl
&& pColl
->xCmp
){
1979 if( db
->activeVdbeCnt
){
1980 sqlite3Error(db
, SQLITE_BUSY
,
1981 "unable to delete/modify collation sequence due to active statements");
1984 sqlite3ExpirePreparedStatements(db
);
1986 /* If collation sequence pColl was created directly by a call to
1987 ** sqlite3_create_collation, and not generated by synthCollSeq(),
1988 ** then any copies made by synthCollSeq() need to be invalidated.
1989 ** Also, collation destructor - CollSeq.xDel() - function may need
1992 if( (pColl
->enc
& ~SQLITE_UTF16_ALIGNED
)==enc2
){
1993 CollSeq
*aColl
= sqlite3HashFind(&db
->aCollSeq
, zName
, nName
);
1996 CollSeq
*p
= &aColl
[j
];
1997 if( p
->enc
==pColl
->enc
){
2007 pColl
= sqlite3FindCollSeq(db
, (u8
)enc2
, zName
, 1);
2008 if( pColl
==0 ) return SQLITE_NOMEM
;
2009 pColl
->xCmp
= xCompare
;
2010 pColl
->pUser
= pCtx
;
2012 pColl
->enc
= (u8
)(enc2
| (enc
& SQLITE_UTF16_ALIGNED
));
2013 sqlite3Error(db
, SQLITE_OK
, 0);
2019 ** This array defines hard upper bounds on limit values. The
2020 ** initializer must be kept in sync with the SQLITE_LIMIT_*
2021 ** #defines in sqlite3.h.
2023 static const int aHardLimit
[] = {
2025 SQLITE_MAX_SQL_LENGTH
,
2027 SQLITE_MAX_EXPR_DEPTH
,
2028 SQLITE_MAX_COMPOUND_SELECT
,
2030 SQLITE_MAX_FUNCTION_ARG
,
2031 SQLITE_MAX_ATTACHED
,
2032 SQLITE_MAX_LIKE_PATTERN_LENGTH
,
2033 SQLITE_MAX_VARIABLE_NUMBER
,
2034 SQLITE_MAX_TRIGGER_DEPTH
,
2038 ** Make sure the hard limits are set to reasonable values
2040 #if SQLITE_MAX_LENGTH<100
2041 # error SQLITE_MAX_LENGTH must be at least 100
2043 #if SQLITE_MAX_SQL_LENGTH<100
2044 # error SQLITE_MAX_SQL_LENGTH must be at least 100
2046 #if SQLITE_MAX_SQL_LENGTH>SQLITE_MAX_LENGTH
2047 # error SQLITE_MAX_SQL_LENGTH must not be greater than SQLITE_MAX_LENGTH
2049 #if SQLITE_MAX_COMPOUND_SELECT<2
2050 # error SQLITE_MAX_COMPOUND_SELECT must be at least 2
2052 #if SQLITE_MAX_VDBE_OP<40
2053 # error SQLITE_MAX_VDBE_OP must be at least 40
2055 #if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>1000
2056 # error SQLITE_MAX_FUNCTION_ARG must be between 0 and 1000
2058 #if SQLITE_MAX_ATTACHED<0 || SQLITE_MAX_ATTACHED>62
2059 # error SQLITE_MAX_ATTACHED must be between 0 and 62
2061 #if SQLITE_MAX_LIKE_PATTERN_LENGTH<1
2062 # error SQLITE_MAX_LIKE_PATTERN_LENGTH must be at least 1
2064 #if SQLITE_MAX_COLUMN>32767
2065 # error SQLITE_MAX_COLUMN must not exceed 32767
2067 #if SQLITE_MAX_TRIGGER_DEPTH<1
2068 # error SQLITE_MAX_TRIGGER_DEPTH must be at least 1
2073 ** Change the value of a limit. Report the old value.
2074 ** If an invalid limit index is supplied, report -1.
2075 ** Make no changes but still report the old value if the
2076 ** new limit is negative.
2078 ** A new lower limit does not shrink existing constructs.
2079 ** It merely prevents new constructs that exceed the limit
2082 int sqlite3_limit(sqlite3
*db
, int limitId
, int newLimit
){
2086 /* EVIDENCE-OF: R-30189-54097 For each limit category SQLITE_LIMIT_NAME
2087 ** there is a hard upper bound set at compile-time by a C preprocessor
2088 ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
2091 assert( aHardLimit
[SQLITE_LIMIT_LENGTH
]==SQLITE_MAX_LENGTH
);
2092 assert( aHardLimit
[SQLITE_LIMIT_SQL_LENGTH
]==SQLITE_MAX_SQL_LENGTH
);
2093 assert( aHardLimit
[SQLITE_LIMIT_COLUMN
]==SQLITE_MAX_COLUMN
);
2094 assert( aHardLimit
[SQLITE_LIMIT_EXPR_DEPTH
]==SQLITE_MAX_EXPR_DEPTH
);
2095 assert( aHardLimit
[SQLITE_LIMIT_COMPOUND_SELECT
]==SQLITE_MAX_COMPOUND_SELECT
);
2096 assert( aHardLimit
[SQLITE_LIMIT_VDBE_OP
]==SQLITE_MAX_VDBE_OP
);
2097 assert( aHardLimit
[SQLITE_LIMIT_FUNCTION_ARG
]==SQLITE_MAX_FUNCTION_ARG
);
2098 assert( aHardLimit
[SQLITE_LIMIT_ATTACHED
]==SQLITE_MAX_ATTACHED
);
2099 assert( aHardLimit
[SQLITE_LIMIT_LIKE_PATTERN_LENGTH
]==
2100 SQLITE_MAX_LIKE_PATTERN_LENGTH
);
2101 assert( aHardLimit
[SQLITE_LIMIT_VARIABLE_NUMBER
]==SQLITE_MAX_VARIABLE_NUMBER
);
2102 assert( aHardLimit
[SQLITE_LIMIT_TRIGGER_DEPTH
]==SQLITE_MAX_TRIGGER_DEPTH
);
2103 assert( SQLITE_LIMIT_TRIGGER_DEPTH
==(SQLITE_N_LIMIT
-1) );
2106 if( limitId
<0 || limitId
>=SQLITE_N_LIMIT
){
2109 oldLimit
= db
->aLimit
[limitId
];
2110 if( newLimit
>=0 ){ /* IMP: R-52476-28732 */
2111 if( newLimit
>aHardLimit
[limitId
] ){
2112 newLimit
= aHardLimit
[limitId
]; /* IMP: R-51463-25634 */
2114 db
->aLimit
[limitId
] = newLimit
;
2116 return oldLimit
; /* IMP: R-53341-35419 */
2120 ** This function is used to parse both URIs and non-URI filenames passed by the
2121 ** user to API functions sqlite3_open() or sqlite3_open_v2(), and for database
2122 ** URIs specified as part of ATTACH statements.
2124 ** The first argument to this function is the name of the VFS to use (or
2125 ** a NULL to signify the default VFS) if the URI does not contain a "vfs=xxx"
2126 ** query parameter. The second argument contains the URI (or non-URI filename)
2127 ** itself. When this function is called the *pFlags variable should contain
2128 ** the default flags to open the database handle with. The value stored in
2129 ** *pFlags may be updated before returning if the URI filename contains
2130 ** "cache=xxx" or "mode=xxx" query parameters.
2132 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
2133 ** the VFS that should be used to open the database file. *pzFile is set to
2134 ** point to a buffer containing the name of the file to open. It is the
2135 ** responsibility of the caller to eventually call sqlite3_free() to release
2138 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
2139 ** may be set to point to a buffer containing an English language error
2140 ** message. It is the responsibility of the caller to eventually release
2141 ** this buffer by calling sqlite3_free().
2143 int sqlite3ParseUri(
2144 const char *zDefaultVfs
, /* VFS to use if no "vfs=xxx" query option */
2145 const char *zUri
, /* Nul-terminated URI to parse */
2146 unsigned int *pFlags
, /* IN/OUT: SQLITE_OPEN_XXX flags */
2147 sqlite3_vfs
**ppVfs
, /* OUT: VFS to use */
2148 char **pzFile
, /* OUT: Filename component of URI */
2149 char **pzErrMsg
/* OUT: Error message (if rc!=SQLITE_OK) */
2152 unsigned int flags
= *pFlags
;
2153 const char *zVfs
= zDefaultVfs
;
2156 int nUri
= sqlite3Strlen30(zUri
);
2158 assert( *pzErrMsg
==0 );
2160 if( ((flags
& SQLITE_OPEN_URI
) || sqlite3GlobalConfig
.bOpenUri
)
2161 && nUri
>=5 && memcmp(zUri
, "file:", 5)==0
2164 int eState
; /* Parser state when parsing URI */
2165 int iIn
; /* Input character index */
2166 int iOut
= 0; /* Output character index */
2167 int nByte
= nUri
+2; /* Bytes of space to allocate */
2169 /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen
2170 ** method that there may be extra parameters following the file-name. */
2171 flags
|= SQLITE_OPEN_URI
;
2173 for(iIn
=0; iIn
<nUri
; iIn
++) nByte
+= (zUri
[iIn
]=='&');
2174 zFile
= sqlite3_malloc(nByte
);
2175 if( !zFile
) return SQLITE_NOMEM
;
2177 /* Discard the scheme and authority segments of the URI. */
2178 if( zUri
[5]=='/' && zUri
[6]=='/' ){
2180 while( zUri
[iIn
] && zUri
[iIn
]!='/' ) iIn
++;
2182 if( iIn
!=7 && (iIn
!=16 || memcmp("localhost", &zUri
[7], 9)) ){
2183 *pzErrMsg
= sqlite3_mprintf("invalid uri authority: %.*s",
2192 /* Copy the filename and any query parameters into the zFile buffer.
2193 ** Decode %HH escape codes along the way.
2195 ** Within this loop, variable eState may be set to 0, 1 or 2, depending
2196 ** on the parsing context. As follows:
2198 ** 0: Parsing file-name.
2199 ** 1: Parsing name section of a name=value query parameter.
2200 ** 2: Parsing value section of a name=value query parameter.
2203 while( (c
= zUri
[iIn
])!=0 && c
!='#' ){
2206 && sqlite3Isxdigit(zUri
[iIn
])
2207 && sqlite3Isxdigit(zUri
[iIn
+1])
2209 int octet
= (sqlite3HexToInt(zUri
[iIn
++]) << 4);
2210 octet
+= sqlite3HexToInt(zUri
[iIn
++]);
2212 assert( octet
>=0 && octet
<256 );
2214 /* This branch is taken when "%00" appears within the URI. In this
2215 ** case we ignore all text in the remainder of the path, name or
2216 ** value currently being parsed. So ignore the current character
2217 ** and skip to the next "?", "=" or "&", as appropriate. */
2218 while( (c
= zUri
[iIn
])!=0 && c
!='#'
2219 && (eState
!=0 || c
!='?')
2220 && (eState
!=1 || (c
!='=' && c
!='&'))
2221 && (eState
!=2 || c
!='&')
2228 }else if( eState
==1 && (c
=='&' || c
=='=') ){
2229 if( zFile
[iOut
-1]==0 ){
2230 /* An empty option name. Ignore this option altogether. */
2231 while( zUri
[iIn
] && zUri
[iIn
]!='#' && zUri
[iIn
-1]!='&' ) iIn
++;
2235 zFile
[iOut
++] = '\0';
2240 }else if( (eState
==0 && c
=='?') || (eState
==2 && c
=='&') ){
2246 if( eState
==1 ) zFile
[iOut
++] = '\0';
2247 zFile
[iOut
++] = '\0';
2248 zFile
[iOut
++] = '\0';
2250 /* Check if there were any options specified that should be interpreted
2251 ** here. Options that are interpreted here include "vfs" and those that
2252 ** correspond to flags that may be passed to the sqlite3_open_v2()
2254 zOpt
= &zFile
[sqlite3Strlen30(zFile
)+1];
2256 int nOpt
= sqlite3Strlen30(zOpt
);
2257 char *zVal
= &zOpt
[nOpt
+1];
2258 int nVal
= sqlite3Strlen30(zVal
);
2260 if( nOpt
==3 && memcmp("vfs", zOpt
, 3)==0 ){
2267 char *zModeType
= 0;
2271 if( nOpt
==5 && memcmp("cache", zOpt
, 5)==0 ){
2272 static struct OpenMode aCacheMode
[] = {
2273 { "shared", SQLITE_OPEN_SHAREDCACHE
},
2274 { "private", SQLITE_OPEN_PRIVATECACHE
},
2278 mask
= SQLITE_OPEN_SHAREDCACHE
|SQLITE_OPEN_PRIVATECACHE
;
2281 zModeType
= "cache";
2283 if( nOpt
==4 && memcmp("mode", zOpt
, 4)==0 ){
2284 static struct OpenMode aOpenMode
[] = {
2285 { "ro", SQLITE_OPEN_READONLY
},
2286 { "rw", SQLITE_OPEN_READWRITE
},
2287 { "rwc", SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
},
2288 { "memory", SQLITE_OPEN_MEMORY
},
2292 mask
= SQLITE_OPEN_READONLY
| SQLITE_OPEN_READWRITE
2293 | SQLITE_OPEN_CREATE
| SQLITE_OPEN_MEMORY
;
2295 limit
= mask
& flags
;
2296 zModeType
= "access";
2302 for(i
=0; aMode
[i
].z
; i
++){
2303 const char *z
= aMode
[i
].z
;
2304 if( nVal
==sqlite3Strlen30(z
) && 0==memcmp(zVal
, z
, nVal
) ){
2305 mode
= aMode
[i
].mode
;
2310 *pzErrMsg
= sqlite3_mprintf("no such %s mode: %s", zModeType
, zVal
);
2314 if( (mode
& ~SQLITE_OPEN_MEMORY
)>limit
){
2315 *pzErrMsg
= sqlite3_mprintf("%s mode not allowed: %s",
2320 flags
= (flags
& ~mask
) | mode
;
2324 zOpt
= &zVal
[nVal
+1];
2328 zFile
= sqlite3_malloc(nUri
+2);
2329 if( !zFile
) return SQLITE_NOMEM
;
2330 memcpy(zFile
, zUri
, nUri
);
2332 zFile
[nUri
+1] = '\0';
2333 flags
&= ~SQLITE_OPEN_URI
;
2336 *ppVfs
= sqlite3_vfs_find(zVfs
);
2338 *pzErrMsg
= sqlite3_mprintf("no such vfs: %s", zVfs
);
2342 if( rc
!=SQLITE_OK
){
2343 sqlite3_free(zFile
);
2353 ** This routine does the work of opening a database on behalf of
2354 ** sqlite3_open() and sqlite3_open16(). The database filename "zFilename"
2355 ** is UTF-8 encoded.
2357 static int openDatabase(
2358 const char *zFilename
, /* Database filename UTF-8 encoded */
2359 sqlite3
**ppDb
, /* OUT: Returned database handle */
2360 unsigned int flags
, /* Operational flags */
2361 const char *zVfs
/* Name of the VFS to use */
2363 sqlite3
*db
; /* Store allocated handle here */
2364 int rc
; /* Return code */
2365 int isThreadsafe
; /* True for threadsafe connections */
2366 char *zOpen
= 0; /* Filename argument to pass to BtreeOpen() */
2367 char *zErrMsg
= 0; /* Error message from sqlite3ParseUri() */
2370 #ifndef SQLITE_OMIT_AUTOINIT
2371 rc
= sqlite3_initialize();
2375 /* Only allow sensible combinations of bits in the flags argument.
2376 ** Throw an error if any non-sense combination is used. If we
2377 ** do not block illegal combinations here, it could trigger
2378 ** assert() statements in deeper layers. Sensible combinations
2381 ** 1: SQLITE_OPEN_READONLY
2382 ** 2: SQLITE_OPEN_READWRITE
2383 ** 6: SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
2385 assert( SQLITE_OPEN_READONLY
== 0x01 );
2386 assert( SQLITE_OPEN_READWRITE
== 0x02 );
2387 assert( SQLITE_OPEN_CREATE
== 0x04 );
2388 testcase( (1<<(flags
&7))==0x02 ); /* READONLY */
2389 testcase( (1<<(flags
&7))==0x04 ); /* READWRITE */
2390 testcase( (1<<(flags
&7))==0x40 ); /* READWRITE | CREATE */
2391 if( ((1<<(flags
&7)) & 0x46)==0 ) return SQLITE_MISUSE_BKPT
;
2393 if( sqlite3GlobalConfig
.bCoreMutex
==0 ){
2395 }else if( flags
& SQLITE_OPEN_NOMUTEX
){
2397 }else if( flags
& SQLITE_OPEN_FULLMUTEX
){
2400 isThreadsafe
= sqlite3GlobalConfig
.bFullMutex
;
2402 if( flags
& SQLITE_OPEN_PRIVATECACHE
){
2403 flags
&= ~SQLITE_OPEN_SHAREDCACHE
;
2404 }else if( sqlite3GlobalConfig
.sharedCacheEnabled
){
2405 flags
|= SQLITE_OPEN_SHAREDCACHE
;
2408 /* Remove harmful bits from the flags parameter
2410 ** The SQLITE_OPEN_NOMUTEX and SQLITE_OPEN_FULLMUTEX flags were
2411 ** dealt with in the previous code block. Besides these, the only
2412 ** valid input flags for sqlite3_open_v2() are SQLITE_OPEN_READONLY,
2413 ** SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_SHAREDCACHE,
2414 ** SQLITE_OPEN_PRIVATECACHE, and some reserved bits. Silently mask
2415 ** off all other flags.
2417 flags
&= ~( SQLITE_OPEN_DELETEONCLOSE
|
2418 SQLITE_OPEN_EXCLUSIVE
|
2419 SQLITE_OPEN_MAIN_DB
|
2420 SQLITE_OPEN_TEMP_DB
|
2421 SQLITE_OPEN_TRANSIENT_DB
|
2422 SQLITE_OPEN_MAIN_JOURNAL
|
2423 SQLITE_OPEN_TEMP_JOURNAL
|
2424 SQLITE_OPEN_SUBJOURNAL
|
2425 SQLITE_OPEN_MASTER_JOURNAL
|
2426 SQLITE_OPEN_NOMUTEX
|
2427 SQLITE_OPEN_FULLMUTEX
|
2431 /* Allocate the sqlite data structure */
2432 db
= sqlite3MallocZero( sizeof(sqlite3
) );
2433 if( db
==0 ) goto opendb_out
;
2435 db
->mutex
= sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE
);
2442 sqlite3_mutex_enter(db
->mutex
);
2445 db
->magic
= SQLITE_MAGIC_BUSY
;
2446 db
->aDb
= db
->aDbStatic
;
2448 assert( sizeof(db
->aLimit
)==sizeof(aHardLimit
) );
2449 memcpy(db
->aLimit
, aHardLimit
, sizeof(db
->aLimit
));
2451 db
->nextAutovac
= -1;
2452 db
->szMmap
= sqlite3GlobalConfig
.szMmap
;
2453 db
->nextPagesize
= 0;
2454 db
->flags
|= SQLITE_ShortColNames
| SQLITE_AutoIndex
| SQLITE_EnableTrigger
2455 #if SQLITE_DEFAULT_FILE_FORMAT<4
2456 | SQLITE_LegacyFileFmt
2458 #ifdef SQLITE_ENABLE_LOAD_EXTENSION
2459 | SQLITE_LoadExtension
2461 #if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
2462 | SQLITE_RecTriggers
2464 #if defined(SQLITE_DEFAULT_FOREIGN_KEYS) && SQLITE_DEFAULT_FOREIGN_KEYS
2465 | SQLITE_ForeignKeys
2468 sqlite3HashInit(&db
->aCollSeq
);
2469 #ifndef SQLITE_OMIT_VIRTUALTABLE
2470 sqlite3HashInit(&db
->aModule
);
2473 /* Add the default collation sequence BINARY. BINARY works for both UTF-8
2474 ** and UTF-16, so add a version for each to avoid any unnecessary
2475 ** conversions. The only error that can occur here is a malloc() failure.
2477 createCollation(db
, "BINARY", SQLITE_UTF8
, 0, binCollFunc
, 0);
2478 createCollation(db
, "BINARY", SQLITE_UTF16BE
, 0, binCollFunc
, 0);
2479 createCollation(db
, "BINARY", SQLITE_UTF16LE
, 0, binCollFunc
, 0);
2480 createCollation(db
, "RTRIM", SQLITE_UTF8
, (void*)1, binCollFunc
, 0);
2481 if( db
->mallocFailed
){
2484 db
->pDfltColl
= sqlite3FindCollSeq(db
, SQLITE_UTF8
, "BINARY", 0);
2485 assert( db
->pDfltColl
!=0 );
2487 /* Also add a UTF-8 case-insensitive collation sequence. */
2488 createCollation(db
, "NOCASE", SQLITE_UTF8
, 0, nocaseCollatingFunc
, 0);
2490 /* Parse the filename/URI argument. */
2491 db
->openFlags
= flags
;
2492 rc
= sqlite3ParseUri(zVfs
, zFilename
, &flags
, &db
->pVfs
, &zOpen
, &zErrMsg
);
2493 if( rc
!=SQLITE_OK
){
2494 if( rc
==SQLITE_NOMEM
) db
->mallocFailed
= 1;
2495 sqlite3Error(db
, rc
, zErrMsg
? "%s" : 0, zErrMsg
);
2496 sqlite3_free(zErrMsg
);
2500 /* Open the backend database driver */
2501 rc
= sqlite3BtreeOpen(db
->pVfs
, zOpen
, db
, &db
->aDb
[0].pBt
, 0,
2502 flags
| SQLITE_OPEN_MAIN_DB
);
2503 if( rc
!=SQLITE_OK
){
2504 if( rc
==SQLITE_IOERR_NOMEM
){
2507 sqlite3Error(db
, rc
, 0);
2510 db
->aDb
[0].pSchema
= sqlite3SchemaGet(db
, db
->aDb
[0].pBt
);
2511 db
->aDb
[1].pSchema
= sqlite3SchemaGet(db
, 0);
2514 /* The default safety_level for the main database is 'full'; for the temp
2515 ** database it is 'NONE'. This matches the pager layer defaults.
2517 db
->aDb
[0].zName
= "main";
2518 db
->aDb
[0].safety_level
= 3;
2519 db
->aDb
[1].zName
= "temp";
2520 db
->aDb
[1].safety_level
= 1;
2522 db
->magic
= SQLITE_MAGIC_OPEN
;
2523 if( db
->mallocFailed
){
2527 /* Register all built-in functions, but do not attempt to read the
2528 ** database schema yet. This is delayed until the first time the database
2531 sqlite3Error(db
, SQLITE_OK
, 0);
2532 sqlite3RegisterBuiltinFunctions(db
);
2534 /* Load automatic extensions - extensions that have been registered
2535 ** using the sqlite3_automatic_extension() API.
2537 rc
= sqlite3_errcode(db
);
2538 if( rc
==SQLITE_OK
){
2539 sqlite3AutoLoadExtensions(db
);
2540 rc
= sqlite3_errcode(db
);
2541 if( rc
!=SQLITE_OK
){
2546 #ifdef SQLITE_ENABLE_FTS1
2547 if( !db
->mallocFailed
){
2548 extern int sqlite3Fts1Init(sqlite3
*);
2549 rc
= sqlite3Fts1Init(db
);
2553 #ifdef SQLITE_ENABLE_FTS2
2554 if( !db
->mallocFailed
&& rc
==SQLITE_OK
){
2555 extern int sqlite3Fts2Init(sqlite3
*);
2556 rc
= sqlite3Fts2Init(db
);
2560 #ifdef SQLITE_ENABLE_FTS3
2561 if( !db
->mallocFailed
&& rc
==SQLITE_OK
){
2562 rc
= sqlite3Fts3Init(db
);
2566 #ifdef SQLITE_ENABLE_ICU
2567 if( !db
->mallocFailed
&& rc
==SQLITE_OK
){
2568 rc
= sqlite3IcuInit(db
);
2572 #ifdef SQLITE_ENABLE_RTREE
2573 if( !db
->mallocFailed
&& rc
==SQLITE_OK
){
2574 rc
= sqlite3RtreeInit(db
);
2578 sqlite3Error(db
, rc
, 0);
2580 /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking
2581 ** mode. -DSQLITE_DEFAULT_LOCKING_MODE=0 make NORMAL the default locking
2582 ** mode. Doing nothing at all also makes NORMAL the default.
2584 #ifdef SQLITE_DEFAULT_LOCKING_MODE
2585 db
->dfltLockMode
= SQLITE_DEFAULT_LOCKING_MODE
;
2586 sqlite3PagerLockingMode(sqlite3BtreePager(db
->aDb
[0].pBt
),
2587 SQLITE_DEFAULT_LOCKING_MODE
);
2590 /* Enable the lookaside-malloc subsystem */
2591 setupLookaside(db
, 0, sqlite3GlobalConfig
.szLookaside
,
2592 sqlite3GlobalConfig
.nLookaside
);
2594 sqlite3_wal_autocheckpoint(db
, SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
);
2597 sqlite3_free(zOpen
);
2599 assert( db
->mutex
!=0 || isThreadsafe
==0 || sqlite3GlobalConfig
.bFullMutex
==0 );
2600 sqlite3_mutex_leave(db
->mutex
);
2602 rc
= sqlite3_errcode(db
);
2603 assert( db
!=0 || rc
==SQLITE_NOMEM
);
2604 if( rc
==SQLITE_NOMEM
){
2607 }else if( rc
!=SQLITE_OK
){
2608 db
->magic
= SQLITE_MAGIC_SICK
;
2611 #ifdef SQLITE_ENABLE_SQLLOG
2612 if( sqlite3GlobalConfig
.xSqllog
){
2613 /* Opening a db handle. Fourth parameter is passed 0. */
2614 void *pArg
= sqlite3GlobalConfig
.pSqllogArg
;
2615 sqlite3GlobalConfig
.xSqllog(pArg
, db
, zFilename
, 0);
2618 return sqlite3ApiExit(0, rc
);
2622 ** Open a new database handle.
2625 const char *zFilename
,
2628 return openDatabase(zFilename
, ppDb
,
2629 SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
, 0);
2631 int sqlite3_open_v2(
2632 const char *filename
, /* Database filename (UTF-8) */
2633 sqlite3
**ppDb
, /* OUT: SQLite db handle */
2634 int flags
, /* Flags */
2635 const char *zVfs
/* Name of VFS module to use */
2637 return openDatabase(filename
, ppDb
, (unsigned int)flags
, zVfs
);
2640 #ifndef SQLITE_OMIT_UTF16
2642 ** Open a new database handle.
2645 const void *zFilename
,
2648 char const *zFilename8
; /* zFilename encoded in UTF-8 instead of UTF-16 */
2649 sqlite3_value
*pVal
;
2652 assert( zFilename
);
2655 #ifndef SQLITE_OMIT_AUTOINIT
2656 rc
= sqlite3_initialize();
2659 pVal
= sqlite3ValueNew(0);
2660 sqlite3ValueSetStr(pVal
, -1, zFilename
, SQLITE_UTF16NATIVE
, SQLITE_STATIC
);
2661 zFilename8
= sqlite3ValueText(pVal
, SQLITE_UTF8
);
2663 rc
= openDatabase(zFilename8
, ppDb
,
2664 SQLITE_OPEN_READWRITE
| SQLITE_OPEN_CREATE
, 0);
2665 assert( *ppDb
|| rc
==SQLITE_NOMEM
);
2666 if( rc
==SQLITE_OK
&& !DbHasProperty(*ppDb
, 0, DB_SchemaLoaded
) ){
2667 ENC(*ppDb
) = SQLITE_UTF16NATIVE
;
2672 sqlite3ValueFree(pVal
);
2674 return sqlite3ApiExit(0, rc
);
2676 #endif /* SQLITE_OMIT_UTF16 */
2679 ** Register a new collation sequence with the database handle db.
2681 int sqlite3_create_collation(
2686 int(*xCompare
)(void*,int,const void*,int,const void*)
2689 sqlite3_mutex_enter(db
->mutex
);
2690 assert( !db
->mallocFailed
);
2691 rc
= createCollation(db
, zName
, (u8
)enc
, pCtx
, xCompare
, 0);
2692 rc
= sqlite3ApiExit(db
, rc
);
2693 sqlite3_mutex_leave(db
->mutex
);
2698 ** Register a new collation sequence with the database handle db.
2700 int sqlite3_create_collation_v2(
2705 int(*xCompare
)(void*,int,const void*,int,const void*),
2709 sqlite3_mutex_enter(db
->mutex
);
2710 assert( !db
->mallocFailed
);
2711 rc
= createCollation(db
, zName
, (u8
)enc
, pCtx
, xCompare
, xDel
);
2712 rc
= sqlite3ApiExit(db
, rc
);
2713 sqlite3_mutex_leave(db
->mutex
);
2717 #ifndef SQLITE_OMIT_UTF16
2719 ** Register a new collation sequence with the database handle db.
2721 int sqlite3_create_collation16(
2726 int(*xCompare
)(void*,int,const void*,int,const void*)
2730 sqlite3_mutex_enter(db
->mutex
);
2731 assert( !db
->mallocFailed
);
2732 zName8
= sqlite3Utf16to8(db
, zName
, -1, SQLITE_UTF16NATIVE
);
2734 rc
= createCollation(db
, zName8
, (u8
)enc
, pCtx
, xCompare
, 0);
2735 sqlite3DbFree(db
, zName8
);
2737 rc
= sqlite3ApiExit(db
, rc
);
2738 sqlite3_mutex_leave(db
->mutex
);
2741 #endif /* SQLITE_OMIT_UTF16 */
2744 ** Register a collation sequence factory callback with the database handle
2745 ** db. Replace any previously installed collation sequence factory.
2747 int sqlite3_collation_needed(
2749 void *pCollNeededArg
,
2750 void(*xCollNeeded
)(void*,sqlite3
*,int eTextRep
,const char*)
2752 sqlite3_mutex_enter(db
->mutex
);
2753 db
->xCollNeeded
= xCollNeeded
;
2754 db
->xCollNeeded16
= 0;
2755 db
->pCollNeededArg
= pCollNeededArg
;
2756 sqlite3_mutex_leave(db
->mutex
);
2760 #ifndef SQLITE_OMIT_UTF16
2762 ** Register a collation sequence factory callback with the database handle
2763 ** db. Replace any previously installed collation sequence factory.
2765 int sqlite3_collation_needed16(
2767 void *pCollNeededArg
,
2768 void(*xCollNeeded16
)(void*,sqlite3
*,int eTextRep
,const void*)
2770 sqlite3_mutex_enter(db
->mutex
);
2771 db
->xCollNeeded
= 0;
2772 db
->xCollNeeded16
= xCollNeeded16
;
2773 db
->pCollNeededArg
= pCollNeededArg
;
2774 sqlite3_mutex_leave(db
->mutex
);
2777 #endif /* SQLITE_OMIT_UTF16 */
2779 #ifndef SQLITE_OMIT_DEPRECATED
2781 ** This function is now an anachronism. It used to be used to recover from a
2782 ** malloc() failure, but SQLite now does this automatically.
2784 int sqlite3_global_recover(void){
2790 ** Test to see whether or not the database connection is in autocommit
2791 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
2792 ** by default. Autocommit is disabled by a BEGIN statement and reenabled
2793 ** by the next COMMIT or ROLLBACK.
2795 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
2797 int sqlite3_get_autocommit(sqlite3
*db
){
2798 return db
->autoCommit
;
2802 ** The following routines are subtitutes for constants SQLITE_CORRUPT,
2803 ** SQLITE_MISUSE, SQLITE_CANTOPEN, SQLITE_IOERR and possibly other error
2804 ** constants. They server two purposes:
2806 ** 1. Serve as a convenient place to set a breakpoint in a debugger
2807 ** to detect when version error conditions occurs.
2809 ** 2. Invoke sqlite3_log() to provide the source code location where
2810 ** a low-level error is first detected.
2812 int sqlite3CorruptError(int lineno
){
2813 testcase( sqlite3GlobalConfig
.xLog
!=0 );
2814 sqlite3_log(SQLITE_CORRUPT
,
2815 "database corruption at line %d of [%.10s]",
2816 lineno
, 20+sqlite3_sourceid());
2817 return SQLITE_CORRUPT
;
2819 int sqlite3MisuseError(int lineno
){
2820 testcase( sqlite3GlobalConfig
.xLog
!=0 );
2821 sqlite3_log(SQLITE_MISUSE
,
2822 "misuse at line %d of [%.10s]",
2823 lineno
, 20+sqlite3_sourceid());
2824 return SQLITE_MISUSE
;
2826 int sqlite3CantopenError(int lineno
){
2827 testcase( sqlite3GlobalConfig
.xLog
!=0 );
2828 sqlite3_log(SQLITE_CANTOPEN
,
2829 "cannot open file at line %d of [%.10s]",
2830 lineno
, 20+sqlite3_sourceid());
2831 return SQLITE_CANTOPEN
;
2835 #ifndef SQLITE_OMIT_DEPRECATED
2837 ** This is a convenience routine that makes sure that all thread-specific
2838 ** data for this thread has been deallocated.
2840 ** SQLite no longer uses thread-specific data so this routine is now a
2841 ** no-op. It is retained for historical compatibility.
2843 void sqlite3_thread_cleanup(void){
2848 ** Return meta information about a specific column of a database table.
2849 ** See comment in sqlite3.h (sqlite.h.in) for details.
2851 #ifdef SQLITE_ENABLE_COLUMN_METADATA
2852 int sqlite3_table_column_metadata(
2853 sqlite3
*db
, /* Connection handle */
2854 const char *zDbName
, /* Database name or NULL */
2855 const char *zTableName
, /* Table name */
2856 const char *zColumnName
, /* Column name */
2857 char const **pzDataType
, /* OUTPUT: Declared data type */
2858 char const **pzCollSeq
, /* OUTPUT: Collation sequence name */
2859 int *pNotNull
, /* OUTPUT: True if NOT NULL constraint exists */
2860 int *pPrimaryKey
, /* OUTPUT: True if column part of PK */
2861 int *pAutoinc
/* OUTPUT: True if column is auto-increment */
2869 char const *zDataType
= 0;
2870 char const *zCollSeq
= 0;
2875 /* Ensure the database schema has been loaded */
2876 sqlite3_mutex_enter(db
->mutex
);
2877 sqlite3BtreeEnterAll(db
);
2878 rc
= sqlite3Init(db
, &zErrMsg
);
2879 if( SQLITE_OK
!=rc
){
2883 /* Locate the table in question */
2884 pTab
= sqlite3FindTable(db
, zTableName
, zDbName
);
2885 if( !pTab
|| pTab
->pSelect
){
2890 /* Find the column for which info is requested */
2891 if( sqlite3IsRowid(zColumnName
) ){
2894 pCol
= &pTab
->aCol
[iCol
];
2897 for(iCol
=0; iCol
<pTab
->nCol
; iCol
++){
2898 pCol
= &pTab
->aCol
[iCol
];
2899 if( 0==sqlite3StrICmp(pCol
->zName
, zColumnName
) ){
2903 if( iCol
==pTab
->nCol
){
2909 /* The following block stores the meta information that will be returned
2910 ** to the caller in local variables zDataType, zCollSeq, notnull, primarykey
2911 ** and autoinc. At this point there are two possibilities:
2913 ** 1. The specified column name was rowid", "oid" or "_rowid_"
2914 ** and there is no explicitly declared IPK column.
2916 ** 2. The table is not a view and the column name identified an
2917 ** explicitly declared column. Copy meta information from *pCol.
2920 zDataType
= pCol
->zType
;
2921 zCollSeq
= pCol
->zColl
;
2922 notnull
= pCol
->notNull
!=0;
2923 primarykey
= (pCol
->colFlags
& COLFLAG_PRIMKEY
)!=0;
2924 autoinc
= pTab
->iPKey
==iCol
&& (pTab
->tabFlags
& TF_Autoincrement
)!=0;
2926 zDataType
= "INTEGER";
2930 zCollSeq
= "BINARY";
2934 sqlite3BtreeLeaveAll(db
);
2936 /* Whether the function call succeeded or failed, set the output parameters
2937 ** to whatever their local counterparts contain. If an error did occur,
2938 ** this has the effect of zeroing all output parameters.
2940 if( pzDataType
) *pzDataType
= zDataType
;
2941 if( pzCollSeq
) *pzCollSeq
= zCollSeq
;
2942 if( pNotNull
) *pNotNull
= notnull
;
2943 if( pPrimaryKey
) *pPrimaryKey
= primarykey
;
2944 if( pAutoinc
) *pAutoinc
= autoinc
;
2946 if( SQLITE_OK
==rc
&& !pTab
){
2947 sqlite3DbFree(db
, zErrMsg
);
2948 zErrMsg
= sqlite3MPrintf(db
, "no such table column: %s.%s", zTableName
,
2952 sqlite3Error(db
, rc
, (zErrMsg
?"%s":0), zErrMsg
);
2953 sqlite3DbFree(db
, zErrMsg
);
2954 rc
= sqlite3ApiExit(db
, rc
);
2955 sqlite3_mutex_leave(db
->mutex
);
2961 ** Sleep for a little while. Return the amount of time slept.
2963 int sqlite3_sleep(int ms
){
2966 pVfs
= sqlite3_vfs_find(0);
2967 if( pVfs
==0 ) return 0;
2969 /* This function works in milliseconds, but the underlying OsSleep()
2970 ** API uses microseconds. Hence the 1000's.
2972 rc
= (sqlite3OsSleep(pVfs
, 1000*ms
)/1000);
2977 ** Enable or disable the extended result codes.
2979 int sqlite3_extended_result_codes(sqlite3
*db
, int onoff
){
2980 sqlite3_mutex_enter(db
->mutex
);
2981 db
->errMask
= onoff
? 0xffffffff : 0xff;
2982 sqlite3_mutex_leave(db
->mutex
);
2987 ** Invoke the xFileControl method on a particular database.
2989 int sqlite3_file_control(sqlite3
*db
, const char *zDbName
, int op
, void *pArg
){
2990 int rc
= SQLITE_ERROR
;
2993 sqlite3_mutex_enter(db
->mutex
);
2994 pBtree
= sqlite3DbNameToBtree(db
, zDbName
);
2998 sqlite3BtreeEnter(pBtree
);
2999 pPager
= sqlite3BtreePager(pBtree
);
3000 assert( pPager
!=0 );
3001 fd
= sqlite3PagerFile(pPager
);
3003 if( op
==SQLITE_FCNTL_FILE_POINTER
){
3004 *(sqlite3_file
**)pArg
= fd
;
3006 }else if( fd
->pMethods
){
3007 rc
= sqlite3OsFileControl(fd
, op
, pArg
);
3009 rc
= SQLITE_NOTFOUND
;
3011 sqlite3BtreeLeave(pBtree
);
3013 sqlite3_mutex_leave(db
->mutex
);
3018 ** Interface to the testing logic.
3020 int sqlite3_test_control(int op
, ...){
3022 #ifndef SQLITE_OMIT_BUILTIN_TEST
3028 ** Save the current state of the PRNG.
3030 case SQLITE_TESTCTRL_PRNG_SAVE
: {
3031 sqlite3PrngSaveState();
3036 ** Restore the state of the PRNG to the last state saved using
3037 ** PRNG_SAVE. If PRNG_SAVE has never before been called, then
3038 ** this verb acts like PRNG_RESET.
3040 case SQLITE_TESTCTRL_PRNG_RESTORE
: {
3041 sqlite3PrngRestoreState();
3046 ** Reset the PRNG back to its uninitialized state. The next call
3047 ** to sqlite3_randomness() will reseed the PRNG using a single call
3048 ** to the xRandomness method of the default VFS.
3050 case SQLITE_TESTCTRL_PRNG_RESET
: {
3051 sqlite3PrngResetState();
3056 ** sqlite3_test_control(BITVEC_TEST, size, program)
3058 ** Run a test against a Bitvec object of size. The program argument
3059 ** is an array of integers that defines the test. Return -1 on a
3060 ** memory allocation error, 0 on success, or non-zero for an error.
3061 ** See the sqlite3BitvecBuiltinTest() for additional information.
3063 case SQLITE_TESTCTRL_BITVEC_TEST
: {
3064 int sz
= va_arg(ap
, int);
3065 int *aProg
= va_arg(ap
, int*);
3066 rc
= sqlite3BitvecBuiltinTest(sz
, aProg
);
3071 ** sqlite3_test_control(BENIGN_MALLOC_HOOKS, xBegin, xEnd)
3073 ** Register hooks to call to indicate which malloc() failures
3076 case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS
: {
3077 typedef void (*void_function
)(void);
3078 void_function xBenignBegin
;
3079 void_function xBenignEnd
;
3080 xBenignBegin
= va_arg(ap
, void_function
);
3081 xBenignEnd
= va_arg(ap
, void_function
);
3082 sqlite3BenignMallocHooks(xBenignBegin
, xBenignEnd
);
3087 ** sqlite3_test_control(SQLITE_TESTCTRL_PENDING_BYTE, unsigned int X)
3089 ** Set the PENDING byte to the value in the argument, if X>0.
3090 ** Make no changes if X==0. Return the value of the pending byte
3091 ** as it existing before this routine was called.
3093 ** IMPORTANT: Changing the PENDING byte from 0x40000000 results in
3094 ** an incompatible database file format. Changing the PENDING byte
3095 ** while any database connection is open results in undefined and
3096 ** dileterious behavior.
3098 case SQLITE_TESTCTRL_PENDING_BYTE
: {
3100 #ifndef SQLITE_OMIT_WSD
3102 unsigned int newVal
= va_arg(ap
, unsigned int);
3103 if( newVal
) sqlite3PendingByte
= newVal
;
3110 ** sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, int X)
3112 ** This action provides a run-time test to see whether or not
3113 ** assert() was enabled at compile-time. If X is true and assert()
3114 ** is enabled, then the return value is true. If X is true and
3115 ** assert() is disabled, then the return value is zero. If X is
3116 ** false and assert() is enabled, then the assertion fires and the
3117 ** process aborts. If X is false and assert() is disabled, then the
3118 ** return value is zero.
3120 case SQLITE_TESTCTRL_ASSERT
: {
3122 assert( (x
= va_arg(ap
,int))!=0 );
3129 ** sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, int X)
3131 ** This action provides a run-time test to see how the ALWAYS and
3132 ** NEVER macros were defined at compile-time.
3134 ** The return value is ALWAYS(X).
3136 ** The recommended test is X==2. If the return value is 2, that means
3137 ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
3138 ** default setting. If the return value is 1, then ALWAYS() is either
3139 ** hard-coded to true or else it asserts if its argument is false.
3140 ** The first behavior (hard-coded to true) is the case if
3141 ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
3142 ** behavior (assert if the argument to ALWAYS() is false) is the case if
3143 ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
3145 ** The run-time test procedure might look something like this:
3147 ** if( sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, 2)==2 ){
3148 ** // ALWAYS() and NEVER() are no-op pass-through macros
3149 ** }else if( sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, 1) ){
3150 ** // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
3152 ** // ALWAYS(x) is a constant 1. NEVER(x) is a constant 0.
3155 case SQLITE_TESTCTRL_ALWAYS
: {
3156 int x
= va_arg(ap
,int);
3161 /* sqlite3_test_control(SQLITE_TESTCTRL_RESERVE, sqlite3 *db, int N)
3163 ** Set the nReserve size to N for the main database on the database
3166 case SQLITE_TESTCTRL_RESERVE
: {
3167 sqlite3
*db
= va_arg(ap
, sqlite3
*);
3168 int x
= va_arg(ap
,int);
3169 sqlite3_mutex_enter(db
->mutex
);
3170 sqlite3BtreeSetPageSize(db
->aDb
[0].pBt
, 0, x
, 0);
3171 sqlite3_mutex_leave(db
->mutex
);
3175 /* sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS, sqlite3 *db, int N)
3177 ** Enable or disable various optimizations for testing purposes. The
3178 ** argument N is a bitmask of optimizations to be disabled. For normal
3179 ** operation N should be 0. The idea is that a test program (like the
3180 ** SQL Logic Test or SLT test module) can run the same SQL multiple times
3181 ** with various optimizations disabled to verify that the same answer
3182 ** is obtained in every case.
3184 case SQLITE_TESTCTRL_OPTIMIZATIONS
: {
3185 sqlite3
*db
= va_arg(ap
, sqlite3
*);
3186 db
->dbOptFlags
= (u16
)(va_arg(ap
, int) & 0xffff);
3190 #ifdef SQLITE_N_KEYWORD
3191 /* sqlite3_test_control(SQLITE_TESTCTRL_ISKEYWORD, const char *zWord)
3193 ** If zWord is a keyword recognized by the parser, then return the
3194 ** number of keywords. Or if zWord is not a keyword, return 0.
3196 ** This test feature is only available in the amalgamation since
3197 ** the SQLITE_N_KEYWORD macro is not defined in this file if SQLite
3198 ** is built using separate source files.
3200 case SQLITE_TESTCTRL_ISKEYWORD
: {
3201 const char *zWord
= va_arg(ap
, const char*);
3202 int n
= sqlite3Strlen30(zWord
);
3203 rc
= (sqlite3KeywordCode((u8
*)zWord
, n
)!=TK_ID
) ? SQLITE_N_KEYWORD
: 0;
3208 /* sqlite3_test_control(SQLITE_TESTCTRL_SCRATCHMALLOC, sz, &pNew, pFree);
3210 ** Pass pFree into sqlite3ScratchFree().
3211 ** If sz>0 then allocate a scratch buffer into pNew.
3213 case SQLITE_TESTCTRL_SCRATCHMALLOC
: {
3214 void *pFree
, **ppNew
;
3216 sz
= va_arg(ap
, int);
3217 ppNew
= va_arg(ap
, void**);
3218 pFree
= va_arg(ap
, void*);
3219 if( sz
) *ppNew
= sqlite3ScratchMalloc(sz
);
3220 sqlite3ScratchFree(pFree
);
3224 /* sqlite3_test_control(SQLITE_TESTCTRL_LOCALTIME_FAULT, int onoff);
3226 ** If parameter onoff is non-zero, configure the wrappers so that all
3227 ** subsequent calls to localtime() and variants fail. If onoff is zero,
3228 ** undo this setting.
3230 case SQLITE_TESTCTRL_LOCALTIME_FAULT
: {
3231 sqlite3GlobalConfig
.bLocaltimeFault
= va_arg(ap
, int);
3235 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
3236 /* sqlite3_test_control(SQLITE_TESTCTRL_EXPLAIN_STMT,
3237 ** sqlite3_stmt*,const char**);
3239 ** If compiled with SQLITE_ENABLE_TREE_EXPLAIN, each sqlite3_stmt holds
3240 ** a string that describes the optimized parse tree. This test-control
3241 ** returns a pointer to that string.
3243 case SQLITE_TESTCTRL_EXPLAIN_STMT
: {
3244 sqlite3_stmt
*pStmt
= va_arg(ap
, sqlite3_stmt
*);
3245 const char **pzRet
= va_arg(ap
, const char**);
3246 *pzRet
= sqlite3VdbeExplanation((Vdbe
*)pStmt
);
3253 #endif /* SQLITE_OMIT_BUILTIN_TEST */
3258 ** This is a utility routine, useful to VFS implementations, that checks
3259 ** to see if a database file was a URI that contained a specific query
3260 ** parameter, and if so obtains the value of the query parameter.
3262 ** The zFilename argument is the filename pointer passed into the xOpen()
3263 ** method of a VFS implementation. The zParam argument is the name of the
3264 ** query parameter we seek. This routine returns the value of the zParam
3265 ** parameter if it exists. If the parameter does not exist, this routine
3266 ** returns a NULL pointer.
3268 const char *sqlite3_uri_parameter(const char *zFilename
, const char *zParam
){
3269 if( zFilename
==0 ) return 0;
3270 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3271 while( zFilename
[0] ){
3272 int x
= strcmp(zFilename
, zParam
);
3273 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3274 if( x
==0 ) return zFilename
;
3275 zFilename
+= sqlite3Strlen30(zFilename
) + 1;
3281 ** Return a boolean value for a query parameter.
3283 int sqlite3_uri_boolean(const char *zFilename
, const char *zParam
, int bDflt
){
3284 const char *z
= sqlite3_uri_parameter(zFilename
, zParam
);
3286 return z
? sqlite3GetBoolean(z
, bDflt
) : bDflt
;
3290 ** Return a 64-bit integer value for a query parameter.
3292 sqlite3_int64
sqlite3_uri_int64(
3293 const char *zFilename
, /* Filename as passed to xOpen */
3294 const char *zParam
, /* URI parameter sought */
3295 sqlite3_int64 bDflt
/* return if parameter is missing */
3297 const char *z
= sqlite3_uri_parameter(zFilename
, zParam
);
3299 if( z
&& sqlite3Atoi64(z
, &v
, sqlite3Strlen30(z
), SQLITE_UTF8
)==SQLITE_OK
){
3306 ** Return the Btree pointer identified by zDbName. Return NULL if not found.
3308 Btree
*sqlite3DbNameToBtree(sqlite3
*db
, const char *zDbName
){
3310 for(i
=0; i
<db
->nDb
; i
++){
3312 && (zDbName
==0 || sqlite3StrICmp(zDbName
, db
->aDb
[i
].zName
)==0)
3314 return db
->aDb
[i
].pBt
;
3321 ** Return the filename of the database associated with a database
3324 const char *sqlite3_db_filename(sqlite3
*db
, const char *zDbName
){
3325 Btree
*pBt
= sqlite3DbNameToBtree(db
, zDbName
);
3326 return pBt
? sqlite3BtreeGetFilename(pBt
) : 0;
3330 ** Return 1 if database is read-only or 0 if read/write. Return -1 if
3331 ** no such database exists.
3333 int sqlite3_db_readonly(sqlite3
*db
, const char *zDbName
){
3334 Btree
*pBt
= sqlite3DbNameToBtree(db
, zDbName
);
3335 return pBt
? sqlite3PagerIsreadonly(sqlite3BtreePager(pBt
)) : -1;