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.356 2006/09/02 13:58:07 drh Exp $

    18 */

    19 #include "sqliteInt.h"

    20 #include "os.h"

    21 #include <ctype.h>

    22 

    23 /*

    24 ** The following constant value is used by the SQLITE_BIGENDIAN and

    25 ** SQLITE_LITTLEENDIAN macros.

    26 */

    27 const int sqlite3one = 1;

    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 

    36 /*

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

    38 ** available.

    39 */

    40 static int binCollFunc(

    41   void *NotUsed,

    42   int nKey1, const void *pKey1,

    43   int nKey2, const void *pKey2

    44 ){

    45   int rc, n;

    46   n = nKey1<nKey2 ? nKey1 : nKey2;

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

    48   if( rc==0 ){

    49     rc = nKey1 - nKey2;

    50   }

    51   return rc;

    52 }

    53 

    54 /*

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

    56 **

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

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

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

    60 **

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

    62 */

    63 static int nocaseCollatingFunc(

    64   void *NotUsed,

    65   int nKey1, const void *pKey1,

    66   int nKey2, const void *pKey2

    67 ){

    68   int r = sqlite3StrNICmp(

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

    70   if( 0==r ){

    71     r = nKey1-nKey2;

    72   }

    73   return r;

    74 }

    75 

    76 /*

    77 ** Return the ROWID of the most recent insert

    78 */

    79 EXPORT_C sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){

    80   return db->lastRowid;

    81 }

    82 

    83 /*

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

    85 */

    86 EXPORT_C int sqlite3_changes(sqlite3 *db){

    87   return db->nChange;

    88 }

    89 

    90 /*

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

    92 */

    93 int sqlite3_total_changes(sqlite3 *db){

    94   return db->nTotalChange;

    95 }

    96 

    97 /*

    98 ** Close an existing SQLite database

    99 */

   100 EXPORT_C int sqlite3_close(sqlite3 *db){

   101   HashElem *i;

   102   int j;

   103 

   104   if( !db ){

   105     return SQLITE_OK;

   106   }

   107   if( sqlite3SafetyCheck(db) ){

   108     return SQLITE_MISUSE;

   109   }

   110 

   111 #ifdef SQLITE_SSE

   112   {

   113     extern void sqlite3SseCleanup(sqlite3*);

   114     sqlite3SseCleanup(db);

   115   }

   116 #endif 

   117 

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

   119   sqlite3ResetInternalSchema(db, 0);

   120   if( db->pVdbe ){

   121     sqlite3Error(db, SQLITE_BUSY, 

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

   123     return SQLITE_BUSY;

   124   }

   125   assert( !sqlite3SafetyCheck(db) );

   126 

   127   /* FIX ME: db->magic may be set to SQLITE_MAGIC_CLOSED if the database

   128   ** cannot be opened for some reason. So this routine needs to run in

   129   ** that case. But maybe there should be an extra magic value for the

   130   ** "failed to open" state.

   131   */

   132   if( db->magic!=SQLITE_MAGIC_CLOSED && sqlite3SafetyOn(db) ){

   133     /* printf("DID NOT CLOSE\n"); fflush(stdout); */

   134     return SQLITE_ERROR;

   135   }

   136 

   137   sqlite3VtabRollback(db);

   138 

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

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

   141     if( pDb->pBt ){

   142       sqlite3BtreeClose(pDb->pBt);

   143       pDb->pBt = 0;

   144       if( j!=1 ){

   145         pDb->pSchema = 0;

   146       }

   147     }

   148   }

   149   sqlite3ResetInternalSchema(db, 0);

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

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

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

   153     FuncDef *pFunc, *pNext;

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

   155       pNext = pFunc->pNext;

   156       sqliteFree(pFunc);

   157     }

   158   }

   159 

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

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

   162     sqliteFree(pColl);

   163   }

   164   sqlite3HashClear(&db->aCollSeq);

   165 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

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

   168     sqliteFree(pMod);

   169   }

   170   sqlite3HashClear(&db->aModule);

   171 #endif

   172 

   173   sqlite3HashClear(&db->aFunc);

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

   175   if( db->pErr ){

   176     sqlite3ValueFree(db->pErr);

   177   }

   178   sqlite3CloseExtensions(db);

   179 

   180   db->magic = SQLITE_MAGIC_ERROR;

   181 

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

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

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

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

   186   ** structure?

   187   */

   188   sqliteFree(db->aDb[1].pSchema);

   189   sqliteFree(db);

   190   sqlite3ReleaseThreadData();

   191   return SQLITE_OK;

   192 }

   193 

   194 /*

   195 ** Rollback all database files.

   196 */

   197 void sqlite3RollbackAll(sqlite3 *db){

   198   int i;

   199   int inTrans = 0;

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

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

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

   203         inTrans = 1;

   204       }

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

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

   207     }

   208   }

   209   sqlite3VtabRollback(db);

   210   if( db->flags&SQLITE_InternChanges ){

   211     sqlite3ResetInternalSchema(db, 0);

   212   }

   213 

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

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

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

   217   }

   218 }

   219 

   220 /*

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

   222 ** argument.

   223 */

   224 const char *sqlite3ErrStr(int rc){

   225   const char *z;

   226   switch( rc ){

   227     case SQLITE_ROW:

   228     case SQLITE_DONE:

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

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

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

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

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

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

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

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

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

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

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

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

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

   242     case SQLITE_PROTOCOL:   z = "database locking protocol failure";     break;

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

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

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

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

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

   248     case SQLITE_NOLFS:      z = "kernel lacks large file support";       break;

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

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

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

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

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

   254   }

   255   return z;

   256 }

   257 

   258 /*

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

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

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

   262 ** argument.

   263 */

   264 static int sqliteDefaultBusyCallback(

   265  void *ptr,               /* Database connection */

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

   267 ){

   268 #if OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)

   269   static const u8 delays[] =

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

   271   static const u8 totals[] =

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

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

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

   275   int delay, prior;

   276 

   277   assert( count>=0 );

   278   if( count < NDELAY ){

   279     delay = delays[count];

   280     prior = totals[count];

   281   }else{

   282     delay = delays[NDELAY-1];

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

   284   }

   285   if( prior + delay > timeout ){

   286     delay = timeout - prior;

   287     if( delay<=0 ) return 0;

   288   }

   289   sqlite3OsSleep(delay);

   290   return 1;

   291 #else

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

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

   294     return 0;

   295   }

   296   sqlite3OsSleep(1000);

   297   return 1;

   298 #endif

   299 }

   300 

   301 /*

   302 ** Invoke the given busy handler.

   303 **

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

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

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

   307 */

   308 int sqlite3InvokeBusyHandler(BusyHandler *p){

   309   int rc;

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

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

   312   if( rc==0 ){

   313     p->nBusy = -1;

   314   }else{

   315     p->nBusy++;

   316   }

   317   return rc; 

   318 }

   319 

   320 /*

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

   322 ** given callback function with the given argument.

   323 */

   324 EXPORT_C int sqlite3_busy_handler(

   325   sqlite3 *db,

   326   int (*xBusy)(void*,int),

   327   void *pArg

   328 ){

   329   if( sqlite3SafetyCheck(db) ){

   330     return SQLITE_MISUSE;

   331   }

   332   db->busyHandler.xFunc = xBusy;

   333   db->busyHandler.pArg = pArg;

   334   db->busyHandler.nBusy = 0;

   335   return SQLITE_OK;

   336 }

   337 

   338 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

   339 /*

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

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

   342 ** be invoked every nOps opcodes.

   343 */

   344 void sqlite3_progress_handler(

   345   sqlite3 *db, 

   346   int nOps,

   347   int (*xProgress)(void*), 

   348   void *pArg

   349 ){

   350   if( !sqlite3SafetyCheck(db) ){

   351     if( nOps>0 ){

   352       db->xProgress = xProgress;

   353       db->nProgressOps = nOps;

   354       db->pProgressArg = pArg;

   355     }else{

   356       db->xProgress = 0;

   357       db->nProgressOps = 0;

   358       db->pProgressArg = 0;

   359     }

   360   }

   361 }

   362 #endif

   363 

   364 

   365 /*

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

   367 ** specified number of milliseconds before returning 0.

   368 */

   369 EXPORT_C int sqlite3_busy_timeout(sqlite3 *db, int ms){

   370   if( sqlite3SafetyCheck(db) ){

   371     return SQLITE_MISUSE;

   372   }

   373   if( ms>0 ){

   374     db->busyTimeout = ms;

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

   376   }else{

   377     sqlite3_busy_handler(db, 0, 0);

   378   }

   379   return SQLITE_OK;

   380 }

   381 

   382 /*

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

   384 */

   385 void sqlite3_interrupt(sqlite3 *db){

   386   if( db && (db->magic==SQLITE_MAGIC_OPEN || db->magic==SQLITE_MAGIC_BUSY) ){

   387     db->u1.isInterrupted = 1;

   388   }

   389 }

   390 

   391 /*

   392 ** Memory allocation routines that use SQLites internal memory

   393 ** memory allocator.  Depending on how SQLite is compiled, the

   394 ** internal memory allocator might be just an alias for the

   395 ** system default malloc/realloc/free.  Or the built-in allocator

   396 ** might do extra stuff like put sentinals around buffers to 

   397 ** check for overruns or look for memory leaks.

   398 **

   399 ** Use sqlite3_free() to free memory returned by sqlite3_mprintf().

   400 */

   401 void sqlite3_free(void *p){ if( p ) sqlite3OsFree(p); }

   402 void *sqlite3_malloc(int nByte){ return nByte>0 ? sqlite3OsMalloc(nByte) : 0; }

   403 void *sqlite3_realloc(void *pOld, int nByte){ 

   404   if( pOld ){

   405     if( nByte>0 ){

   406       return sqlite3OsRealloc(pOld, nByte);

   407     }else{

   408       sqlite3OsFree(pOld);

   409       return 0;

   410     }

   411   }else{

   412     return sqlite3_malloc(nByte);

   413   }

   414 }

   415 

   416 /*

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

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

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

   420 ** is returned and the mallocFailed flag cleared. 

   421 */

   422 int sqlite3CreateFunc(

   423   sqlite3 *db,

   424   const char *zFunctionName,

   425   int nArg,

   426   int enc,

   427   void *pUserData,

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

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

   430   void (*xFinal)(sqlite3_context*)

   431 ){

   432   FuncDef *p;

   433   int nName;

   434 

   435   if( sqlite3SafetyCheck(db) ){

   436     return SQLITE_MISUSE;

   437   }

   438   if( zFunctionName==0 ||

   439       (xFunc && (xFinal || xStep)) || 

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

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

   442       (nArg<-1 || nArg>127) ||

   443       (255<(nName = strlen(zFunctionName))) ){

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

   445     return SQLITE_ERROR;

   446   }

   447   

   448 #ifndef SQLITE_OMIT_UTF16

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

   450   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

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

   452   **

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

   454   ** to the hash table.

   455   */

   456   if( enc==SQLITE_UTF16 ){

   457     enc = SQLITE_UTF16NATIVE;

   458   }else if( enc==SQLITE_ANY ){

   459     int rc;

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

   461          pUserData, xFunc, xStep, xFinal);

   462     if( rc!=SQLITE_OK ) return rc;

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

   464         pUserData, xFunc, xStep, xFinal);

   465     if( rc!=SQLITE_OK ) return rc;

   466     enc = SQLITE_UTF16BE;

   467   }

   468 #else

   469   enc = SQLITE_UTF8;

   470 #endif

   471   

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

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

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

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

   476   */

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

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

   479     if( db->activeVdbeCnt ){

   480       sqlite3Error(db, SQLITE_BUSY, 

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

   482       assert( !sqlite3MallocFailed() );

   483       return SQLITE_BUSY;

   484     }else{

   485       sqlite3ExpirePreparedStatements(db);

   486     }

   487   }

   488 

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

   490   if( p ){

   491     p->flags = 0;

   492     p->xFunc = xFunc;

   493     p->xStep = xStep;

   494     p->xFinalize = xFinal;

   495     p->pUserData = pUserData;

   496     p->nArg = nArg;

   497   }

   498   return SQLITE_OK;

   499 }

   500 

   501 /*

   502 ** Create new user functions.

   503 */

   504 int sqlite3_create_function(

   505   sqlite3 *db,

   506   const char *zFunctionName,

   507   int nArg,

   508   int enc,

   509   void *p,

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

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

   512   void (*xFinal)(sqlite3_context*)

   513 ){

   514   int rc;

   515   assert( !sqlite3MallocFailed() );

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

   517 

   518   return sqlite3ApiExit(db, rc);

   519 }

   520 

   521 #ifndef SQLITE_OMIT_UTF16

   522 int sqlite3_create_function16(

   523   sqlite3 *db,

   524   const void *zFunctionName,

   525   int nArg,

   526   int eTextRep,

   527   void *p,

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

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

   530   void (*xFinal)(sqlite3_context*)

   531 ){

   532   int rc;

   533   char *zFunc8;

   534   assert( !sqlite3MallocFailed() );

   535 

   536   zFunc8 = sqlite3utf16to8(zFunctionName, -1);

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

   538   sqliteFree(zFunc8);

   539 

   540   return sqlite3ApiExit(db, rc);

   541 }

   542 #endif

   543 

   544 #ifndef SQLITE_OMIT_TRACE

   545 /*

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

   547 ** is returned.  

   548 **

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

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

   551 ** SQL statement.

   552 */

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

   554   void *pOld = db->pTraceArg;

   555   db->xTrace = xTrace;

   556   db->pTraceArg = pArg;

   557   return pOld;

   558 }

   559 /*

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

   561 ** profile function is returned.  

   562 **

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

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

   565 ** each SQL statement that is run.

   566 */

   567 void *sqlite3_profile(

   568   sqlite3 *db,

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

   570   void *pArg

   571 ){

   572   void *pOld = db->pProfileArg;

   573   db->xProfile = xProfile;

   574   db->pProfileArg = pArg;

   575   return pOld;

   576 }

   577 #endif /* SQLITE_OMIT_TRACE */

   578 

   579 /*** EXPERIMENTAL ***

   580 **

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

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

   583 ** rollback.

   584 */

   585 void *sqlite3_commit_hook(

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

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

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

   589 ){

   590   void *pOld = db->pCommitArg;

   591   db->xCommitCallback = xCallback;

   592   db->pCommitArg = pArg;

   593   return pOld;

   594 }

   595 

   596 /*

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

   598 ** inserted or deleted using this database connection.

   599 */

   600 void *sqlite3_update_hook(

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

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

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

   604 ){

   605   void *pRet = db->pUpdateArg;

   606   db->xUpdateCallback = xCallback;

   607   db->pUpdateArg = pArg;

   608   return pRet;

   609 }

   610 

   611 /*

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

   613 ** back by this database connection.

   614 */

   615 void *sqlite3_rollback_hook(

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

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

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

   619 ){

   620   void *pRet = db->pRollbackArg;

   621   db->xRollbackCallback = xCallback;

   622   db->pRollbackArg = pArg;

   623   return pRet;

   624 }

   625 

   626 /*

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

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

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

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

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

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

   633 ** soon as the connection is closed.

   634 **

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

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

   637 ** depending on the values of the TEMP_STORE compile-time macro and the

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

   639 **

   640 **       TEMP_STORE     db->temp_store     Location of temporary database

   641 **       ----------     --------------     ------------------------------

   642 **           0               any             file

   643 **           1                1              file

   644 **           1                2              memory

   645 **           1                0              file

   646 **           2                1              file

   647 **           2                2              memory

   648 **           2                0              memory

   649 **           3               any             memory

   650 */

   651 int sqlite3BtreeFactory(

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

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

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

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

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

   657 ){

   658   int btree_flags = 0;

   659   int rc;

   660   

   661   assert( ppBtree != 0);

   662   if( omitJournal ){

   663     btree_flags |= BTREE_OMIT_JOURNAL;

   664   }

   665   if( db->flags & SQLITE_NoReadlock ){

   666     btree_flags |= BTREE_NO_READLOCK;

   667   }

   668   if( zFilename==0 ){

   669 #if TEMP_STORE==0

   670     /* Do nothing */

   671 #endif

   672 #ifndef SQLITE_OMIT_MEMORYDB

   673 #if TEMP_STORE==1

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

   675 #endif

   676 #if TEMP_STORE==2

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

   678 #endif

   679 #if TEMP_STORE==3

   680     zFilename = ":memory:";

   681 #endif

   682 #endif /* SQLITE_OMIT_MEMORYDB */

   683   }

   684 

   685   rc = sqlite3BtreeOpen(zFilename, (sqlite3 *)db, ppBtree, btree_flags);

   686   if( rc==SQLITE_OK ){

   687     sqlite3BtreeSetBusyHandler(*ppBtree, (void*)&db->busyHandler);

   688     sqlite3BtreeSetCacheSize(*ppBtree, nCache);

   689   }

   690   return rc;

   691 }

   692 

   693 /*

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

   695 ** error.

   696 */

   697 EXPORT_C const char *sqlite3_errmsg(sqlite3 *db){

   698   const char *z;

   699   if( !db || sqlite3MallocFailed() ){

   700     return sqlite3ErrStr(SQLITE_NOMEM);

   701   }

   702   if( sqlite3SafetyCheck(db) || db->errCode==SQLITE_MISUSE ){

   703     return sqlite3ErrStr(SQLITE_MISUSE);

   704   }

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

   706   if( z==0 ){

   707     z = sqlite3ErrStr(db->errCode);

   708   }

   709   return z;

   710 }

   711 

   712 #ifndef SQLITE_OMIT_UTF16

   713 /*

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

   715 ** error.

   716 */

   717 const void *sqlite3_errmsg16(sqlite3 *db){

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

   719   ** range 0x00-0xFF, if we pad the big-endian string with a 

   720   ** zero byte, we can obtain the little-endian string with

   721   ** &big_endian[1].

   722   */

   723   static const char outOfMemBe[] = {

   724     0, 'o', 0, 'u', 0, 't', 0, ' ', 

   725     0, 'o', 0, 'f', 0, ' ', 

   726     0, 'm', 0, 'e', 0, 'm', 0, 'o', 0, 'r', 0, 'y', 0, 0, 0

   727   };

   728   static const char misuseBe [] = {

   729     0, 'l', 0, 'i', 0, 'b', 0, 'r', 0, 'a', 0, 'r', 0, 'y', 0, ' ', 

   730     0, 'r', 0, 'o', 0, 'u', 0, 't', 0, 'i', 0, 'n', 0, 'e', 0, ' ', 

   731     0, 'c', 0, 'a', 0, 'l', 0, 'l', 0, 'e', 0, 'd', 0, ' ', 

   732     0, 'o', 0, 'u', 0, 't', 0, ' ', 

   733     0, 'o', 0, 'f', 0, ' ', 

   734     0, 's', 0, 'e', 0, 'q', 0, 'u', 0, 'e', 0, 'n', 0, 'c', 0, 'e', 0, 0, 0

   735   };

   736 

   737   const void *z;

   738   if( sqlite3MallocFailed() ){

   739     return (void *)(&outOfMemBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]);

   740   }

   741   if( sqlite3SafetyCheck(db) || db->errCode==SQLITE_MISUSE ){

   742     return (void *)(&misuseBe[SQLITE_UTF16NATIVE==SQLITE_UTF16LE?1:0]);

   743   }

   744   z = sqlite3_value_text16(db->pErr);

   745   if( z==0 ){

   746     sqlite3ValueSetStr(db->pErr, -1, sqlite3ErrStr(db->errCode),

   747          SQLITE_UTF8, SQLITE_STATIC);

   748     z = sqlite3_value_text16(db->pErr);

   749   }

   750   sqlite3ApiExit(0, 0);

   751   return z;

   752 }

   753 #endif /* SQLITE_OMIT_UTF16 */

   754 

   755 /*

   756 ** Return the most recent error code generated by an SQLite routine. If NULL is

   757 ** passed to this function, we assume a malloc() failed during sqlite3_open().

   758 */

   759 EXPORT_C int sqlite3_errcode(sqlite3 *db){

   760   if( !db || sqlite3MallocFailed() ){

   761     return SQLITE_NOMEM;

   762   }

   763   if( sqlite3SafetyCheck(db) ){

   764     return SQLITE_MISUSE;

   765   }

   766   return db->errCode;

   767 }

   768 

   769 /*

   770 ** Create a new collating function for database "db".  The name is zName

   771 ** and the encoding is enc.

   772 */

   773 static int createCollation(

   774   sqlite3* db, 

   775   const char *zName, 

   776   int enc, 

   777   void* pCtx,

   778   int(*xCompare)(void*,int,const void*,int,const void*)

   779 ){

   780   CollSeq *pColl;

   781   int enc2;

   782   

   783   if( sqlite3SafetyCheck(db) ){

   784     return SQLITE_MISUSE;

   785   }

   786 

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

   788   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the

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

   790   */

   791   enc2 = enc & ~SQLITE_UTF16_ALIGNED;

   792   if( enc2==SQLITE_UTF16 ){

   793     enc2 = SQLITE_UTF16NATIVE;

   794   }

   795 

   796   if( (enc2&~3)!=0 ){

   797     sqlite3Error(db, SQLITE_ERROR, "unknown encoding");

   798     return SQLITE_ERROR;

   799   }

   800 

   801   /* Check if this call is removing or replacing an existing collation 

   802   ** sequence. If so, and there are active VMs, return busy. If there

   803   ** are no active VMs, invalidate any pre-compiled statements.

   804   */

   805   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, strlen(zName), 0);

   806   if( pColl && pColl->xCmp ){

   807     if( db->activeVdbeCnt ){

   808       sqlite3Error(db, SQLITE_BUSY, 

   809         "Unable to delete/modify collation sequence due to active statements");

   810       return SQLITE_BUSY;

   811     }

   812     sqlite3ExpirePreparedStatements(db);

   813   }

   814 

   815   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, strlen(zName), 1);

   816   if( pColl ){

   817     pColl->xCmp = xCompare;

   818     pColl->pUser = pCtx;

   819     pColl->enc = enc2 | (enc & SQLITE_UTF16_ALIGNED);

   820   }

   821   sqlite3Error(db, SQLITE_OK, 0);

   822   return SQLITE_OK;

   823 }

   824 

   825 

   826 /*

   827 ** This routine does the work of opening a database on behalf of

   828 ** sqlite3_open() and sqlite3_open16(). The database filename "zFilename"  

   829 ** is UTF-8 encoded.

   830 */

   831 static int openDatabase(

   832   const char *zFilename, /* Database filename UTF-8 encoded */

   833   sqlite3 **ppDb         /* OUT: Returned database handle */

   834 ){

   835   sqlite3 *db;

   836   int rc;

   837   CollSeq *pColl;

   838 

   839   assert( !sqlite3MallocFailed() );

   840 

   841   /* Allocate the sqlite data structure */

   842   db = sqliteMalloc( sizeof(sqlite3) );

   843   if( db==0 ) goto opendb_out;

   844   db->priorNewRowid = 0;

   845   db->magic = SQLITE_MAGIC_BUSY;

   846   db->nDb = 2;

   847   db->aDb = db->aDbStatic;

   848   db->autoCommit = 1;

   849   db->flags |= SQLITE_ShortColNames

   850 #if SQLITE_DEFAULT_FILE_FORMAT<4

   851                  | SQLITE_LegacyFileFmt

   852 #endif

   853       ;

   854   sqlite3HashInit(&db->aFunc, SQLITE_HASH_STRING, 0);

   855   sqlite3HashInit(&db->aCollSeq, SQLITE_HASH_STRING, 0);

   856 #ifndef SQLITE_OMIT_VIRTUALTABLE

   857   sqlite3HashInit(&db->aModule, SQLITE_HASH_STRING, 0);

   858 #endif

   859 

   860   /* Add the default collation sequence BINARY. BINARY works for both UTF-8

   861   ** and UTF-16, so add a version for each to avoid any unnecessary

   862   ** conversions. The only error that can occur here is a malloc() failure.

   863   */

   864   if( createCollation(db, "BINARY", SQLITE_UTF8, 0, binCollFunc) ||

   865       createCollation(db, "BINARY", SQLITE_UTF16BE, 0, binCollFunc) ||

   866       createCollation(db, "BINARY", SQLITE_UTF16LE, 0, binCollFunc) ||

   867       (db->pDfltColl = sqlite3FindCollSeq(db, SQLITE_UTF8, "BINARY", 6, 0))==0 

   868   ){

   869     assert( sqlite3MallocFailed() );

   870     db->magic = SQLITE_MAGIC_CLOSED;

   871     goto opendb_out;

   872   }

   873 

   874   /* Also add a UTF-8 case-insensitive collation sequence. */

   875   createCollation(db, "NOCASE", SQLITE_UTF8, 0, nocaseCollatingFunc);

   876 

   877   /* Set flags on the built-in collating sequences */

   878   db->pDfltColl->type = SQLITE_COLL_BINARY;

   879   pColl = sqlite3FindCollSeq(db, SQLITE_UTF8, "NOCASE", 6, 0);

   880   if( pColl ){

   881     pColl->type = SQLITE_COLL_NOCASE;

   882   }

   883 

   884   /* Open the backend database driver */

   885   rc = sqlite3BtreeFactory(db, zFilename, 0, MAX_PAGES, &db->aDb[0].pBt);

   886   if( rc!=SQLITE_OK ){

   887     sqlite3Error(db, rc, 0);

   888     db->magic = SQLITE_MAGIC_CLOSED;

   889     goto opendb_out;

   890   }

   891   db->aDb[0].pSchema = sqlite3SchemaGet(db->aDb[0].pBt);

   892   db->aDb[1].pSchema = sqlite3SchemaGet(0);

   893 

   894 

   895   /* The default safety_level for the main database is 'full'; for the temp

   896   ** database it is 'NONE'. This matches the pager layer defaults.  

   897   */

   898   db->aDb[0].zName = "main";

   899   db->aDb[0].safety_level = 3;

   900 #ifndef SQLITE_OMIT_TEMPDB

   901   db->aDb[1].zName = "temp";

   902   db->aDb[1].safety_level = 1;

   903 #endif

   904 

   905   /* Register all built-in functions, but do not attempt to read the

   906   ** database schema yet. This is delayed until the first time the database

   907   ** is accessed.

   908   */

   909   if( !sqlite3MallocFailed() ){

   910     sqlite3RegisterBuiltinFunctions(db);

   911     sqlite3Error(db, SQLITE_OK, 0);

   912   }

   913   db->magic = SQLITE_MAGIC_OPEN;

   914 

   915   /* Load automatic extensions - extensions that have been registered

   916   ** using the sqlite3_automatic_extension() API.

   917   */

   918   (void)sqlite3AutoLoadExtensions(db);

   919 

   920 #ifdef SQLITE_ENABLE_FTS1

   921   {

   922     extern int sqlite3Fts1Init(sqlite3*);

   923     sqlite3Fts1Init(db);

   924   }

   925 #endif

   926 

   927 opendb_out:

   928   if( SQLITE_NOMEM==(rc = sqlite3_errcode(db)) ){

   929     sqlite3_close(db);

   930     db = 0;

   931   }

   932   *ppDb = db;

   933   return sqlite3ApiExit(0, rc);

   934 }

   935 

   936 /*

   937 ** Open a new database handle.

   938 */

   939 int sqlite3_open(

   940   const char *zFilename, 

   941   sqlite3 **ppDb 

   942 ){

   943   return openDatabase(zFilename, ppDb);

   944 }

   945 

   946 #ifndef SQLITE_OMIT_UTF16

   947 /*

   948 ** Open a new database handle.

   949 */

   950 EXPORT_C int sqlite3_open16(

   951   const void *zFilename, 

   952   sqlite3 **ppDb

   953 ){

   954   char const *zFilename8;   /* zFilename encoded in UTF-8 instead of UTF-16 */

   955   int rc = SQLITE_OK;

   956   sqlite3_value *pVal;

   957 

   958   assert( zFilename );

   959   assert( ppDb );

   960   *ppDb = 0;

   961   pVal = sqlite3ValueNew();

   962   sqlite3ValueSetStr(pVal, -1, zFilename, SQLITE_UTF16NATIVE, SQLITE_STATIC);

   963   zFilename8 = sqlite3ValueText(pVal, SQLITE_UTF8);

   964   if( zFilename8 ){

   965     rc = openDatabase(zFilename8, ppDb);

   966     if( rc==SQLITE_OK && *ppDb ){

   967       rc = sqlite3_exec(*ppDb, "PRAGMA encoding = 'UTF-16'", 0, 0, 0);

   968       if( rc!=SQLITE_OK ){

   969         sqlite3_close(*ppDb);

   970         *ppDb = 0;

   971       }

   972     }

   973   }

   974   sqlite3ValueFree(pVal);

   975 

   976   return sqlite3ApiExit(0, rc);

   977 }

   978 #endif /* SQLITE_OMIT_UTF16 */

   979 

   980 /*

   981 ** The following routine destroys a virtual machine that is created by

   982 ** the sqlite3_compile() routine. The integer returned is an SQLITE_

   983 ** success/failure code that describes the result of executing the virtual

   984 ** machine.

   985 **

   986 ** This routine sets the error code and string returned by

   987 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().

   988 */

   989 EXPORT_C int sqlite3_finalize(sqlite3_stmt *pStmt){

   990   int rc;

   991   if( pStmt==0 ){

   992     rc = SQLITE_OK;

   993   }else{

   994     rc = sqlite3VdbeFinalize((Vdbe*)pStmt);

   995   }

   996   return rc;

   997 }

   998 

   999 /*

  1000 ** Terminate the current execution of an SQL statement and reset it

  1001 ** back to its starting state so that it can be reused. A success code from

  1002 ** the prior execution is returned.

  1003 **

  1004 ** This routine sets the error code and string returned by

  1005 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().

  1006 */

  1007 EXPORT_C int sqlite3_reset(sqlite3_stmt *pStmt){

  1008   int rc;

  1009   if( pStmt==0 ){

  1010     rc = SQLITE_OK;

  1011   }else{

  1012     rc = sqlite3VdbeReset((Vdbe*)pStmt);

  1013     sqlite3VdbeMakeReady((Vdbe*)pStmt, -1, 0, 0, 0);

  1014   }

  1015   return rc;

  1016 }

  1017 

  1018 /*

  1019 ** Register a new collation sequence with the database handle db.

  1020 */

  1021 int sqlite3_create_collation(

  1022   sqlite3* db, 

  1023   const char *zName, 

  1024   int enc, 

  1025   void* pCtx,

  1026   int(*xCompare)(void*,int,const void*,int,const void*)

  1027 ){

  1028   int rc;

  1029   assert( !sqlite3MallocFailed() );

  1030   rc = createCollation(db, zName, enc, pCtx, xCompare);

  1031   return sqlite3ApiExit(db, rc);

  1032 }

  1033 

  1034 #ifndef SQLITE_OMIT_UTF16

  1035 /*

  1036 ** Register a new collation sequence with the database handle db.

  1037 */

  1038 int sqlite3_create_collation16(

  1039   sqlite3* db, 

  1040   const char *zName, 

  1041   int enc, 

  1042   void* pCtx,

  1043   int(*xCompare)(void*,int,const void*,int,const void*)

  1044 ){

  1045   int rc = SQLITE_OK;

  1046   char *zName8; 

  1047   assert( !sqlite3MallocFailed() );

  1048   zName8 = sqlite3utf16to8(zName, -1);

  1049   if( zName8 ){

  1050     rc = createCollation(db, zName8, enc, pCtx, xCompare);

  1051     sqliteFree(zName8);

  1052   }

  1053   return sqlite3ApiExit(db, rc);

  1054 }

  1055 #endif /* SQLITE_OMIT_UTF16 */

  1056 

  1057 /*

  1058 ** Register a collation sequence factory callback with the database handle

  1059 ** db. Replace any previously installed collation sequence factory.

  1060 */

  1061 int sqlite3_collation_needed(

  1062   sqlite3 *db, 

  1063   void *pCollNeededArg, 

  1064   void(*xCollNeeded)(void*,sqlite3*,int eTextRep,const char*)

  1065 ){

  1066   if( sqlite3SafetyCheck(db) ){

  1067     return SQLITE_MISUSE;

  1068   }

  1069   db->xCollNeeded = xCollNeeded;

  1070   db->xCollNeeded16 = 0;

  1071   db->pCollNeededArg = pCollNeededArg;

  1072   return SQLITE_OK;

  1073 }

  1074 

  1075 #ifndef SQLITE_OMIT_UTF16

  1076 /*

  1077 ** Register a collation sequence factory callback with the database handle

  1078 ** db. Replace any previously installed collation sequence factory.

  1079 */

  1080 int sqlite3_collation_needed16(

  1081   sqlite3 *db, 

  1082   void *pCollNeededArg, 

  1083   void(*xCollNeeded16)(void*,sqlite3*,int eTextRep,const void*)

  1084 ){

  1085   if( sqlite3SafetyCheck(db) ){

  1086     return SQLITE_MISUSE;

  1087   }

  1088   db->xCollNeeded = 0;

  1089   db->xCollNeeded16 = xCollNeeded16;

  1090   db->pCollNeededArg = pCollNeededArg;

  1091   return SQLITE_OK;

  1092 }

  1093 #endif /* SQLITE_OMIT_UTF16 */

  1094 

  1095 #ifndef SQLITE_OMIT_GLOBALRECOVER

  1096 /*

  1097 ** This function is now an anachronism. It used to be used to recover from a

  1098 ** malloc() failure, but SQLite now does this automatically.

  1099 */

  1100 int sqlite3_global_recover(){

  1101   return SQLITE_OK;

  1102 }

  1103 #endif

  1104 

  1105 /*

  1106 ** Test to see whether or not the database connection is in autocommit

  1107 ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on

  1108 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled

  1109 ** by the next COMMIT or ROLLBACK.

  1110 **

  1111 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******

  1112 */

  1113 int sqlite3_get_autocommit(sqlite3 *db){

  1114   return db->autoCommit;

  1115 }

  1116 

  1117 #ifdef SQLITE_DEBUG

  1118 /*

  1119 ** The following routine is subtituted for constant SQLITE_CORRUPT in

  1120 ** debugging builds.  This provides a way to set a breakpoint for when

  1121 ** corruption is first detected.

  1122 */

  1123 int sqlite3Corrupt(void){

  1124   return SQLITE_CORRUPT;

  1125 }

  1126 #endif

  1127 

  1128 

  1129 #ifndef SQLITE_OMIT_SHARED_CACHE

  1130 /*

  1131 ** Enable or disable the shared pager and schema features for the

  1132 ** current thread.

  1133 **

  1134 ** This routine should only be called when there are no open

  1135 ** database connections.