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.486 2008/08/04 20:13:27 drh 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 

    29 /*

    30 ** The version of the library

    31 */

    32 const char sqlite3_version[] = SQLITE_VERSION;

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

    34 int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }

    35 int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE; }

    36 

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

    38 /*

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

    40 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing

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

    42 ** are intended for debugging activity only.

    43 */

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

    45 #endif

    46 

    47 /*

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

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

    50 ** temporary files.

    51 **

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

    53 */

    54 char *sqlite3_temp_directory = 0;

    55 

    56 /*

    57 ** Initialize SQLite.  

    58 **

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

    60 ** VFS, and mutex subsystesms prior to doing any serious work with

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

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

    63 ** sqlite3_open().  

    64 **

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

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

    67 */

    68 int sqlite3_initialize(void){

    69   static int inProgress = 0;

    70   int rc;

    71 

    72   /* If SQLite is already initialized, this call is a no-op. */

    73   if( sqlite3Config.isInit ) return SQLITE_OK;

    74 

    75   /* Make sure the mutex system is initialized. */

    76   rc = sqlite3MutexInit();

    77 

    78   if( rc==SQLITE_OK ){

    79 

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

    81     ** This operation is protected by the STATIC_MASTER mutex.

    82     */

    83     sqlite3_mutex *pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);

    84     sqlite3_mutex_enter(pMaster);

    85     if( !sqlite3Config.isMallocInit ){

    86       rc = sqlite3MallocInit();

    87     }

    88     if( rc==SQLITE_OK ){

    89       sqlite3Config.isMallocInit = 1;

    90       if( !sqlite3Config.pInitMutex ){

    91         sqlite3Config.pInitMutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);

    92         if( sqlite3Config.bCoreMutex && !sqlite3Config.pInitMutex ){

    93           rc = SQLITE_NOMEM;

    94         }

    95       }

    96     }

    97     sqlite3_mutex_leave(pMaster);

    98     if( rc!=SQLITE_OK ){

    99       return rc;

   100     }

   101 

   102     /* Enter the recursive pInitMutex mutex. After doing so, if the

   103     ** sqlite3Config.isInit flag is true, then some other thread has

   104     ** finished doing the initialization. If the inProgress flag is

   105     ** true, then this function is being called recursively from within

   106     ** the sqlite3_os_init() call below. In either case, exit early.

   107     */

   108     sqlite3_mutex_enter(sqlite3Config.pInitMutex);

   109     if( sqlite3Config.isInit || inProgress ){

   110       sqlite3_mutex_leave(sqlite3Config.pInitMutex);

   111       return SQLITE_OK;

   112     }

   113     sqlite3StatusReset();

   114     inProgress = 1;

   115     rc = sqlite3_os_init();

   116     inProgress = 0;

   117     sqlite3Config.isInit = (rc==SQLITE_OK ? 1 : 0);

   118     sqlite3_mutex_leave(sqlite3Config.pInitMutex);

   119   }

   120 

   121   /* Check NaN support. */

   122 #ifndef NDEBUG

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

   124   if ( rc==SQLITE_OK ){

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

   126     double y;

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

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

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

   130     assert( sqlite3IsNaN(y) );

   131   }

   132 #endif

   133 

   134   return rc;

   135 }

   136 

   137 /*

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

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

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

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

   142 */

   143 int sqlite3_shutdown(void){

   144   sqlite3_mutex_free(sqlite3Config.pInitMutex);

   145   sqlite3Config.pInitMutex = 0;

   146   sqlite3Config.isMallocInit = 0;

   147   if( sqlite3Config.isInit ){

   148     sqlite3_os_end();

   149   }

   150   if( sqlite3Config.m.xShutdown ){

   151     sqlite3MallocEnd();

   152   }

   153   if( sqlite3Config.mutex.xMutexEnd ){

   154     sqlite3MutexEnd();

   155   }

   156   sqlite3Config.isInit = 0;

   157   return SQLITE_OK;

   158 }

   159 

   160 /*

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

   162 ** the SQLite library at run-time.

   163 **

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

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

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

   167 ** behavior.

   168 */

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

   170   va_list ap;

   171   int rc = SQLITE_OK;

   172 

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

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

   175   if( sqlite3Config.isInit ) return SQLITE_MISUSE;

   176 

   177   va_start(ap, op);

   178   switch( op ){

   179     case SQLITE_CONFIG_SINGLETHREAD: {

   180       /* Disable all mutexing */

   181       sqlite3Config.bCoreMutex = 0;

   182       sqlite3Config.bFullMutex = 0;

   183       break;

   184     }

   185     case SQLITE_CONFIG_MULTITHREAD: {

   186       /* Disable mutexing of database connections */

   187       /* Enable mutexing of core data structures */

   188       sqlite3Config.bCoreMutex = 1;

   189       sqlite3Config.bFullMutex = 0;

   190       break;

   191     }

   192     case SQLITE_CONFIG_SERIALIZED: {

   193       /* Enable all mutexing */

   194       sqlite3Config.bCoreMutex = 1;

   195       sqlite3Config.bFullMutex = 1;

   196       break;

   197     }

   198     case SQLITE_CONFIG_MALLOC: {

   199       /* Specify an alternative malloc implementation */

   200       sqlite3Config.m = *va_arg(ap, sqlite3_mem_methods*);

   201       break;

   202     }

   203     case SQLITE_CONFIG_GETMALLOC: {

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

   205       if( sqlite3Config.m.xMalloc==0 ) sqlite3MemSetDefault();

   206       *va_arg(ap, sqlite3_mem_methods*) = sqlite3Config.m;

   207       break;

   208     }

   209     case SQLITE_CONFIG_MUTEX: {

   210       /* Specify an alternative mutex implementation */

   211       sqlite3Config.mutex = *va_arg(ap, sqlite3_mutex_methods*);

   212       break;

   213     }

   214     case SQLITE_CONFIG_GETMUTEX: {

   215       /* Retrieve the current mutex implementation */

   216       *va_arg(ap, sqlite3_mutex_methods*) = sqlite3Config.mutex;

   217       break;

   218     }

   219     case SQLITE_CONFIG_MEMSTATUS: {

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

   221       sqlite3Config.bMemstat = va_arg(ap, int);

   222       break;

   223     }

   224     case SQLITE_CONFIG_SCRATCH: {

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

   226       sqlite3Config.pScratch = va_arg(ap, void*);

   227       sqlite3Config.szScratch = va_arg(ap, int);

   228       sqlite3Config.nScratch = va_arg(ap, int);

   229       break;

   230     }

   231     case SQLITE_CONFIG_PAGECACHE: {

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

   233       sqlite3Config.pPage = va_arg(ap, void*);

   234       sqlite3Config.szPage = va_arg(ap, int);

   235       sqlite3Config.nPage = va_arg(ap, int);

   236       break;

   237     }

   238 

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

   240     case SQLITE_CONFIG_HEAP: {

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

   242       sqlite3Config.pHeap = va_arg(ap, void*);

   243       sqlite3Config.nHeap = va_arg(ap, int);

   244       sqlite3Config.mnReq = va_arg(ap, int);

   245 

   246       if( sqlite3Config.pHeap==0 ){

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

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

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

   250         ** run.

   251         */

   252         memset(&sqlite3Config.m, 0, sizeof(sqlite3Config.m));

   253       }else{

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

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

   256         ** ENABLE_MEMSYS5 is defined, return an error.

   257         ** the default case and return an error.

   258         */

   259 #ifdef SQLITE_ENABLE_MEMSYS3

   260         sqlite3Config.m = *sqlite3MemGetMemsys3();

   261 #endif

   262 #ifdef SQLITE_ENABLE_MEMSYS5

   263         sqlite3Config.m = *sqlite3MemGetMemsys5();

   264 #endif

   265       }

   266       break;

   267     }

   268 #endif

   269 

   270 #if defined(SQLITE_ENABLE_MEMSYS6)

   271     case SQLITE_CONFIG_CHUNKALLOC: {

   272       sqlite3Config.nSmall = va_arg(ap, int);

   273       sqlite3Config.m = *sqlite3MemGetMemsys6();

   274       break;

   275     }

   276 #endif

   277 

   278     case SQLITE_CONFIG_LOOKASIDE: {

   279       sqlite3Config.szLookaside = va_arg(ap, int);

   280       sqlite3Config.nLookaside = va_arg(ap, int);

   281       break;

   282     }

   283 

   284     default: {

   285       rc = SQLITE_ERROR;

   286       break;

   287     }

   288   }

   289   va_end(ap);

   290   return rc;

   291 }

   292 

   293 /*

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

   295 ** Return SQLITE_OK on success.  

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

   297 **

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

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

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

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

   302 ** the lookaside memory.

   303 */

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

   305   void *pStart;

   306   if( db->lookaside.nOut ){

   307     return SQLITE_BUSY;

   308   }

   309   if( sz<0 ) sz = 0;

   310   if( cnt<0 ) cnt = 0;

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

   312   if( pBuf==0 ){

   313     sqlite3BeginBenignMalloc();

   314     pStart = sqlite3Malloc( sz*cnt );

   315     sqlite3EndBenignMalloc();

   316   }else{

   317     pStart = pBuf;

   318   }

   319   if( db->lookaside.bMalloced ){

   320     sqlite3_free(db->lookaside.pStart);

   321   }

   322   db->lookaside.pStart = pStart;

   323   db->lookaside.pFree = 0;

   324   db->lookaside.sz = sz;

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

   326   if( pStart ){

   327     int i;

   328     LookasideSlot *p;

   329     p = (LookasideSlot*)pStart;

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

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

   332       db->lookaside.pFree = p;

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

   334     }

   335     db->lookaside.pEnd = p;

   336     db->lookaside.bEnabled = 1;

   337   }else{

   338     db->lookaside.pEnd = 0;

   339     db->lookaside.bEnabled = 0;

   340   }

   341   return SQLITE_OK;

   342 }

   343 

   344 /*

   345 ** Configuration settings for an individual database connection

   346 */

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

   348   va_list ap;

   349   int rc;

   350   va_start(ap, op);

   351   switch( op ){

   352     case SQLITE_DBCONFIG_LOOKASIDE: {

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

   354       int sz = va_arg(ap, int);

   355       int cnt = va_arg(ap, int);

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

   357       break;

   358     }

   359     default: {

   360       rc = SQLITE_ERROR;

   361       break;

   362     }

   363   }

   364   va_end(ap);

   365   return rc;

   366 }

   367 

   368 /*

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

   370 */

   371 #ifdef SQLITE_COVERAGE_TEST

   372 void sqlite3Coverage(int x){

   373   static int dummy = 0;

   374   dummy += x;

   375 }

   376 #endif

   377 

   378 

   379 /*

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

   381 */

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

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

   384   return n==0;

   385 }

   386 

   387 /*

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

   389 ** available.

   390 **

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

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

   393 */

   394 static int binCollFunc(

   395   void *padFlag,

   396   int nKey1, const void *pKey1,

   397   int nKey2, const void *pKey2

   398 ){

   399   int rc, n;

   400   n = nKey1<nKey2 ? nKey1 : nKey2;

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

   402   if( rc==0 ){

   403     if( padFlag

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

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

   406     ){

   407       /* Leave rc unchanged at 0 */

   408     }else{

   409       rc = nKey1 - nKey2;

   410     }

   411   }

   412   return rc;

   413 }

   414 

   415 /*

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

   417 **

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

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

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

   421 **

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

   423 */

   424 static int nocaseCollatingFunc(

   425   void *NotUsed,

   426   int nKey1, const void *pKey1,

   427   int nKey2, const void *pKey2

   428 ){

   429   int r = sqlite3StrNICmp(

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

   431   if( 0==r ){

   432     r = nKey1-nKey2;

   433   }

   434   return r;

   435 }

   436 

   437 /*

   438 ** Return the ROWID of the most recent insert

   439 */

   440 sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){

   441   return db->lastRowid;

   442 }

   443 

   444 /*

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

   446 */

   447 int sqlite3_changes(sqlite3 *db){

   448   return db->nChange;

   449 }

   450 

   451 /*

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

   453 */

   454 int sqlite3_total_changes(sqlite3 *db){

   455   return db->nTotalChange;

   456 }

   457 

   458 /*

   459 ** Close an existing SQLite database

   460 */

   461 int sqlite3_close(sqlite3 *db){

   462   HashElem *i;

   463   int j;

   464 

   465   if( !db ){

   466     return SQLITE_OK;

   467   }

   468   if( !sqlite3SafetyCheckSickOrOk(db) ){

   469     return SQLITE_MISUSE;

   470   }

   471   sqlite3_mutex_enter(db->mutex);

   472 

   473 #ifdef SQLITE_SSE

   474   {

   475     extern void sqlite3SseCleanup(sqlite3*);

   476     sqlite3SseCleanup(db);

   477   }

   478 #endif 

   479 

   480   sqlite3ResetInternalSchema(db, 0);

   481 

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

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

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

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

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

   487   ** some prepared statements internally.

   488   */

   489   sqlite3VtabRollback(db);

   490 

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

   492   if( db->pVdbe ){

   493     sqlite3Error(db, SQLITE_BUSY, 

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

   495     sqlite3_mutex_leave(db->mutex);

   496     return SQLITE_BUSY;

   497   }

   498   assert( sqlite3SafetyCheckSickOrOk(db) );

   499 

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

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

   502     if( pDb->pBt ){

   503       sqlite3BtreeClose(pDb->pBt);

   504       pDb->pBt = 0;

   505       if( j!=1 ){

   506         pDb->pSchema = 0;

   507       }

   508     }

   509   }

   510   sqlite3ResetInternalSchema(db, 0);

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

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

   513   for(i=sqliteHashFirst(&db->aFunc); i; i=sqliteHashNext(i)){

   514     FuncDef *pFunc, *pNext;

   515     for(pFunc = (FuncDef*)sqliteHashData(i); pFunc; pFunc=pNext){

   516       pNext = pFunc->pNext;

   517       sqlite3DbFree(db, pFunc);

   518     }

   519   }

   520 

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

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

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

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

   525       if( pColl[j].xDel ){

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

   527       }

   528     }

   529     sqlite3DbFree(db, pColl);

   530   }

   531   sqlite3HashClear(&db->aCollSeq);

   532 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

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

   535     if( pMod->xDestroy ){

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

   537     }

   538     sqlite3DbFree(db, pMod);

   539   }

   540   sqlite3HashClear(&db->aModule);

   541 #endif

   542 

   543   sqlite3HashClear(&db->aFunc);

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

   545   if( db->pErr ){

   546     sqlite3ValueFree(db->pErr);

   547   }

   548   sqlite3CloseExtensions(db);

   549 

   550   db->magic = SQLITE_MAGIC_ERROR;

   551 

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

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

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

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

   556   ** structure?

   557   */

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

   559   sqlite3_mutex_leave(db->mutex);

   560   db->magic = SQLITE_MAGIC_CLOSED;

   561   sqlite3_mutex_free(db->mutex);

   562   if( db->lookaside.bMalloced ){

   563     sqlite3_free(db->lookaside.pStart);

   564   }

   565   sqlite3_free(db);

   566   return SQLITE_OK;

   567 }

   568 

   569 /*

   570 ** Rollback all database files.

   571 */

   572 void sqlite3RollbackAll(sqlite3 *db){

   573   int i;

   574   int inTrans = 0;

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

   576   sqlite3BeginBenignMalloc();

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

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

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

   580         inTrans = 1;

   581       }

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

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

   584     }

   585   }

   586   sqlite3VtabRollback(db);

   587   sqlite3EndBenignMalloc();

   588 

   589   if( db->flags&SQLITE_InternChanges ){

   590     sqlite3ExpirePreparedStatements(db);

   591     sqlite3ResetInternalSchema(db, 0);

   592   }

   593 

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

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

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

   597   }

   598 }

   599 

   600 /*

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

   602 ** argument.

   603 */

   604 const char *sqlite3ErrStr(int rc){

   605   const char *z;

   606   switch( rc & 0xff ){

   607     case SQLITE_ROW:

   608     case SQLITE_DONE:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   634   }

   635   return z;

   636 }

   637 

   638 /*

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

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

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

   642 ** argument.

   643 */

   644 static int sqliteDefaultBusyCallback(

   645  void *ptr,               /* Database connection */

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

   647 ){

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

   649   static const u8 delays[] =

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

   651   static const u8 totals[] =

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

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

   654   sqlite3 *db = (sqlite3 *)ptr;

   655   int timeout = db->busyTimeout;

   656   int delay, prior;

   657 

   658   assert( count>=0 );

   659   if( count < NDELAY ){

   660     delay = delays[count];

   661     prior = totals[count];

   662   }else{

   663     delay = delays[NDELAY-1];

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

   665   }

   666   if( prior + delay > timeout ){

   667     delay = timeout - prior;

   668     if( delay<=0 ) return 0;

   669   }

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

   671   return 1;

   672 #else

   673   sqlite3 *db = (sqlite3 *)ptr;

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

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

   676     return 0;

   677   }

   678   sqlite3OsSleep(db->pVfs, 1000000);

   679   return 1;

   680 #endif

   681 }

   682 

   683 /*

   684 ** Invoke the given busy handler.

   685 **

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

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

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

   689 */

   690 int sqlite3InvokeBusyHandler(BusyHandler *p){

   691   int rc;

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

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

   694   if( rc==0 ){

   695     p->nBusy = -1;

   696   }else{

   697     p->nBusy++;

   698   }

   699   return rc; 

   700 }

   701 

   702 /*

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

   704 ** given callback function with the given argument.

   705 */

   706 int sqlite3_busy_handler(

   707   sqlite3 *db,

   708   int (*xBusy)(void*,int),

   709   void *pArg

   710 ){

   711   sqlite3_mutex_enter(db->mutex);

   712   db->busyHandler.xFunc = xBusy;

   713   db->busyHandler.pArg = pArg;

   714   db->busyHandler.nBusy = 0;

   715   sqlite3_mutex_leave(db->mutex);

   716   return SQLITE_OK;

   717 }

   718 

   719 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

   720 /*

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

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

   723 ** be invoked every nOps opcodes.

   724 */

   725 void sqlite3_progress_handler(

   726   sqlite3 *db, 

   727   int nOps,

   728   int (*xProgress)(void*), 

   729   void *pArg

   730 ){

   731   sqlite3_mutex_enter(db->mutex);

   732   if( nOps>0 ){

   733     db->xProgress = xProgress;

   734     db->nProgressOps = nOps;

   735     db->pProgressArg = pArg;

   736   }else{

   737     db->xProgress = 0;

   738     db->nProgressOps = 0;

   739     db->pProgressArg = 0;

   740   }

   741   sqlite3_mutex_leave(db->mutex);

   742 }

   743 #endif

   744 

   745 

   746 /*

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

   748 ** specified number of milliseconds before returning 0.

   749 */

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

   751   if( ms>0 ){

   752     db->busyTimeout = ms;

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

   754   }else{

   755     sqlite3_busy_handler(db, 0, 0);

   756   }

   757   return SQLITE_OK;

   758 }

   759 

   760 /*

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

   762 */

   763 void sqlite3_interrupt(sqlite3 *db){

   764   db->u1.isInterrupted = 1;

   765 }

   766 

   767 

   768 /*

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

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

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

   772 ** is returned and the mallocFailed flag cleared. 

   773 */

   774 int sqlite3CreateFunc(

   775   sqlite3 *db,

   776   const char *zFunctionName,

   777   int nArg,

   778   int enc,

   779   void *pUserData,

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

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

   782   void (*xFinal)(sqlite3_context*)

   783 ){

   784   FuncDef *p;

   785   int nName;

   786 

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

   788   if( zFunctionName==0 ||

   789       (xFunc && (xFinal || xStep)) || 

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

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

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

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

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

   795     return SQLITE_ERROR;

   796   }

   797   

   798 #ifndef SQLITE_OMIT_UTF16

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

   800   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

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

   802   **

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

   804   ** to the hash table.

   805   */

   806   if( enc==SQLITE_UTF16 ){

   807     enc = SQLITE_UTF16NATIVE;

   808   }else if( enc==SQLITE_ANY ){

   809     int rc;

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

   811          pUserData, xFunc, xStep, xFinal);

   812     if( rc==SQLITE_OK ){

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

   814           pUserData, xFunc, xStep, xFinal);

   815     }

   816     if( rc!=SQLITE_OK ){

   817       return rc;

   818     }

   819     enc = SQLITE_UTF16BE;

   820   }

   821 #else

   822   enc = SQLITE_UTF8;

   823 #endif

   824   

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

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

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

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

   829   */

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

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

   832     if( db->activeVdbeCnt ){

   833       sqlite3Error(db, SQLITE_BUSY, 

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

   835       assert( !db->mallocFailed );

   836       return SQLITE_BUSY;

   837     }else{

   838       sqlite3ExpirePreparedStatements(db);

   839     }

   840   }

   841 

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

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

   844   if( !p ){

   845     return SQLITE_NOMEM;

   846   }

   847   p->flags = 0;

   848   p->xFunc = xFunc;

   849   p->xStep = xStep;

   850   p->xFinalize = xFinal;

   851   p->pUserData = pUserData;

   852   p->nArg = nArg;

   853   return SQLITE_OK;

   854 }

   855 

   856 /*

   857 ** Create new user functions.

   858 */

   859 int sqlite3_create_function(

   860   sqlite3 *db,

   861   const char *zFunctionName,

   862   int nArg,

   863   int enc,

   864   void *p,

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

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

   867   void (*xFinal)(sqlite3_context*)

   868 ){

   869   int rc;

   870   sqlite3_mutex_enter(db->mutex);

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

   872   rc = sqlite3ApiExit(db, rc);

   873   sqlite3_mutex_leave(db->mutex);

   874   return rc;

   875 }

   876 

   877 #ifndef SQLITE_OMIT_UTF16

   878 int sqlite3_create_function16(

   879   sqlite3 *db,

   880   const void *zFunctionName,

   881   int nArg,

   882   int eTextRep,

   883   void *p,

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

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

   886   void (*xFinal)(sqlite3_context*)

   887 ){

   888   int rc;

   889   char *zFunc8;

   890   sqlite3_mutex_enter(db->mutex);

   891   assert( !db->mallocFailed );

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

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

   894   sqlite3DbFree(db, zFunc8);

   895   rc = sqlite3ApiExit(db, rc);

   896   sqlite3_mutex_leave(db->mutex);

   897   return rc;

   898 }

   899 #endif

   900 

   901 

   902 /*

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

   904 **

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

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

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

   908 **

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

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

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

   912 ** properly.

   913 */

   914 int sqlite3_overload_function(

   915   sqlite3 *db,

   916   const char *zName,

   917   int nArg

   918 ){

   919   int nName = sqlite3Strlen(db, zName);

   920   int rc;

   921   sqlite3_mutex_enter(db->mutex);

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

   923     sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,

   924                       0, sqlite3InvalidFunction, 0, 0);

   925   }

   926   rc = sqlite3ApiExit(db, SQLITE_OK);

   927   sqlite3_mutex_leave(db->mutex);

   928   return rc;

   929 }

   930 

   931 #ifndef SQLITE_OMIT_TRACE

   932 /*

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

   934 ** is returned.  

   935 **

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

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

   938 ** SQL statement.

   939 */

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

   941   void *pOld;

   942   sqlite3_mutex_enter(db->mutex);

   943   pOld = db->pTraceArg;

   944   db->xTrace = xTrace;

   945   db->pTraceArg = pArg;

   946   sqlite3_mutex_leave(db->mutex);

   947   return pOld;

   948 }

   949 /*

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

   951 ** profile function is returned.  

   952 **

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

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

   955 ** each SQL statement that is run.

   956 */

   957 void *sqlite3_profile(

   958   sqlite3 *db,

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

   960   void *pArg

   961 ){

   962   void *pOld;

   963   sqlite3_mutex_enter(db->mutex);

   964   pOld = db->pProfileArg;

   965   db->xProfile = xProfile;

   966   db->pProfileArg = pArg;

   967   sqlite3_mutex_leave(db->mutex);

   968   return pOld;

   969 }

   970 #endif /* SQLITE_OMIT_TRACE */

   971 

   972 /*** EXPERIMENTAL ***

   973 **

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

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

   976 ** rollback.

   977 */

   978 void *sqlite3_commit_hook(

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

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

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

   982 ){

   983   void *pOld;

   984   sqlite3_mutex_enter(db->mutex);

   985   pOld = db->pCommitArg;

   986   db->xCommitCallback = xCallback;

   987   db->pCommitArg = pArg;

   988   sqlite3_mutex_leave(db->mutex);

   989   return pOld;

   990 }

   991 

   992 /*

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

   994 ** inserted or deleted using this database connection.

   995 */

   996 void *sqlite3_update_hook(

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

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

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

  1000 ){

  1001   void *pRet;

  1002   sqlite3_mutex_enter(db->mutex);

  1003   pRet = db->pUpdateArg;

  1004   db->xUpdateCallback = xCallback;

  1005   db->pUpdateArg = pArg;

  1006   sqlite3_mutex_leave(db->mutex);

  1007   return pRet;

  1008 }

  1009 

  1010 /*

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

  1012 ** back by this database connection.

  1013 */

  1014 void *sqlite3_rollback_hook(

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

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

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

  1018 ){

  1019   void *pRet;

  1020   sqlite3_mutex_enter(db->mutex);

  1021   pRet = db->pRollbackArg;

  1022   db->xRollbackCallback = xCallback;

  1023   db->pRollbackArg = pArg;

  1024   sqlite3_mutex_leave(db->mutex);

  1025   return pRet;

  1026 }

  1027 

  1028 /*

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

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

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

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

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

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

  1035 ** soon as the connection is closed.

  1036 **

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

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

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

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

  1041 **

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

  1043 **   -----------------     --------------     ------------------------------

  1044 **   0                     any                file

  1045 **   1                     1                  file

  1046 **   1                     2                  memory

  1047 **   1                     0                  file

  1048 **   2                     1                  file

  1049 **   2                     2                  memory

  1050 **   2                     0                  memory

  1051 **   3                     any                memory

  1052 */

  1053 int sqlite3BtreeFactory(

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

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

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

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

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

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

  1060 ){

  1061   int btFlags = 0;

  1062   int rc;

  1063   

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

  1065   assert( ppBtree != 0);

  1066   if( omitJournal ){

  1067     btFlags |= BTREE_OMIT_JOURNAL;

  1068   }

  1069   if( db->flags & SQLITE_NoReadlock ){

  1070     btFlags |= BTREE_NO_READLOCK;

  1071   }

  1072   if( zFilename==0 ){

  1073 #if SQLITE_TEMP_STORE==0

  1074     /* Do nothing */

  1075 #endif

  1076 #ifndef SQLITE_OMIT_MEMORYDB

  1077 #if SQLITE_TEMP_STORE==1

  1078     if( db->temp_store==2 ) zFilename = ":memory:";

  1079 #endif

  1080 #if SQLITE_TEMP_STORE==2

  1081     if( db->temp_store!=1 ) zFilename = ":memory:";

  1082 #endif

  1083 #if SQLITE_TEMP_STORE==3

  1084     zFilename = ":memory:";

  1085 #endif

  1086 #endif /* SQLITE_OMIT_MEMORYDB */

  1087   }

  1088 

  1089   if( (vfsFlags & SQLITE_OPEN_MAIN_DB)!=0 && (zFilename==0 || *zFilename==0) ){

  1090     vfsFlags = (vfsFlags & ~SQLITE_OPEN_MAIN_DB) | SQLITE_OPEN_TEMP_DB;

  1091   }

  1092   rc = sqlite3BtreeOpen(zFilename, (sqlite3 *)db, ppBtree, btFlags, vfsFlags);

  1093 

  1094   /* If the B-Tree was successfully opened, set the pager-cache size to the

  1095   ** default value. Except, if the call to BtreeOpen() returned a handle

  1096   ** open on an existing shared pager-cache, do not change the pager-cache 

  1097   ** size.

  1098   */

  1099   if( rc==SQLITE_OK && 0==sqlite3BtreeSchema(*ppBtree, 0, 0) ){

  1100     sqlite3BtreeSetCacheSize(*ppBtree, nCache);

  1101   }

  1102   return rc;

  1103 }

  1104 

  1105 /*

  1106 ** Return UTF-8 encoded English language explanation of the most recent

  1107 ** error.

  1108 */

  1109 const char *sqlite3_errmsg(sqlite3 *db){

  1110   const char *z;

  1111   if( !db ){

  1112     return sqlite3ErrStr(SQLITE_NOMEM);

  1113   }

  1114   if( !sqlite3SafetyCheckSickOrOk(db) ){

  1115     return sqlite3ErrStr(SQLITE_MISUSE);

  1116   }

  1117   sqlite3_mutex_enter(db->mutex);

  1118   assert( !db->mallocFailed );

  1119   z = (char*)sqlite3_value_text(db->pErr);

  1120   assert( !db->mallocFailed );

  1121   if( z==0 ){

  1122     z = sqlite3ErrStr(db->errCode);

  1123   }

  1124   sqlite3_mutex_leave(db->mutex);

  1125   return z;

  1126 }

  1127 

  1128 #ifndef SQLITE_OMIT_UTF16

  1129 /*

  1130 ** Return UTF-16 encoded English language explanation of the most recent

  1131 ** error.

  1132 */

  1133 const void *sqlite3_errmsg16(sqlite3 *db){

  1134   /* Because all the characters in the string are in the unicode