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.508 2008/10/12 00:27:53 shane 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 const char *sqlite3_libversion(void){ return sqlite3_version; }

    37 int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }

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

   139   if( rc==SQLITE_OK ){

   140     sqlite3GlobalConfig.nRefInitMutex++;

   141   }

   142   sqlite3_mutex_leave(pMaster);

   143 

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

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

   146   ** subsystem cannot be initialized.

   147   */

   148   if( rc!=SQLITE_OK ){

   149     return rc;

   150   }

   151 

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

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

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

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

   156   ** recursive calls might also be possible.

   157   */

   158   sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex);

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

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

   161     sqlite3GlobalConfig.inProgress = 1;

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

   163     sqlite3RegisterGlobalFunctions();

   164     rc = sqlite3_os_init();

   165     if( rc==SQLITE_OK ){

   166       rc = sqlite3PcacheInitialize();

   167       sqlite3PCacheBufferSetup( sqlite3GlobalConfig.pPage, 

   168           sqlite3GlobalConfig.szPage, sqlite3GlobalConfig.nPage);

   169     }

   170     sqlite3GlobalConfig.inProgress = 0;

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

   172   }

   173   sqlite3_mutex_leave(sqlite3GlobalConfig.pInitMutex);

   174 

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

   176   ** mutex to prevent a resource leak.

   177   */

   178   sqlite3_mutex_enter(pMaster);

   179   sqlite3GlobalConfig.nRefInitMutex--;

   180   if( sqlite3GlobalConfig.nRefInitMutex<=0 ){

   181     assert( sqlite3GlobalConfig.nRefInitMutex==0 );

   182     sqlite3_mutex_free(sqlite3GlobalConfig.pInitMutex);

   183     sqlite3GlobalConfig.pInitMutex = 0;

   184   }

   185   sqlite3_mutex_leave(pMaster);

   186 

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

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

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

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

   191   */

   192 #ifndef NDEBUG

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

   194   if ( rc==SQLITE_OK ){

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

   196     double y;

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

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

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

   200     assert( sqlite3IsNaN(y) );

   201   }

   202 #endif

   203 

   204   return rc;

   205 }

   206 

   207 /*

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

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

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

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

   212 */

   213 int sqlite3_shutdown(void){

   214   sqlite3GlobalConfig.isMallocInit = 0;

   215   sqlite3PcacheShutdown();

   216   if( sqlite3GlobalConfig.isInit ){

   217     sqlite3_os_end();

   218   }

   219   sqlite3MallocEnd();

   220   sqlite3MutexEnd();

   221   sqlite3GlobalConfig.isInit = 0;

   222   return SQLITE_OK;

   223 }

   224 

   225 /*

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

   227 ** the SQLite library at run-time.

   228 **

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

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

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

   232 ** behavior.

   233 */

   234 int sqlite3_config(int op, ...){

   235   va_list ap;

   236   int rc = SQLITE_OK;

   237 

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

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

   240   if( sqlite3GlobalConfig.isInit ) return SQLITE_MISUSE;

   241 

   242   va_start(ap, op);

   243   switch( op ){

   244 

   245     /* Mutex configuration options are only available in a threadsafe

   246     ** compile. 

   247     */

   248 #if SQLITE_THREADSAFE

   249     case SQLITE_CONFIG_SINGLETHREAD: {

   250       /* Disable all mutexing */

   251       sqlite3GlobalConfig.bCoreMutex = 0;

   252       sqlite3GlobalConfig.bFullMutex = 0;

   253       break;

   254     }

   255     case SQLITE_CONFIG_MULTITHREAD: {

   256       /* Disable mutexing of database connections */

   257       /* Enable mutexing of core data structures */

   258       sqlite3GlobalConfig.bCoreMutex = 1;

   259       sqlite3GlobalConfig.bFullMutex = 0;

   260       break;

   261     }

   262     case SQLITE_CONFIG_SERIALIZED: {

   263       /* Enable all mutexing */

   264       sqlite3GlobalConfig.bCoreMutex = 1;

   265       sqlite3GlobalConfig.bFullMutex = 1;

   266       break;

   267     }

   268     case SQLITE_CONFIG_MUTEX: {

   269       /* Specify an alternative mutex implementation */

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

   271       break;

   272     }

   273     case SQLITE_CONFIG_GETMUTEX: {

   274       /* Retrieve the current mutex implementation */

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

   276       break;

   277     }

   278 #endif

   279 

   280 

   281     case SQLITE_CONFIG_MALLOC: {

   282       /* Specify an alternative malloc implementation */

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

   284       break;

   285     }

   286     case SQLITE_CONFIG_GETMALLOC: {

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

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

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

   290       break;

   291     }

   292     case SQLITE_CONFIG_MEMSTATUS: {

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

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

   295       break;

   296     }

   297     case SQLITE_CONFIG_SCRATCH: {

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

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

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

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

   302       break;

   303     }

   304     case SQLITE_CONFIG_PAGECACHE: {

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

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

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

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

   309       break;

   310     }

   311 

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

   313     case SQLITE_CONFIG_HEAP: {

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

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

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

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

   318 

   319       if( sqlite3GlobalConfig.pHeap==0 ){

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

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

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

   323         ** run.

   324         */

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

   326       }else{

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

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

   329         ** ENABLE_MEMSYS5 is defined, return an error.

   330         ** the default case and return an error.

   331         */

   332 #ifdef SQLITE_ENABLE_MEMSYS3

   333         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys3();

   334 #endif

   335 #ifdef SQLITE_ENABLE_MEMSYS5

   336         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys5();

   337 #endif

   338       }

   339       break;

   340     }

   341 #endif

   342 

   343 #if defined(SQLITE_ENABLE_MEMSYS6)

   344     case SQLITE_CONFIG_CHUNKALLOC: {

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

   346       sqlite3GlobalConfig.m = *sqlite3MemGetMemsys6();

   347       break;

   348     }

   349 #endif

   350 

   351     case SQLITE_CONFIG_LOOKASIDE: {

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

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

   354       break;

   355     }

   356 

   357     default: {

   358       rc = SQLITE_ERROR;

   359       break;

   360     }

   361   }

   362   va_end(ap);

   363   return rc;

   364 }

   365 

   366 /*

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

   368 ** Return SQLITE_OK on success.  

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

   370 **

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

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

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

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

   375 ** the lookaside memory.

   376 */

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

   378   void *pStart;

   379   if( db->lookaside.nOut ){

   380     return SQLITE_BUSY;

   381   }

   382   if( sz<0 ) sz = 0;

   383   if( cnt<0 ) cnt = 0;

   384   if( pBuf==0 ){

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

   386     sqlite3BeginBenignMalloc();

   387     pStart = sqlite3Malloc( sz*cnt );

   388     sqlite3EndBenignMalloc();

   389   }else{

   390     sz = sz&~7;

   391     pStart = pBuf;

   392   }

   393   if( db->lookaside.bMalloced ){

   394     sqlite3_free(db->lookaside.pStart);

   395   }

   396   db->lookaside.pStart = pStart;

   397   db->lookaside.pFree = 0;

   398   db->lookaside.sz = sz;

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

   400   if( pStart ){

   401     int i;

   402     LookasideSlot *p;

   403     p = (LookasideSlot*)pStart;

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

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

   406       db->lookaside.pFree = p;

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

   408     }

   409     db->lookaside.pEnd = p;

   410     db->lookaside.bEnabled = 1;

   411   }else{

   412     db->lookaside.pEnd = 0;

   413     db->lookaside.bEnabled = 0;

   414   }

   415   return SQLITE_OK;

   416 }

   417 

   418 /*

   419 ** Configuration settings for an individual database connection

   420 */

   421 int sqlite3_db_config(sqlite3 *db, int op, ...){

   422   va_list ap;

   423   int rc;

   424   va_start(ap, op);

   425   switch( op ){

   426     case SQLITE_DBCONFIG_LOOKASIDE: {

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

   428       int sz = va_arg(ap, int);

   429       int cnt = va_arg(ap, int);

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

   431       break;

   432     }

   433     default: {

   434       rc = SQLITE_ERROR;

   435       break;

   436     }

   437   }

   438   va_end(ap);

   439   return rc;

   440 }

   441 

   442 /*

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

   444 */

   445 #ifdef SQLITE_COVERAGE_TEST

   446 void sqlite3Coverage(int x){

   447   static int dummy = 0;

   448   dummy += x;

   449 }

   450 #endif

   451 

   452 

   453 /*

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

   455 */

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

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

   458   return n==0;

   459 }

   460 

   461 /*

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

   463 ** available.

   464 **

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

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

   467 */

   468 static int binCollFunc(

   469   void *padFlag,

   470   int nKey1, const void *pKey1,

   471   int nKey2, const void *pKey2

   472 ){

   473   int rc, n;

   474   n = nKey1<nKey2 ? nKey1 : nKey2;

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

   476   if( rc==0 ){

   477     if( padFlag

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

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

   480     ){

   481       /* Leave rc unchanged at 0 */

   482     }else{

   483       rc = nKey1 - nKey2;

   484     }

   485   }

   486   return rc;

   487 }

   488 

   489 /*

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

   491 **

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

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

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

   495 **

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

   497 */

   498 static int nocaseCollatingFunc(

   499   void *NotUsed,

   500   int nKey1, const void *pKey1,

   501   int nKey2, const void *pKey2

   502 ){

   503   int r = sqlite3StrNICmp(

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

   505   if( 0==r ){

   506     r = nKey1-nKey2;

   507   }

   508   return r;

   509 }

   510 

   511 /*

   512 ** Return the ROWID of the most recent insert

   513 */

   514 sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){

   515   return db->lastRowid;

   516 }

   517 

   518 /*

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

   520 */

   521 int sqlite3_changes(sqlite3 *db){

   522   return db->nChange;

   523 }

   524 

   525 /*

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

   527 */

   528 int sqlite3_total_changes(sqlite3 *db){

   529   return db->nTotalChange;

   530 }

   531 

   532 /*

   533 ** Close an existing SQLite database

   534 */

   535 int sqlite3_close(sqlite3 *db){

   536   HashElem *i;

   537   int j;

   538 

   539   if( !db ){

   540     return SQLITE_OK;

   541   }

   542   if( !sqlite3SafetyCheckSickOrOk(db) ){

   543     return SQLITE_MISUSE;

   544   }

   545   sqlite3_mutex_enter(db->mutex);

   546 

   547 #ifdef SQLITE_SSE

   548   {

   549     extern void sqlite3SseCleanup(sqlite3*);

   550     sqlite3SseCleanup(db);

   551   }

   552 #endif 

   553 

   554   sqlite3ResetInternalSchema(db, 0);

   555 

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

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

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

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

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

   561   ** some prepared statements internally.

   562   */

   563   sqlite3VtabRollback(db);

   564 

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

   566   if( db->pVdbe ){

   567     sqlite3Error(db, SQLITE_BUSY, 

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

   569     sqlite3_mutex_leave(db->mutex);

   570     return SQLITE_BUSY;

   571   }

   572   assert( sqlite3SafetyCheckSickOrOk(db) );

   573 

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

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

   576     if( pDb->pBt ){

   577       sqlite3BtreeClose(pDb->pBt);

   578       pDb->pBt = 0;

   579       if( j!=1 ){

   580         pDb->pSchema = 0;

   581       }

   582     }

   583   }

   584   sqlite3ResetInternalSchema(db, 0);

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

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

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

   588     FuncDef *pNext, *pHash, *p;

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

   590       pHash = p->pHash;

   591       while( p ){

   592         pNext = p->pNext;

   593         sqlite3DbFree(db, p);

   594         p = pNext;

   595       }

   596     }

   597   }

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

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

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

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

   602       if( pColl[j].xDel ){

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

   604       }

   605     }

   606     sqlite3DbFree(db, pColl);

   607   }

   608   sqlite3HashClear(&db->aCollSeq);

   609 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

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

   612     if( pMod->xDestroy ){

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

   614     }

   615     sqlite3DbFree(db, pMod);

   616   }

   617   sqlite3HashClear(&db->aModule);

   618 #endif

   619 

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

   621   if( db->pErr ){

   622     sqlite3ValueFree(db->pErr);

   623   }

   624   sqlite3CloseExtensions(db);

   625 

   626   db->magic = SQLITE_MAGIC_ERROR;

   627 

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

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

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

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

   632   ** structure?

   633   */

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

   635   sqlite3_mutex_leave(db->mutex);

   636   db->magic = SQLITE_MAGIC_CLOSED;

   637   sqlite3_mutex_free(db->mutex);

   638   assert( db->lookaside.nOut==0 );  /* Fails on a lookaside memory leak */

   639   if( db->lookaside.bMalloced ){

   640     sqlite3_free(db->lookaside.pStart);

   641   }

   642   sqlite3_free(db);

   643   return SQLITE_OK;

   644 }

   645 

   646 /*

   647 ** Rollback all database files.

   648 */

   649 void sqlite3RollbackAll(sqlite3 *db){

   650   int i;

   651   int inTrans = 0;

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

   653   sqlite3BeginBenignMalloc();

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

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

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

   657         inTrans = 1;

   658       }

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

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

   661     }

   662   }

   663   sqlite3VtabRollback(db);

   664   sqlite3EndBenignMalloc();

   665 

   666   if( db->flags&SQLITE_InternChanges ){

   667     sqlite3ExpirePreparedStatements(db);

   668     sqlite3ResetInternalSchema(db, 0);

   669   }

   670 

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

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

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

   674   }

   675 }

   676 

   677 /*

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

   679 ** argument.

   680 */

   681 const char *sqlite3ErrStr(int rc){

   682   const char *z;

   683   switch( rc & 0xff ){

   684     case SQLITE_ROW:

   685     case SQLITE_DONE:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   711   }

   712   return z;

   713 }

   714 

   715 /*

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

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

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

   719 ** argument.

   720 */

   721 static int sqliteDefaultBusyCallback(

   722  void *ptr,               /* Database connection */

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

   724 ){

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

   726   static const u8 delays[] =

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

   728   static const u8 totals[] =

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

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

   731   sqlite3 *db = (sqlite3 *)ptr;

   732   int timeout = db->busyTimeout;

   733   int delay, prior;

   734 

   735   assert( count>=0 );

   736   if( count < NDELAY ){

   737     delay = delays[count];

   738     prior = totals[count];

   739   }else{

   740     delay = delays[NDELAY-1];

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

   742   }

   743   if( prior + delay > timeout ){

   744     delay = timeout - prior;

   745     if( delay<=0 ) return 0;

   746   }

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

   748   return 1;

   749 #else

   750   sqlite3 *db = (sqlite3 *)ptr;

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

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

   753     return 0;

   754   }

   755   sqlite3OsSleep(db->pVfs, 1000000);

   756   return 1;

   757 #endif

   758 }

   759 

   760 /*

   761 ** Invoke the given busy handler.

   762 **

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

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

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

   766 */

   767 int sqlite3InvokeBusyHandler(BusyHandler *p){

   768   int rc;

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

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

   771   if( rc==0 ){

   772     p->nBusy = -1;

   773   }else{

   774     p->nBusy++;

   775   }

   776   return rc; 

   777 }

   778 

   779 /*

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

   781 ** given callback function with the given argument.

   782 */

   783 int sqlite3_busy_handler(

   784   sqlite3 *db,

   785   int (*xBusy)(void*,int),

   786   void *pArg

   787 ){

   788   sqlite3_mutex_enter(db->mutex);

   789   db->busyHandler.xFunc = xBusy;

   790   db->busyHandler.pArg = pArg;

   791   db->busyHandler.nBusy = 0;

   792   sqlite3_mutex_leave(db->mutex);

   793   return SQLITE_OK;

   794 }

   795 

   796 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

   797 /*

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

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

   800 ** be invoked every nOps opcodes.

   801 */

   802 void sqlite3_progress_handler(

   803   sqlite3 *db, 

   804   int nOps,

   805   int (*xProgress)(void*), 

   806   void *pArg

   807 ){

   808   sqlite3_mutex_enter(db->mutex);

   809   if( nOps>0 ){

   810     db->xProgress = xProgress;

   811     db->nProgressOps = nOps;

   812     db->pProgressArg = pArg;

   813   }else{

   814     db->xProgress = 0;

   815     db->nProgressOps = 0;

   816     db->pProgressArg = 0;

   817   }

   818   sqlite3_mutex_leave(db->mutex);

   819 }

   820 #endif

   821 

   822 

   823 /*

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

   825 ** specified number of milliseconds before returning 0.

   826 */

   827 int sqlite3_busy_timeout(sqlite3 *db, int ms){

   828   if( ms>0 ){

   829     db->busyTimeout = ms;

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

   831   }else{

   832     sqlite3_busy_handler(db, 0, 0);

   833   }

   834   return SQLITE_OK;

   835 }

   836 

   837 /*

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

   839 */

   840 void sqlite3_interrupt(sqlite3 *db){

   841   db->u1.isInterrupted = 1;

   842 }

   843 

   844 

   845 /*

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

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

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

   849 ** is returned and the mallocFailed flag cleared. 

   850 */

   851 int sqlite3CreateFunc(

   852   sqlite3 *db,

   853   const char *zFunctionName,

   854   int nArg,

   855   int enc,

   856   void *pUserData,

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

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

   859   void (*xFinal)(sqlite3_context*)

   860 ){

   861   FuncDef *p;

   862   int nName;

   863 

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

   865   if( zFunctionName==0 ||

   866       (xFunc && (xFinal || xStep)) || 

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

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

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

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

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

   872     return SQLITE_ERROR;

   873   }

   874   

   875 #ifndef SQLITE_OMIT_UTF16

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

   877   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

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

   879   **

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

   881   ** to the hash table.

   882   */

   883   if( enc==SQLITE_UTF16 ){

   884     enc = SQLITE_UTF16NATIVE;

   885   }else if( enc==SQLITE_ANY ){

   886     int rc;

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

   888          pUserData, xFunc, xStep, xFinal);

   889     if( rc==SQLITE_OK ){

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

   891           pUserData, xFunc, xStep, xFinal);

   892     }

   893     if( rc!=SQLITE_OK ){

   894       return rc;

   895     }

   896     enc = SQLITE_UTF16BE;

   897   }

   898 #else

   899   enc = SQLITE_UTF8;

   900 #endif

   901   

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

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

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

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

   906   */

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

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

   909     if( db->activeVdbeCnt ){

   910       sqlite3Error(db, SQLITE_BUSY, 

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

   912       assert( !db->mallocFailed );

   913       return SQLITE_BUSY;

   914     }else{

   915       sqlite3ExpirePreparedStatements(db);

   916     }

   917   }

   918 

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

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

   921   if( !p ){

   922     return SQLITE_NOMEM;

   923   }

   924   p->flags = 0;

   925   p->xFunc = xFunc;

   926   p->xStep = xStep;

   927   p->xFinalize = xFinal;

   928   p->pUserData = pUserData;

   929   p->nArg = nArg;

   930   return SQLITE_OK;

   931 }

   932 

   933 /*

   934 ** Create new user functions.

   935 */

   936 int sqlite3_create_function(

   937   sqlite3 *db,

   938   const char *zFunctionName,

   939   int nArg,

   940   int enc,

   941   void *p,

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

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

   944   void (*xFinal)(sqlite3_context*)

   945 ){

   946   int rc;

   947   sqlite3_mutex_enter(db->mutex);

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

   949   rc = sqlite3ApiExit(db, rc);

   950   sqlite3_mutex_leave(db->mutex);

   951   return rc;

   952 }

   953 

   954 #ifndef SQLITE_OMIT_UTF16

   955 int sqlite3_create_function16(

   956   sqlite3 *db,

   957   const void *zFunctionName,

   958   int nArg,

   959   int eTextRep,

   960   void *p,

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

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

   963   void (*xFinal)(sqlite3_context*)

   964 ){

   965   int rc;

   966   char *zFunc8;

   967   sqlite3_mutex_enter(db->mutex);

   968   assert( !db->mallocFailed );

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

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

   971   sqlite3DbFree(db, zFunc8);

   972   rc = sqlite3ApiExit(db, rc);

   973   sqlite3_mutex_leave(db->mutex);

   974   return rc;

   975 }

   976 #endif

   977 

   978 

   979 /*

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

   981 **

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

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

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

   985 **

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

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

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

   989 ** properly.

   990 */

   991 int sqlite3_overload_function(

   992   sqlite3 *db,

   993   const char *zName,

   994   int nArg

   995 ){

   996   int nName = sqlite3Strlen(db, zName);

   997   int rc;

   998   sqlite3_mutex_enter(db->mutex);

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

  1000     sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,

  1001                       0, sqlite3InvalidFunction, 0, 0);

  1002   }

  1003   rc = sqlite3ApiExit(db, SQLITE_OK);

  1004   sqlite3_mutex_leave(db->mutex);

  1005   return rc;

  1006 }

  1007 

  1008 #ifndef SQLITE_OMIT_TRACE

  1009 /*

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

  1011 ** is returned.  

  1012 **

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

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

  1015 ** SQL statement.

  1016 */

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

  1018   void *pOld;

  1019   sqlite3_mutex_enter(db->mutex);

  1020   pOld = db->pTraceArg;

  1021   db->xTrace = xTrace;

  1022   db->pTraceArg = pArg;

  1023   sqlite3_mutex_leave(db->mutex);

  1024   return pOld;

  1025 }

  1026 /*

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

  1028 ** profile function is returned.  

  1029 **

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

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

  1032 ** each SQL statement that is run.

  1033 */

  1034 void *sqlite3_profile(

  1035   sqlite3 *db,

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

  1037   void *pArg

  1038 ){

  1039   void *pOld;

  1040   sqlite3_mutex_enter(db->mutex);

  1041   pOld = db->pProfileArg;

  1042   db->xProfile = xProfile;

  1043   db->pProfileArg = pArg;

  1044   sqlite3_mutex_leave(db->mutex);

  1045   return pOld;

  1046 }

  1047 #endif /* SQLITE_OMIT_TRACE */

  1048 

  1049 /*** EXPERIMENTAL ***

  1050 **

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

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

  1053 ** rollback.

  1054 */

  1055 void *sqlite3_commit_hook(

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

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

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

  1059 ){

  1060   void *pOld;

  1061   sqlite3_mutex_enter(db->mutex);

  1062   pOld = db->pCommitArg;

  1063   db->xCommitCallback = xCallback;

  1064   db->pCommitArg = pArg;

  1065   sqlite3_mutex_leave(db->mutex);

  1066   return pOld;

  1067 }

  1068 

  1069 /*

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

  1071 ** inserted or deleted using this database connection.

  1072 */

  1073 void *sqlite3_update_hook(

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

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

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

  1077 ){

  1078   void *pRet;

  1079   sqlite3_mutex_enter(db->mutex);

  1080   pRet = db->pUpdateArg;

  1081   db->xUpdateCallback = xCallback;

  1082   db->pUpdateArg = pArg;

  1083   sqlite3_mutex_leave(db->mutex);

  1084   return pRet;

  1085 }

  1086 

  1087 /*

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

  1089 ** back by this database connection.

  1090 */

  1091 void *sqlite3_rollback_hook(

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

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

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

  1095 ){

  1096   void *pRet;

  1097   sqlite3_mutex_enter(db->mutex);

  1098   pRet = db->pRollbackArg;

  1099   db->xRollbackCallback = xCallback;

  1100   db->pRollbackArg = pArg;

  1101   sqlite3_mutex_leave(db->mutex);

  1102   return pRet;

  1103 }

  1104 

  1105 /*

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

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

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

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

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

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

  1112 ** soon as the connection is closed.

  1113 **

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

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

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

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

  1118 **

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

  1120 **   -----------------     --------------     ------------------------------

  1121 **   0                     any                file

  1122 **   1                     1                  file

  1123 **   1                     2                  memory

  1124 **   1                     0                  file

  1125 **   2                     1                  file

  1126 **   2                     2                  memory

  1127 **   2                     0                  memory

  1128 **   3                     any                memory

  1129 */

  1130 int sqlite3BtreeFactory(

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

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

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

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