1 /*

     2 ** 2001 September 15

     3 **

     4 ** The author disclaims copyright to this source code.  In place of

     5 ** a legal notice, here is a blessing:

     6 **

     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.

    10 **

    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.

    16 **

    17 ** $Id: main.c,v 1.502 2008/09/23 17:39:26 danielk1977 Exp $

    18 */

    19 #include "sqliteInt.h"

    20 #include <ctype.h>

    21 

    22 #ifdef SQLITE_ENABLE_FTS3

    23 # include "fts3.h"

    24 #endif

    25 #ifdef SQLITE_ENABLE_RTREE

    26 # include "rtree.h"

    27 #endif

    28 #ifdef SQLITE_ENABLE_ICU

    29 # include "sqliteicu.h"

    30 #endif

    31 

    32 /*

    33 ** The version of the library

    34 */

    35 const char sqlite3_version[] = SQLITE_VERSION;

    36 SQLITE_EXPORT const char *sqlite3_libversion(void){ return sqlite3_version; }

    37 SQLITE_EXPORT int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }

    38 SQLITE_EXPORT int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE; }

    39 

    40 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)

    41 /*

    42 ** If the following function pointer is not NULL and if

    43 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing

    44 ** I/O active are written using this function.  These messages

    45 ** are intended for debugging activity only.

    46 */

    47 void (*sqlite3IoTrace)(const char*, ...) = 0;

    48 #endif

    49 

    50 /*

    51 ** If the following global variable points to a string which is the

    52 ** name of a directory, then that directory will be used to store

    53 ** temporary files.

    54 **

    55 ** See also the "PRAGMA temp_store_directory" SQL command.

    56 */

    57 char *sqlite3_temp_directory = 0;

    58 

    59 /*

    60 ** Initialize SQLite.  

    61 **

    62 ** This routine must be called to initialize the memory allocation,

    63 ** VFS, and mutex subsystems prior to doing any serious work with

    64 ** SQLite.  But as long as you do not compile with SQLITE_OMIT_AUTOINIT

    65 ** this routine will be called automatically by key routines such as

    66 ** sqlite3_open().  

    67 **

    68 ** This routine is a no-op except on its very first call for the process,

    69 ** or for the first call after a call to sqlite3_shutdown.

    70 **

    71 ** The first thread to call this routine runs the initialization to

    72 ** completion.  If subsequent threads call this routine before the first

    73 ** thread has finished the initialization process, then the subsequent

    74 ** threads must block until the first thread finishes with the initialization.

    75 **

    76 ** The first thread might call this routine recursively.  Recursive

    77 ** calls to this routine should not block, of course.  Otherwise the

    78 ** initialization process would never complete.

    79 **

    80 ** Let X be the first thread to enter this routine.  Let Y be some other

    81 ** thread.  Then while the initial invocation of this routine by X is

    82 ** incomplete, it is required that:

    83 **

    84 **    *  Calls to this routine from Y must block until the outer-most

    85 **       call by X completes.

    86 **

    87 **    *  Recursive calls to this routine from thread X return immediately

    88 **       without blocking.

    89 */

    90 SQLITE_EXPORT int sqlite3_initialize(void){

    91   sqlite3_mutex *pMaster;                      /* The main static mutex */

    92   int rc;                                      /* Result code */

    93 

    94 #ifdef SQLITE_OMIT_WSD

    95   rc = sqlite3_wsd_init(4096, 24);

    96   if( rc!=SQLITE_OK ){

    97     return rc;

    98   }

    99 #endif

   100 

   101   /* If SQLite is already completely initialized, then this call

   102   ** to sqlite3_initialize() should be a no-op.  But the initialization

   103   ** must be complete.  So isInit must not be set until the very end

   104   ** of this routine.

   105   */

   106   if( sqlite3GlobalConfig.isInit ) return SQLITE_OK;

   107 

   108   /* Make sure the mutex subsystem is initialized.  If unable to 

   109   ** initialize the mutex subsystem, return early with the error.

   110   ** If the system is so sick that we are unable to allocate a mutex,

   111   ** there is not much SQLite is going to be able to do.

   112   **

   113   ** The mutex subsystem must take care of serializing its own

   114   ** initialization.

   115   */

   116   rc = sqlite3MutexInit();

   117   if( rc ) return rc;

   118 

   119   /* Initialize the malloc() system and the recursive pInitMutex mutex.

   120   ** This operation is protected by the STATIC_MASTER mutex.  Note that

   121   ** MutexAlloc() is called for a static mutex prior to initializing the

   122   ** malloc subsystem - this implies that the allocation of a static

   123   ** mutex must not require support from the malloc subsystem.

   124   */

   125   pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);

   126   sqlite3_mutex_enter(pMaster);

   127   if( !sqlite3GlobalConfig.isMallocInit ){

   128     rc = sqlite3MallocInit();

   129   }

   130   if( rc==SQLITE_OK ){

   131     sqlite3GlobalConfig.isMallocInit = 1;

   132     if( !sqlite3GlobalConfig.pInitMutex ){

   133       sqlite3GlobalConfig.pInitMutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);

   134       if( sqlite3GlobalConfig.bCoreMutex && !sqlite3GlobalConfig.pInitMutex ){

   135         rc = SQLITE_NOMEM;

   136       }

   137     }

   138     if( rc==SQLITE_OK )    

   139       sqlite3GlobalConfig.nRefInitMutex++;

   140   }

   141   sqlite3_mutex_leave(pMaster);

   142 

   143   /* If unable to initialize the malloc subsystem, then return early.

   144   ** There is little hope of getting SQLite to run if the malloc

   145   ** subsystem cannot be initialized.

   146   */

   147   if( rc!=SQLITE_OK ){

   148     return rc;

   149   }

   150 

   151   /* Do the rest of the initialization under the recursive mutex so

   152   ** that we will be able to handle recursive calls into

   153   ** sqlite3_initialize().  The recursive calls normally come through

   154   ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other

   155   ** recursive calls might also be possible.

   156   */

   157   sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex);

   158   if( sqlite3GlobalConfig.isInit==0 && sqlite3GlobalConfig.inProgress==0 ){

   159     FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);

   160     sqlite3GlobalConfig.inProgress = 1;

   161     memset(pHash, 0, sizeof(sqlite3GlobalFunctions));

   162     sqlite3RegisterGlobalFunctions();

   163     rc = sqlite3_os_init();

   164     if( rc==SQLITE_OK ){

   165       rc = sqlite3PcacheInitialize();

   166       sqlite3PCacheBufferSetup( sqlite3GlobalConfig.pPage, 

   167           sqlite3GlobalConfig.szPage, sqlite3GlobalConfig.nPage);

   168     }

   169     sqlite3GlobalConfig.inProgress = 0;

   170     sqlite3GlobalConfig.isInit = (rc==SQLITE_OK ? 1 : 0);

   171   }

   172   sqlite3_mutex_leave(sqlite3GlobalConfig.pInitMutex);

   173 

   174   /* Go back under the static mutex and clean up the recursive

   175   ** mutex to prevent a resource leak.

   176   */

   177   sqlite3_mutex_enter(pMaster);

   178   sqlite3GlobalConfig.nRefInitMutex--;

   179   if( sqlite3GlobalConfig.nRefInitMutex<=0 ){

   180     assert( sqlite3GlobalConfig.nRefInitMutex==0 );

   181     sqlite3_mutex_free(sqlite3GlobalConfig.pInitMutex);

   182     sqlite3GlobalConfig.pInitMutex = 0;

   183   }

   184   sqlite3_mutex_leave(pMaster);

   185 

   186   /* The following is just a sanity check to make sure SQLite has

   187   ** been compiled correctly.  It is important to run this code, but

   188   ** we don't want to run it too often and soak up CPU cycles for no

   189   ** reason.  So we run it once during initialization.

   190   */

   191 #ifndef NDEBUG

   192   /* This section of code's only "output" is via assert() statements. */

   193   if ( rc==SQLITE_OK ){

   194     u64 x = (((u64)1)<<63)-1;

   195     double y;

   196     assert(sizeof(x)==8);

   197     assert(sizeof(x)==sizeof(y));

   198     memcpy(&y, &x, 8);

   199     assert( sqlite3IsNaN(y) );

   200   }

   201 #endif

   202 

   203   return rc;

   204 }

   205 

   206 /*

   207 ** Undo the effects of sqlite3_initialize().  Must not be called while

   208 ** there are outstanding database connections or memory allocations or

   209 ** while any part of SQLite is otherwise in use in any thread.  This

   210 ** routine is not threadsafe.  Not by a long shot.

   211 */

   212 SQLITE_EXPORT int sqlite3_shutdown(void){

   213   sqlite3GlobalConfig.isMallocInit = 0;

   214   sqlite3PcacheShutdown();

   215   if( sqlite3GlobalConfig.isInit ){

   216     sqlite3_os_end();

   217   }

   218   if( sqlite3GlobalConfig.m.xShutdown ){

   219     sqlite3MallocEnd();

   220   }

   221   if( sqlite3GlobalConfig.mutex.xMutexEnd ){

   222     sqlite3MutexEnd();

   223   }

   224   sqlite3GlobalConfig.isInit = 0;

   225   return SQLITE_OK;

   226 }

   227 

   228 /*

   229 ** This API allows applications to modify the global configuration of

   230 ** the SQLite library at run-time.

   231 **

   232 ** This routine should only be called when there are no outstanding

   233 ** database connections or memory allocations.  This routine is not

   234 ** threadsafe.  Failure to heed these warnings can lead to unpredictable

   235 ** behavior.

   236 */

   237 SQLITE_EXPORT int sqlite3_config(int op, ...){

   238   va_list ap;

   239   int rc = SQLITE_OK;

   240 

   241   /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while

   242   ** the SQLite library is in use. */

   243   if( sqlite3GlobalConfig.isInit ) return SQLITE_MISUSE;

   244 

   245   va_start(ap, op);

   246   switch( op ){

   247     case SQLITE_CONFIG_SINGLETHREAD: {

   248       /* Disable all mutexing */

   249       sqlite3GlobalConfig.bCoreMutex = 0;

   250       sqlite3GlobalConfig.bFullMutex = 0;

   251       break;

   252     }

   253     case SQLITE_CONFIG_MULTITHREAD: {

   254       /* Disable mutexing of database connections */

   255       /* Enable mutexing of core data structures */

   256       sqlite3GlobalConfig.bCoreMutex = 1;

   257       sqlite3GlobalConfig.bFullMutex = 0;

   258       break;

   259     }

   260     case SQLITE_CONFIG_SERIALIZED: {

   261       /* Enable all mutexing */

   262       sqlite3GlobalConfig.bCoreMutex = 1;

   263       sqlite3GlobalConfig.bFullMutex = 1;

   264       break;

   265     }

   266     case SQLITE_CONFIG_MALLOC: {

   267       /* Specify an alternative malloc implementation */

   268       sqlite3GlobalConfig.m = *va_arg(ap, sqlite3_mem_methods*);

   269       break;

   270     }

   271     case SQLITE_CONFIG_GETMALLOC: {

   272       /* Retrieve the current malloc() implementation */

   273       if( sqlite3GlobalConfig.m.xMalloc==0 ) sqlite3MemSetDefault();

   274       *va_arg(ap, sqlite3_mem_methods*) = sqlite3GlobalConfig.m;

   275       break;

   276     }

   277     case SQLITE_CONFIG_MUTEX: {

   278       /* Specify an alternative mutex implementation */

   279       sqlite3GlobalConfig.mutex = *va_arg(ap, sqlite3_mutex_methods*);

   280       break;

   281     }

   282     case SQLITE_CONFIG_GETMUTEX: {

   283       /* Retrieve the current mutex implementation */

   284       *va_arg(ap, sqlite3_mutex_methods*) = sqlite3GlobalConfig.mutex;

   285       break;

   286     }

   287     case SQLITE_CONFIG_MEMSTATUS: {

   288       /* Enable or disable the malloc status collection */

   289       sqlite3GlobalConfig.bMemstat = va_arg(ap, int);

   290       break;

   291     }

   292     case SQLITE_CONFIG_SCRATCH: {

   293       /* Designate a buffer for scratch memory space */

   294       sqlite3GlobalConfig.pScratch = va_arg(ap, void*);

   295       sqlite3GlobalConfig.szScratch = va_arg(ap, int);

   296       sqlite3GlobalConfig.nScratch = va_arg(ap, int);

   297       break;

   298     }

   299     case SQLITE_CONFIG_PAGECACHE: {

   300       /* Designate a buffer for scratch memory space */

   301       sqlite3GlobalConfig.pPage = va_arg(ap, void*);

   302       sqlite3GlobalConfig.szPage = va_arg(ap, int);

   303       sqlite3GlobalConfig.nPage = va_arg(ap, int);

   304       break;

   305     }

   306 

   307 #if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)

   308     case SQLITE_CONFIG_HEAP: {

   309       /* Designate a buffer for heap memory space */

   310       sqlite3GlobalConfig.pHeap = va_arg(ap, void*);

   311       sqlite3GlobalConfig.nHeap = va_arg(ap, int);

   312       sqlite3GlobalConfig.mnReq = va_arg(ap, int);

   313 

   314       if( sqlite3GlobalConfig.pHeap==0 ){

   315         /* If the heap pointer is NULL, then restore the malloc implementation

   316         ** back to NULL pointers too.  This will cause the malloc to go

   317         ** back to its default implementation when sqlite3_initialize() is

   318         ** run.

   319         */

   320         memset(&sqlite3GlobalConfig.m, 0, sizeof(sqlite3GlobalConfig.m));

   321       }else{

   322         /* The heap pointer is not NULL, then install one of the

   323         ** mem5.c/mem3.c methods. If neither ENABLE_MEMSYS3 nor

   324         ** ENABLE_MEMSYS5 is defined, return an error.

   325         ** the default case and return an error.

   326         */

   327 #ifdef SQLITE_ENABLE_MEMSYS3

   328         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys3();

   329 #endif

   330 #ifdef SQLITE_ENABLE_MEMSYS5

   331         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys5();

   332 #endif

   333       }

   334       break;

   335     }

   336 #endif

   337 

   338 #if defined(SQLITE_ENABLE_MEMSYS6)

   339     case SQLITE_CONFIG_CHUNKALLOC: {

   340       sqlite3GlobalConfig.nSmall = va_arg(ap, int);

   341       sqlite3GlobalConfig.m = *sqlite3MemGetMemsys6();

   342       break;

   343     }

   344 #endif

   345 

   346     case SQLITE_CONFIG_LOOKASIDE: {

   347       sqlite3GlobalConfig.szLookaside = va_arg(ap, int);

   348       sqlite3GlobalConfig.nLookaside = va_arg(ap, int);

   349       break;

   350     }

   351 

   352     default: {

   353       rc = SQLITE_ERROR;

   354       break;

   355     }

   356   }

   357   va_end(ap);

   358   return rc;

   359 }

   360 

   361 /*

   362 ** Set up the lookaside buffers for a database connection.

   363 ** Return SQLITE_OK on success.  

   364 ** If lookaside is already active, return SQLITE_BUSY.

   365 **

   366 ** The sz parameter is the number of bytes in each lookaside slot.

   367 ** The cnt parameter is the number of slots.  If pStart is NULL the

   368 ** space for the lookaside memory is obtained from sqlite3_malloc().

   369 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for

   370 ** the lookaside memory.

   371 */

   372 static int setupLookaside(sqlite3 *db, void *pBuf, int sz, int cnt){

   373   void *pStart;

   374   if( db->lookaside.nOut ){

   375     return SQLITE_BUSY;

   376   }

   377   if( sz<0 ) sz = 0;

   378   if( cnt<0 ) cnt = 0;

   379   if( pBuf==0 ){

   380     sz = (sz + 7)&~7;

   381     sqlite3BeginBenignMalloc();

   382     pStart = sqlite3Malloc( sz*cnt );

   383     sqlite3EndBenignMalloc();

   384   }else{

   385     sz = sz&~7;

   386     pStart = pBuf;

   387   }

   388   if( db->lookaside.bMalloced ){

   389     sqlite3_free(db->lookaside.pStart);

   390   }

   391   db->lookaside.pStart = pStart;

   392   db->lookaside.pFree = 0;

   393   db->lookaside.sz = sz;

   394   db->lookaside.bMalloced = pBuf==0;

   395   if( pStart ){

   396     int i;

   397     LookasideSlot *p;

   398     p = (LookasideSlot*)pStart;

   399     for(i=cnt-1; i>=0; i--){

   400       p->pNext = db->lookaside.pFree;

   401       db->lookaside.pFree = p;

   402       p = (LookasideSlot*)&((u8*)p)[sz];

   403     }

   404     db->lookaside.pEnd = p;

   405     db->lookaside.bEnabled = 1;

   406   }else{

   407     db->lookaside.pEnd = 0;

   408     db->lookaside.bEnabled = 0;

   409   }

   410   return SQLITE_OK;

   411 }

   412 

   413 /*

   414 ** Configuration settings for an individual database connection

   415 */

   416 SQLITE_EXPORT int sqlite3_db_config(sqlite3 *db, int op, ...){

   417   va_list ap;

   418   int rc;

   419   va_start(ap, op);

   420   switch( op ){

   421     case SQLITE_DBCONFIG_LOOKASIDE: {

   422       void *pBuf = va_arg(ap, void*);

   423       int sz = va_arg(ap, int);

   424       int cnt = va_arg(ap, int);

   425       rc = setupLookaside(db, pBuf, sz, cnt);

   426       break;

   427     }

   428     default: {

   429       rc = SQLITE_ERROR;

   430       break;

   431     }

   432   }

   433   va_end(ap);

   434   return rc;

   435 }

   436 

   437 /*

   438 ** Routine needed to support the testcase() macro.

   439 */

   440 #ifdef SQLITE_COVERAGE_TEST

   441 void sqlite3Coverage(int x){

   442   static int dummy = 0;

   443   dummy += x;

   444 }

   445 #endif

   446 

   447 

   448 /*

   449 ** Return true if the buffer z[0..n-1] contains all spaces.

   450 */

   451 static int allSpaces(const char *z, int n){

   452   while( n>0 && z[n-1]==' ' ){ n--; }

   453   return n==0;

   454 }

   455 

   456 /*

   457 ** This is the default collating function named "BINARY" which is always

   458 ** available.

   459 **

   460 ** If the padFlag argument is not NULL then space padding at the end

   461 ** of strings is ignored.  This implements the RTRIM collation.

   462 */

   463 static int binCollFunc(

   464   void *padFlag,

   465   int nKey1, const void *pKey1,

   466   int nKey2, const void *pKey2

   467 ){

   468   int rc, n;

   469   n = nKey1<nKey2 ? nKey1 : nKey2;

   470   rc = memcmp(pKey1, pKey2, n);

   471   if( rc==0 ){

   472     if( padFlag

   473      && allSpaces(((char*)pKey1)+n, nKey1-n)

   474      && allSpaces(((char*)pKey2)+n, nKey2-n)

   475     ){

   476       /* Leave rc unchanged at 0 */

   477     }else{

   478       rc = nKey1 - nKey2;

   479     }

   480   }

   481   return rc;

   482 }

   483 

   484 /*

   485 ** Another built-in collating sequence: NOCASE. 

   486 **

   487 ** This collating sequence is intended to be used for "case independant

   488 ** comparison". SQLite's knowledge of upper and lower case equivalents

   489 ** extends only to the 26 characters used in the English language.

   490 **

   491 ** At the moment there is only a UTF-8 implementation.

   492 */

   493 static int nocaseCollatingFunc(

   494   void *NotUsed,

   495   int nKey1, const void *pKey1,

   496   int nKey2, const void *pKey2

   497 ){

   498   int r = sqlite3StrNICmp(

   499       (const char *)pKey1, (const char *)pKey2, (nKey1<nKey2)?nKey1:nKey2);

   500   if( 0==r ){

   501     r = nKey1-nKey2;

   502   }

   503   return r;

   504 }

   505 

   506 /*

   507 ** Return the ROWID of the most recent insert

   508 */

   509 SQLITE_EXPORT sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){

   510   return db->lastRowid;

   511 }

   512 

   513 /*

   514 ** Return the number of changes in the most recent call to sqlite3_exec().

   515 */

   516 SQLITE_EXPORT int sqlite3_changes(sqlite3 *db){

   517   return db->nChange;

   518 }

   519 

   520 /*

   521 ** Return the number of changes since the database handle was opened.

   522 */

   523 SQLITE_EXPORT int sqlite3_total_changes(sqlite3 *db){

   524   return db->nTotalChange;

   525 }

   526 

   527 /*

   528 ** Close an existing SQLite database

   529 */

   530 SQLITE_EXPORT int sqlite3_close(sqlite3 *db){

   531   HashElem *i;

   532   int j;

   533 

   534   if( !db ){

   535     return SQLITE_OK;

   536   }

   537   if( !sqlite3SafetyCheckSickOrOk(db) ){

   538     return SQLITE_MISUSE;

   539   }

   540   sqlite3_mutex_enter(db->mutex);

   541 

   542 #ifdef SQLITE_SSE

   543   {

   544     extern void sqlite3SseCleanup(sqlite3*);

   545     sqlite3SseCleanup(db);

   546   }

   547 #endif 

   548 

   549   sqlite3ResetInternalSchema(db, 0);

   550 

   551   /* If a transaction is open, the ResetInternalSchema() call above

   552   ** will not have called the xDisconnect() method on any virtual

   553   ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()

   554   ** call will do so. We need to do this before the check for active

   555   ** SQL statements below, as the v-table implementation may be storing

   556   ** some prepared statements internally.

   557   */

   558   sqlite3VtabRollback(db);

   559 

   560   /* If there are any outstanding VMs, return SQLITE_BUSY. */

   561   if( db->pVdbe ){

   562     sqlite3Error(db, SQLITE_BUSY, 

   563         "Unable to close due to unfinalised statements");

   564     sqlite3_mutex_leave(db->mutex);

   565     return SQLITE_BUSY;

   566   }

   567   assert( sqlite3SafetyCheckSickOrOk(db) );

   568 

   569   for(j=0; j<db->nDb; j++){

   570     struct Db *pDb = &db->aDb[j];

   571     if( pDb->pBt ){

   572       sqlite3BtreeClose(pDb->pBt);

   573       pDb->pBt = 0;

   574       if( j!=1 ){

   575         pDb->pSchema = 0;

   576       }

   577     }

   578   }

   579   sqlite3ResetInternalSchema(db, 0);

   580   assert( db->nDb<=2 );

   581   assert( db->aDb==db->aDbStatic );

   582   for(j=0; j<ArraySize(db->aFunc.a); j++){

   583     FuncDef *pNext, *pHash, *p;

   584     for(p=db->aFunc.a[j]; p; p=pHash){

   585       pHash = p->pHash;

   586       while( p ){

   587         pNext = p->pNext;

   588         sqlite3DbFree(db, p);

   589         p = pNext;

   590       }

   591     }

   592   }

   593   for(i=sqliteHashFirst(&db->aCollSeq); i; i=sqliteHashNext(i)){

   594     CollSeq *pColl = (CollSeq *)sqliteHashData(i);

   595     /* Invoke any destructors registered for collation sequence user data. */

   596     for(j=0; j<3; j++){

   597       if( pColl[j].xDel ){

   598         pColl[j].xDel(pColl[j].pUser);

   599       }

   600     }

   601     sqlite3DbFree(db, pColl);

   602   }

   603   sqlite3HashClear(&db->aCollSeq);

   604 #ifndef SQLITE_OMIT_VIRTUALTABLE

   605   for(i=sqliteHashFirst(&db->aModule); i; i=sqliteHashNext(i)){

   606     Module *pMod = (Module *)sqliteHashData(i);

   607     if( pMod->xDestroy ){

   608       pMod->xDestroy(pMod->pAux);

   609     }

   610     sqlite3DbFree(db, pMod);

   611   }

   612   sqlite3HashClear(&db->aModule);

   613 #endif

   614 

   615   sqlite3Error(db, SQLITE_OK, 0); /* Deallocates any cached error strings. */

   616   if( db->pErr ){

   617     sqlite3ValueFree(db->pErr);

   618   }

   619   sqlite3CloseExtensions(db);

   620 

   621   db->magic = SQLITE_MAGIC_ERROR;

   622 

   623   /* The temp-database schema is allocated differently from the other schema

   624   ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).

   625   ** So it needs to be freed here. Todo: Why not roll the temp schema into

   626   ** the same sqliteMalloc() as the one that allocates the database 

   627   ** structure?

   628   */

   629   sqlite3DbFree(db, db->aDb[1].pSchema);

   630   sqlite3_mutex_leave(db->mutex);

   631   db->magic = SQLITE_MAGIC_CLOSED;

   632   sqlite3_mutex_free(db->mutex);

   633   if( db->lookaside.bMalloced ){

   634     sqlite3_free(db->lookaside.pStart);

   635   }

   636   sqlite3_free(db);

   637   return SQLITE_OK;

   638 }

   639 

   640 /*

   641 ** Rollback all database files.

   642 */

   643 void sqlite3RollbackAll(sqlite3 *db){

   644   int i;

   645   int inTrans = 0;

   646   assert( sqlite3_mutex_held(db->mutex) );

   647   sqlite3BeginBenignMalloc();

   648   for(i=0; i<db->nDb; i++){

   649     if( db->aDb[i].pBt ){

   650       if( sqlite3BtreeIsInTrans(db->aDb[i].pBt) ){

   651         inTrans = 1;

   652       }

   653       sqlite3BtreeRollback(db->aDb[i].pBt);

   654       db->aDb[i].inTrans = 0;

   655     }

   656   }

   657   sqlite3VtabRollback(db);

   658   sqlite3EndBenignMalloc();

   659 

   660   if( db->flags&SQLITE_InternChanges ){

   661     sqlite3ExpirePreparedStatements(db);

   662     sqlite3ResetInternalSchema(db, 0);

   663   }

   664 

   665   /* If one has been configured, invoke the rollback-hook callback */

   666   if( db->xRollbackCallback && (inTrans || !db->autoCommit) ){

   667     db->xRollbackCallback(db->pRollbackArg);

   668   }

   669 }

   670 

   671 /*

   672 ** Return a static string that describes the kind of error specified in the

   673 ** argument.

   674 */

   675 const char *sqlite3ErrStr(int rc){

   676   const char *z;

   677   switch( rc & 0xff ){

   678     case SQLITE_ROW:

   679     case SQLITE_DONE:

   680     case SQLITE_OK:         z = "not an error";                          break;

   681     case SQLITE_ERROR:      z = "SQL logic error or missing database";   break;

   682     case SQLITE_PERM:       z = "access permission denied";              break;

   683     case SQLITE_ABORT:      z = "callback requested query abort";        break;

   684     case SQLITE_BUSY:       z = "database is locked";                    break;

   685     case SQLITE_LOCKED:     z = "database table is locked";              break;

   686     case SQLITE_NOMEM:      z = "out of memory";                         break;

   687     case SQLITE_READONLY:   z = "attempt to write a readonly database";  break;

   688     case SQLITE_INTERRUPT:  z = "interrupted";                           break;

   689     case SQLITE_IOERR:      z = "disk I/O error";                        break;

   690     case SQLITE_CORRUPT:    z = "database disk image is malformed";      break;

   691     case SQLITE_FULL:       z = "database or disk is full";              break;

   692     case SQLITE_CANTOPEN:   z = "unable to open database file";          break;

   693     case SQLITE_EMPTY:      z = "table contains no data";                break;

   694     case SQLITE_SCHEMA:     z = "database schema has changed";           break;

   695     case SQLITE_TOOBIG:     z = "String or BLOB exceeded size limit";    break;

   696     case SQLITE_CONSTRAINT: z = "constraint failed";                     break;

   697     case SQLITE_MISMATCH:   z = "datatype mismatch";                     break;

   698     case SQLITE_MISUSE:     z = "library routine called out of sequence";break;

   699     case SQLITE_NOLFS:      z = "large file support is disabled";        break;

   700     case SQLITE_AUTH:       z = "authorization denied";                  break;

   701     case SQLITE_FORMAT:     z = "auxiliary database format error";       break;

   702     case SQLITE_RANGE:      z = "bind or column index out of range";     break;

   703     case SQLITE_NOTADB:     z = "file is encrypted or is not a database";break;

   704     default:                z = "unknown error";                         break;

   705   }

   706   return z;

   707 }

   708 

   709 /*

   710 ** This routine implements a busy callback that sleeps and tries

   711 ** again until a timeout value is reached.  The timeout value is

   712 ** an integer number of milliseconds passed in as the first

   713 ** argument.

   714 */

   715 static int sqliteDefaultBusyCallback(

   716  void *ptr,               /* Database connection */

   717  int count                /* Number of times table has been busy */

   718 ){

   719 #if SQLITE_OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)

   720   static const u8 delays[] =

   721      { 1, 2, 5, 10, 15, 20, 25, 25,  25,  50,  50, 100 };

   722   static const u8 totals[] =

   723      { 0, 1, 3,  8, 18, 33, 53, 78, 103, 128, 178, 228 };

   724 # define NDELAY (sizeof(delays)/sizeof(delays[0]))

   725   sqlite3 *db = (sqlite3 *)ptr;

   726   int timeout = db->busyTimeout;

   727   int delay, prior;

   728 

   729   assert( count>=0 );

   730   if( count < NDELAY ){

   731     delay = delays[count];

   732     prior = totals[count];

   733   }else{

   734     delay = delays[NDELAY-1];

   735     prior = totals[NDELAY-1] + delay*(count-(NDELAY-1));

   736   }

   737   if( prior + delay > timeout ){

   738     delay = timeout - prior;

   739     if( delay<=0 ) return 0;

   740   }

   741   sqlite3OsSleep(db->pVfs, delay*1000);

   742   return 1;

   743 #else

   744   sqlite3 *db = (sqlite3 *)ptr;

   745   int timeout = ((sqlite3 *)ptr)->busyTimeout;

   746   if( (count+1)*1000 > timeout ){

   747     return 0;

   748   }

   749   sqlite3OsSleep(db->pVfs, 1000000);

   750   return 1;

   751 #endif

   752 }

   753 

   754 /*

   755 ** Invoke the given busy handler.

   756 **

   757 ** This routine is called when an operation failed with a lock.

   758 ** If this routine returns non-zero, the lock is retried.  If it

   759 ** returns 0, the operation aborts with an SQLITE_BUSY error.

   760 */

   761 int sqlite3InvokeBusyHandler(BusyHandler *p){

   762   int rc;

   763   if( NEVER(p==0) || p->xFunc==0 || p->nBusy<0 ) return 0;

   764   rc = p->xFunc(p->pArg, p->nBusy);

   765   if( rc==0 ){

   766     p->nBusy = -1;

   767   }else{

   768     p->nBusy++;

   769   }

   770   return rc; 

   771 }

   772 

   773 /*

   774 ** This routine sets the busy callback for an Sqlite database to the

   775 ** given callback function with the given argument.

   776 */

   777 SQLITE_EXPORT int sqlite3_busy_handler(

   778   sqlite3 *db,

   779   int (*xBusy)(void*,int),

   780   void *pArg

   781 ){

   782   sqlite3_mutex_enter(db->mutex);

   783   db->busyHandler.xFunc = xBusy;

   784   db->busyHandler.pArg = pArg;

   785   db->busyHandler.nBusy = 0;

   786   sqlite3_mutex_leave(db->mutex);

   787   return SQLITE_OK;

   788 }

   789 

   790 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

   791 /*

   792 ** This routine sets the progress callback for an Sqlite database to the

   793 ** given callback function with the given argument. The progress callback will

   794 ** be invoked every nOps opcodes.

   795 */

   796 SQLITE_EXPORT void sqlite3_progress_handler(

   797   sqlite3 *db, 

   798   int nOps,

   799   int (*xProgress)(void*), 

   800   void *pArg

   801 ){

   802   sqlite3_mutex_enter(db->mutex);

   803   if( nOps>0 ){

   804     db->xProgress = xProgress;

   805     db->nProgressOps = nOps;

   806     db->pProgressArg = pArg;

   807   }else{

   808     db->xProgress = 0;

   809     db->nProgressOps = 0;

   810     db->pProgressArg = 0;

   811   }

   812   sqlite3_mutex_leave(db->mutex);

   813 }

   814 #endif

   815 

   816 

   817 /*

   818 ** This routine installs a default busy handler that waits for the

   819 ** specified number of milliseconds before returning 0.

   820 */

   821 SQLITE_EXPORT int sqlite3_busy_timeout(sqlite3 *db, int ms){

   822   if( ms>0 ){

   823     db->busyTimeout = ms;

   824     sqlite3_busy_handler(db, sqliteDefaultBusyCallback, (void*)db);

   825   }else{

   826     sqlite3_busy_handler(db, 0, 0);

   827   }

   828   return SQLITE_OK;

   829 }

   830 

   831 /*

   832 ** Cause any pending operation to stop at its earliest opportunity.

   833 */

   834 SQLITE_EXPORT void sqlite3_interrupt(sqlite3 *db){

   835   db->u1.isInterrupted = 1;

   836 }

   837 

   838 

   839 /*

   840 ** This function is exactly the same as sqlite3_create_function(), except

   841 ** that it is designed to be called by internal code. The difference is

   842 ** that if a malloc() fails in sqlite3_create_function(), an error code

   843 ** is returned and the mallocFailed flag cleared. 

   844 */

   845 int sqlite3CreateFunc(

   846   sqlite3 *db,

   847   const char *zFunctionName,

   848   int nArg,

   849   int enc,

   850   void *pUserData,

   851   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),

   852   void (*xStep)(sqlite3_context*,int,sqlite3_value **),

   853   void (*xFinal)(sqlite3_context*)

   854 ){

   855   FuncDef *p;

   856   int nName;

   857 

   858   assert( sqlite3_mutex_held(db->mutex) );

   859   if( zFunctionName==0 ||

   860       (xFunc && (xFinal || xStep)) || 

   861       (!xFunc && (xFinal && !xStep)) ||

   862       (!xFunc && (!xFinal && xStep)) ||

   863       (nArg<-1 || nArg>SQLITE_MAX_FUNCTION_ARG) ||

   864       (255<(nName = sqlite3Strlen(db, zFunctionName))) ){

   865     sqlite3Error(db, SQLITE_ERROR, "bad parameters");

   866     return SQLITE_ERROR;

   867   }

   868   

   869 #ifndef SQLITE_OMIT_UTF16

   870   /* If SQLITE_UTF16 is specified as the encoding type, transform this

   871   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

   872   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.

   873   **

   874   ** If SQLITE_ANY is specified, add three versions of the function

   875   ** to the hash table.

   876   */

   877   if( enc==SQLITE_UTF16 ){

   878     enc = SQLITE_UTF16NATIVE;

   879   }else if( enc==SQLITE_ANY ){

   880     int rc;

   881     rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF8,

   882          pUserData, xFunc, xStep, xFinal);

   883     if( rc==SQLITE_OK ){

   884       rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF16LE,

   885           pUserData, xFunc, xStep, xFinal);

   886     }

   887     if( rc!=SQLITE_OK ){

   888       return rc;

   889     }

   890     enc = SQLITE_UTF16BE;

   891   }

   892 #else

   893   enc = SQLITE_UTF8;

   894 #endif

   895   

   896   /* Check if an existing function is being overridden or deleted. If so,

   897   ** and there are active VMs, then return SQLITE_BUSY. If a function

   898   ** is being overridden/deleted but there are no active VMs, allow the

   899   ** operation to continue but invalidate all precompiled statements.

   900   */

   901   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, enc, 0);

   902   if( p && p->iPrefEnc==enc && p->nArg==nArg ){

   903     if( db->activeVdbeCnt ){

   904       sqlite3Error(db, SQLITE_BUSY, 

   905         "Unable to delete/modify user-function due to active statements");

   906       assert( !db->mallocFailed );

   907       return SQLITE_BUSY;

   908     }else{

   909       sqlite3ExpirePreparedStatements(db);

   910     }

   911   }

   912 

   913   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, enc, 1);

   914   assert(p || db->mallocFailed);

   915   if( !p ){

   916     return SQLITE_NOMEM;

   917   }

   918   p->flags = 0;

   919   p->xFunc = xFunc;

   920   p->xStep = xStep;

   921   p->xFinalize = xFinal;

   922   p->pUserData = pUserData;

   923   p->nArg = nArg;

   924   return SQLITE_OK;

   925 }

   926 

   927 /*

   928 ** Create new user functions.

   929 */

   930 SQLITE_EXPORT int sqlite3_create_function(

   931   sqlite3 *db,

   932   const char *zFunctionName,

   933   int nArg,

   934   int enc,

   935   void *p,

   936   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),

   937   void (*xStep)(sqlite3_context*,int,sqlite3_value **),

   938   void (*xFinal)(sqlite3_context*)

   939 ){

   940   int rc;

   941   sqlite3_mutex_enter(db->mutex);

   942   rc = sqlite3CreateFunc(db, zFunctionName, nArg, enc, p, xFunc, xStep, xFinal);

   943   rc = sqlite3ApiExit(db, rc);

   944   sqlite3_mutex_leave(db->mutex);

   945   return rc;

   946 }

   947 

   948 #ifndef SQLITE_OMIT_UTF16

   949 SQLITE_EXPORT int sqlite3_create_function16(

   950   sqlite3 *db,

   951   const void *zFunctionName,

   952   int nArg,

   953   int eTextRep,

   954   void *p,

   955   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),

   956   void (*xStep)(sqlite3_context*,int,sqlite3_value**),

   957   void (*xFinal)(sqlite3_context*)

   958 ){

   959   int rc;

   960   char *zFunc8;

   961   sqlite3_mutex_enter(db->mutex);

   962   assert( !db->mallocFailed );

   963   zFunc8 = sqlite3Utf16to8(db, zFunctionName, -1);

   964   rc = sqlite3CreateFunc(db, zFunc8, nArg, eTextRep, p, xFunc, xStep, xFinal);

   965   sqlite3DbFree(db, zFunc8);

   966   rc = sqlite3ApiExit(db, rc);

   967   sqlite3_mutex_leave(db->mutex);

   968   return rc;

   969 }

   970 #endif

   971 

   972 

   973 /*

   974 ** Declare that a function has been overloaded by a virtual table.

   975 **

   976 ** If the function already exists as a regular global function, then

   977 ** this routine is a no-op.  If the function does not exist, then create

   978 ** a new one that always throws a run-time error.  

   979 **

   980 ** When virtual tables intend to provide an overloaded function, they

   981 ** should call this routine to make sure the global function exists.

   982 ** A global function must exist in order for name resolution to work

   983 ** properly.

   984 */

   985 SQLITE_EXPORT int sqlite3_overload_function(

   986   sqlite3 *db,

   987   const char *zName,

   988   int nArg

   989 ){

   990   int nName = sqlite3Strlen(db, zName);

   991   int rc;

   992   sqlite3_mutex_enter(db->mutex);

   993   if( sqlite3FindFunction(db, zName, nName, nArg, SQLITE_UTF8, 0)==0 ){

   994     sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,

   995                       0, sqlite3InvalidFunction, 0, 0);

   996   }

   997   rc = sqlite3ApiExit(db, SQLITE_OK);

   998   sqlite3_mutex_leave(db->mutex);

   999   return rc;

  1000 }

  1001 

  1002 #ifndef SQLITE_OMIT_TRACE

  1003 /*

  1004 ** Register a trace function.  The pArg from the previously registered trace

  1005 ** is returned.  

  1006 **

  1007 ** A NULL trace function means that no tracing is executes.  A non-NULL

  1008 ** trace is a pointer to a function that is invoked at the start of each

  1009 ** SQL statement.

  1010 */

  1011 SQLITE_EXPORT void *sqlite3_trace(sqlite3 *db, void (*xTrace)(void*,const char*), void *pArg){

  1012   void *pOld;

  1013   sqlite3_mutex_enter(db->mutex);

  1014   pOld = db->pTraceArg;

  1015   db->xTrace = xTrace;

  1016   db->pTraceArg = pArg;

  1017   sqlite3_mutex_leave(db->mutex);

  1018   return pOld;

  1019 }

  1020 /*

  1021 ** Register a profile function.  The pArg from the previously registered 

  1022 ** profile function is returned.  

  1023 **

  1024 ** A NULL profile function means that no profiling is executes.  A non-NULL

  1025 ** profile is a pointer to a function that is invoked at the conclusion of

  1026 ** each SQL statement that is run.

  1027 */

  1028 SQLITE_EXPORT void *sqlite3_profile(

  1029   sqlite3 *db,

  1030   void (*xProfile)(void*,const char*,sqlite_uint64),

  1031   void *pArg

  1032 ){

  1033   void *pOld;

  1034   sqlite3_mutex_enter(db->mutex);

  1035   pOld = db->pProfileArg;

  1036   db->xProfile = xProfile;

  1037   db->pProfileArg = pArg;

  1038   sqlite3_mutex_leave(db->mutex);

  1039   return pOld;

  1040 }

  1041 #endif /* SQLITE_OMIT_TRACE */

  1042 

  1043 /*** EXPERIMENTAL ***

  1044 **

  1045 ** Register a function to be invoked when a transaction comments.

  1046 ** If the invoked function returns non-zero, then the commit becomes a

  1047 ** rollback.

  1048 */

  1049 SQLITE_EXPORT void *sqlite3_commit_hook(

  1050   sqlite3 *db,              /* Attach the hook to this database */

  1051   int (*xCallback)(void*),  /* Function to invoke on each commit */

  1052   void *pArg                /* Argument to the function */

  1053 ){

  1054   void *pOld;

  1055   sqlite3_mutex_enter(db->mutex);

  1056   pOld = db->pCommitArg;

  1057   db->xCommitCallback = xCallback;

  1058   db->pCommitArg = pArg;

  1059   sqlite3_mutex_leave(db->mutex);

  1060   return pOld;

  1061 }

  1062 

  1063 /*

  1064 ** Register a callback to be invoked each time a row is updated,

  1065 ** inserted or deleted using this database connection.

  1066 */

  1067 SQLITE_EXPORT void *sqlite3_update_hook(

  1068   sqlite3 *db,              /* Attach the hook to this database */

  1069   void (*xCallback)(void*,int,char const *,char const *,sqlite_int64),

  1070   void *pArg                /* Argument to the function */

  1071 ){

  1072   void *pRet;

  1073   sqlite3_mutex_enter(db->mutex);

  1074   pRet = db->pUpdateArg;

  1075   db->xUpdateCallback = xCallback;

  1076   db->pUpdateArg = pArg;

  1077   sqlite3_mutex_leave(db->mutex);

  1078   return pRet;

  1079 }

  1080 

  1081 /*

  1082 ** Register a callback to be invoked each time a transaction is rolled

  1083 ** back by this database connection.

  1084 */

  1085 SQLITE_EXPORT void *sqlite3_rollback_hook(

  1086   sqlite3 *db,              /* Attach the hook to this database */

  1087   void (*xCallback)(void*), /* Callback function */

  1088   void *pArg                /* Argument to the function */

  1089 ){

  1090   void *pRet;

  1091   sqlite3_mutex_enter(db->mutex);

  1092   pRet = db->pRollbackArg;

  1093   db->xRollbackCallback = xCallback;

  1094   db->pRollbackArg = pArg;

  1095   sqlite3_mutex_leave(db->mutex);

  1096   return pRet;

  1097 }

  1098 

  1099 /*

  1100 ** This routine is called to create a connection to a database BTree

  1101 ** driver.  If zFilename is the name of a file, then that file is

  1102 ** opened and used.  If zFilename is the magic name ":memory:" then

  1103 ** the database is stored in memory (and is thus forgotten as soon as

  1104 ** the connection is closed.)  If zFilename is NULL then the database

  1105 ** is a "virtual" database for transient use only and is deleted as

  1106 ** soon as the connection is closed.

  1107 **

  1108 ** A virtual database can be either a disk file (that is automatically

  1109 ** deleted when the file is closed) or it an be held entirely in memory,

  1110 ** depending on the values of the SQLITE_TEMP_STORE compile-time macro and the

  1111 ** db->temp_store variable, according to the following chart:

  1112 **

  1113 **   SQLITE_TEMP_STORE     db->temp_store     Location of temporary database

  1114 **   -----------------     --------------     ------------------------------

  1115 **   0                     any                file

  1116 **   1                     1                  file

  1117 **   1                     2                  memory

  1118 **   1                     0                  file

  1119 **   2                     1                  file

  1120 **   2                     2                  memory

  1121 **   2                     0                  memory

  1122 **   3                     any                memory

  1123 */

  1124 int sqlite3BtreeFactory(

  1125   const sqlite3 *db,        /* Main database when opening aux otherwise 0 */

  1126   const char *zFilename,    /* Name of the file containing the BTree database */

  1127   int omitJournal,          /* if TRUE then do not journal this file */

  1128   int nCache,               /* How many pages in the page cache */

  1129   int vfsFlags,             /* Flags passed through to vfsOpen */

  1130   Btree **ppBtree           /* Pointer to new Btree object written here */

  1131 ){

  1132   int btFlags = 0;

  1133   int rc;

  1134   

  1135   assert( sqlite3_mutex_held(db->mutex) );