lib/sqlite/sqlite3.c

47 ** These #defines should enable >2GB file support on POSIX if the
49 ** large file support, or if the OS is windows, these should be no-ops.
61 ** portability you should omit LFS.
121 ** tell you that in a well-normalized database, you usually should
342 #if defined(__PTRDIFF_TYPE__)  /* This case should work for GCC */
395 ** will cause HeapValidate to be called.  If heap validation should fail, an
569 ** notice, and should not be referenced by programs that use SQLite.
613 ** should not use deprecated interfaces - they are support for backwards
614 ** compatibility only.  Application writers should be aware that
745 ** the mutexes.  But for maximum safety, mutexes should be enabled.
876 ** To avoid memory leaks, the application should invoke [sqlite3_free()]
983 ** over time.  Software that uses extended result codes should expect
1186 ** Applications that define a custom xFileControl method should use opcodes
1187 ** greater than 100 to avoid conflicts.  VFS implementations should
1277 ** by the user. The fourth argument to [sqlite3_file_control()] should
1293 ** VFSes do not need this signal and should silently ignore this opcode.
1294 ** Applications should not call [sqlite3_file_control()] with this
1323 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1376 ** implementation should use the pNext pointer.
1381 ** The application should never modify anything within the sqlite3_vfs
1441 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1450 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1452 ** It is <i>not</i> used to indicate the file should be opened
1458 ** allocate the structure; it should just fill it in.  Note that
1475 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1476 ** handled as a fatal error by SQLite, vfs implementations should endeavor
1672 ** The application should never invoke either sqlite3_os_init()
1673 ** or sqlite3_os_end() directly.  The application should only invoke
1771 ** xSize should return the allocated size of a memory allocation
1786 ** [sqlite3_shutdown()] and should deallocate any resources acquired
1825 ** should check the return code from [sqlite3_config()] to make sure that
1914 ** N should be set to twice the expected maximum number of threads.
1923 ** This configuration should not be used if an application-define page
1927 ** The sz argument should be the size of the largest database page
1932 ** argument should point to an allocation of at least sz*N bytes of memory.
2062 ** should check the return code from [sqlite3_db_config()] to make sure that
2092 ** [foreign key constraints].  There should be two additional arguments.
2102 ** There should be two additional arguments.
2387 ** The busy callback should not take any actions which modify the
2440 ** A result table should be deallocated using [sqlite3_free_table()].
2506 ** The strings returned by these two routines should be
2571 ** This second example is an SQL syntax error.  As a general rule you should
2617 ** should neither be read nor written.  Even reading previously freed
2727 ** see if those actions are allowed.  ^The authorizer callback should
2788 ** schema change.  Hence, the application should ensure that the
2954 ** associated with the [database connection] handle should be released by
3000 ** the new database connection should use.  ^If the fourth parameter is
3008 ** a ":" character you should prefix the filename with a pathname such as
3049 **     a VFS object that provides the operating system interface that should
3845 ** explicit transaction then you should rollback the transaction before
3849 ** successfully.  sqlite3_step() should not be called again on this virtual
3859 ** violation) has occurred.  sqlite3_step() should not be called again on
3932 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
3957 ** should be returned. ^The leftmost column of the result set has the index 0.
4087 ** In other words, you should call sqlite3_column_text(),
4216 ** encoding is used, then the fourth argument should be [SQLITE_ANY].
4311 ** to be supported.  However, new applications should avoid
4502 ** the near future and that SQLite should make its own private copy of
4704 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
4758 ** The callback function should register the desired collation using
4775 ** Specify the key for an encrypted database.  This routine should be
4862 ** Hence, if this variable is modified directly, either it should be
4864 ** or else the use of the [temp_store_directory pragma] should be avoided.
5040 ** cache setting should set it explicitly.
5117 ** only.  All new applications should use the
5214 ** should free this memory by calling [sqlite3_free()].
5265 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
5406 ** particular lookup.  A full scan of a table with N entries should have
5407 ** a cost of N.  A binary search of a table of N entries should have a
5417      int iTermOffset;          /* Used internally - xBestIndex should ignore */
5502 ** string obtained from [sqlite3_mprintf()] to zErrMsg.  The method should
5642 ** To avoid a resource leak, every open [BLOB handle] should eventually
5884 ** use by SQLite only.  Applications that use SQLite mutexes should
6027 ** ^These routines should return true if the mutex in their argument
6032 ** versions of these routines, it should at least provide stubs that always
6036 ** the routine should return 1.   This seems counter-intuitive since
6042 ** interface should also return 1 when given a NULL pointer.
6142 ** Applications should not use any of these parameters or the
6320 ** might be discontinued. Applications should check the return code from
6553 ** cache implementation should use the value of the createFlag
6599 ** All resources associated with the specified cache should be freed. ^After
6657 ** There should be exactly one call to sqlite3_backup_finish() for each
6748 ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
6998 ** The callback function should normally return [SQLITE_OK].  ^If an error
7202 ** CONFLICT policy is REPLACE, the virtual table implementation should
7339 ** code should not attempt to access or modify the fields of this structure
8039 ** should be one of the following values. The integer values are assigned
8290 ** gets freed when the Vdbe is finalized so it still should be obtained
8292 ** function should *not* try to free the KeyInfo.
8817   ** and should not be accessed by other modules.
9150 ** for very large databases.  But one should test the page skipping logic
9242 ** NOTE:  source files should *not* #include this header file directly.
9243 ** Source files should #include the sqliteInt.h file and let that file
10090 #define UNPACKED_NEED_DESTROY  0x0002  /* apMem[]s should all be destroyed */
10530 ** is.  None of the fields in this object should be used outside of
10552 ** is intended to be private the the where.c module and should not be
10713 #define SF_Distinct        0x0001  /* Output should be DISTINCT */
11544 ** file.  Code should use the MACRO forms below, as the Varint32 versions
12062    /* All the rest should always be initialized to zero */
12144 ** An array of names of all compile-time options.  This array should
14305 ** functions.  This should be the only routine in this file with
15561 ** u.hdr.prevSize can be part of the data for that chunk and should
16333 ** on.  It should be found on mem5.aiFreelist[iLogsize].
16580 ** routine should return 0 without freeing pPrior.
17217 ** use by SQLite only.  Applications that use SQLite mutexes should
17478 ** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
17529 ** use by SQLite only.  Applications that use SQLite mutexes should
17894   ** (which should be the last to shutdown.) */
17939 ** use by SQLite only.  Applications that use SQLite mutexes should
18211 ** should call sqlite3MemoryAlarm.
19135   etByte flag_dp;            /* True if decimal point should be shown */
19136   etByte flag_rtz;           /* True if trailing zeros should be removed */
20513 ** is set to the length of the returned string in bytes. The call should
20660   ** Systems that support the isnan() library function should probably
20669   **      This option [-ffast-math] should never be turned on by any
20720 **      %z      A string that should be freed after use
20729 ** should be called with err_code set to SQLITE_OK and zFormat set
20753 **      %z      A string that should be freed after use
20758 ** This function should be used to report any error that occurs whilst
20762 ** Function sqlite3Error() should be used during statement execution
21247 ** is provided which inlines the single-byte case.  All code should use
21450 ** single-byte case.  All code should use the MACRO version as
21641 ** Log an error that is an API call on a connection pointer that should
21657 ** 1 it means that the db pointer is valid and 0 if it should not be
21658 ** dereferenced for any reason.  The calling function should invoke
22312 ** This file should be #included by the os_*.c files only.  It is not a
22321 ** switch.  The following code should catch this problem at compile-time.
22426   ** of the debugging and testing utilities, but it should at
22967       /* This should never happen.  We should always be able to
23988   ** The handle should not be inherited by child processes and we don't
24301 ** a buffer of nBuf bytes. The OS layer should populate the
24307 ** it should be truncated. The return value of xGetLastError
24397 ** KEEP THE STRUCTURE OF THIS FILE INTACT.  New code should be placed
24398 ** in the correct division and should be clearly labeled.
24459 ** These #defines should enable >2GB file support on Posix if the
24461 ** large file support, these should be no-ops.
24469 ** portability you should omit LFS.
24473 ** you should probably leave LFS enabled.  But some embedded platforms might
24654 ** This file should be #included by the os_*.c files only.  It is not a
24663 ** switch.  The following code should catch this problem at compile-time.
24768   ** of the debugging and testing utilities, but it should at
25206 ** should handle ENOLCK, ENOTSUP, EOPNOTSUPP separately.
25212   ** should never be hit, as this function should only be called after
25215   ** errno should be non-zero.
25218   ** SQLITE_OK. The system call failed, and *some* SQLite error should be
25278     /* these should force the client to close the file and reconnect */
25572 ** The first argument passed to the macro should be the error code that
25574 ** The two subsequent arguments should be the name of the OS function that
27587   ** file), the bytes in the locking range should never be read or written. */
27667   ** file), the bytes in the locking range should never be read or written. */
27761 ** The idea behind dataOnly is that it should only write the file content
29121   /* Usually the path zFilename should not be a relative pathname. The
30808                  ** we should never get here except via the 'continue' call. */
31241 ** should be the only routines in this file that are visible from other
31247 ** should not be used.
31431 ** This file should be #included by the os_*.c files only.  It is not a
31440 ** switch.  The following code should catch this problem at compile-time.
31545   ** of the debugging and testing utilities, but it should at
32188 ** The first argument passed to the macro should be the error code that
32190 ** The two subsequent arguments should be the name of the OS function that
32235 ** to see if it should be retried.  Return TRUE to retry.  Return FALSE
32406     /* The following blocks should probably assert in debug mode, but they
33139       /* This should never happen.  We should always be able to
34688 ** a buffer of nBuf bytes. The OS layer should populate the
34694 ** it should be truncated. The return value of xGetLastError
35972 ** All code in this file should access the global structure above via the
36365 ** for all page cache needs and we should not need to spill the
37870 **      last reference is dropped the pager should move back to OPEN state).
38456       ** in ERROR state. Otherwise the pager should have already dropped
38722 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
39468       ** file should be closed and deleted. If this connection writes to
39806     /* No page should ever be explicitly rolled back that is in use, except
40108 ** If the nRec value is 0xffffffff it means that nRec should be computed
40213     ** should be computed based on the journal file size.
40249           ** case, the database should have never been written in the
40268   /* Following a rollback, the database file should be back in its original
40363       ** of bytes 24..39 of the database.  Bytes 28..31 should always be
40365       ** should be page numbers which are never 0xffffffff.  So filling
40366       ** pPager->dbFileVers[] with all 0xff bytes should suffice.
40371       ** we should still be ok.
41789 ** in *ppPager. The pager should eventually be freed by passing it
41804 ** operation of the pager. It should be passed some bitwise combination
42243   ** outstanding pages. This implies that the pager state should either
42359         ** assert_pager_state() would fail now, as it should not be possible
42839   ** again. This should not happen, but the check provides robustness. */
42883         /* We should never write to the journal file the page that
43231 ** of a master journal file that should be written into the individual
43462   /* This routine should not be called if a prior error has occurred.
44505 ** The wal-index is transient.  After a crash, the wal-index can (and should
44643 ** of available reader locks and should be at least 3.
45603 ** A SHARED lock should be held on the database file when this function
45872 ** The calling routine should invoke walIteratorFree() to destroy the
46404   ** Circumstances that cause a RETRY should only last for the briefest
46406   ** locks are held, so the locks should not be held for very long. But
47272 ** should acquire the database exclusive lock prior to invoking
47283   ** locks are taken in this case). Nor should the pager attempt to
47583 ** the string itself should be 15 characters long.  If you change
47873 **   should return the error code stored in BtCursor.skip
48042   ** connected by pNext and pPrev should be in sorted order by
48043   ** Btree.pBt value. All elements of the list should belong to
48055   /* We should already hold a lock on the database connection */
48059   ** should already be set correctly. */
48066   /* In most cases, we should be able to acquire the lock we
48300 ** is empty, the offset should be 65536, but the 2-byte value stores zero.
48370 ** caller should have first obtained a lock specifying the root page of
48409   /* Figure out the root-page that the lock should be held on. For table
48457 ** rooted at page iRoot, one should call:
48568   /* This function should only be called on a sharable b-tree after it
48765 **      from the database or written to the journal file (why should it
48812 ** Clear (destroy) the BtShared.pHasContent bitvec. This should be
49243   /* The value returned by this function should always be the same as
49805 ** read should occur at that point.
49885 ** Release a MemPage.  This should be called once for each prior
50601     /* If the write version is set to 2, this database should be accessed
51274 ** the database file should be truncated to during the commit process.
51355 ** the name of a master journal file that should be written into the
51359 ** When this is called, the master journal should already have been
51426 ** sqlite3BtreeCommitPhaseOne() routine does the first phase and should
51803 ** or negative rowids are very uncommon so this should not be a problem.
51815 ** return value indicates that the rowid cache is invalid and should be
52339 ** Hence, a mutex on the BtShared should be held prior to calling
53380       ** to 3.6.0 or later) we should consider fixing the conditional above
53470       /* There is no reason any cursor should have an outstanding reference
53747   /* The cell should normally be sized correctly.  However, when moving a
53809 ** Add a list of cells to a page.  The page should be initially empty.
54096 ** in a corrupted state. So if this routine fails, the database should
54349   ** cntNew[k] should equal nCell.
54471   ** n is never more than NB (a small constant), that should
54918 ** define what table the record should be inserted into.  The cursor
54965   ** expecting an index b-tree, then the caller should be inserting blob
54967   ** intkey table, the caller should be inserting integer keys with a
55231     ** root page of the new table should go. meta[3] is the largest root-page
55541     ** This really never should happen except in a corrupt
56294 ** blob of allocated memory. The xFree function should not call sqlite3_free()
57136   ** checks this assumption - (p->rc) should be set to either SQLITE_DONE
58588 ** invoke directly or indirectly. It should be used as follows:
59006 ** caller should not free the allocation, it will be freed when the Vdbe is
59302 ** this routine is N*N.  But as N is rarely more than 1, this should not
59470   ** listing has finished and sqlite3_step() should return SQLITE_DONE.
59676 ** this routine should not allocate any new memory.  When pBuf is not
59720   /* There should be at least one opcode.
60057   /* This loop determines (a) if the commit hook should be invoked and
60326   ** statement transaction that should be closed here. The only exception
60621 ** After this routine is run, the VDBE should be ready to be executed
60937 ** Developers using SQLite on an ARM7 should compile and run their
61142 ** stack space). If the former, then *ppFree is set to a pointer that should
61153   char **ppFree                   /* OUT: Caller should free this pointer */
61161   ** it by.  If pSpace is already 8-byte aligned, nOff should be zero.
61389   /* The last field of the index should be an integer - the ROWID.
61985   /* At this point local variable rc holds the value that should be
62201 ** implementations should keep their own counts within their aggregate
62386 **    0      The column name as it should be displayed for output
62780 ** should call sqlite3TransferBindings.
63555   ** of the debugging and testing utilities, but it should at
63645 ** After this routine has finished, sqlite3VdbeFinalize() should be
64231 ** indentation conventions, each case should be indented by 6 spaces.  But
64339 ** or sqlite3_finalize().  For a normal halt, this should be SQLITE_OK (0).
65383 ** OP_Halt, or OP_ResultRow.  Typically the OP_Permutation should occur
65652 ** register has changed should have this bit set.
65953 ** string indicates the column affinity that should be used for the nth
65983 ** string indicates the column affinity that should be used for the nth
66175       ** savepoint (and therefore should not prompt xSavepoint()) callbacks.
66589 ** values need not be contiguous but all P1 values should be small integers.
68147 ** the end of the index key pointed to by cursor P1.  This integer should be
69705 ** The cases of the switch statement above this line should all be indented
69787   ** should hold the error number.
70909   /* See if the contents of the sorter should now be written out. They
71528   /* An in-memory journal file should only ever be appended to. Random
71687 ** The return value from the callback should be one of the WRC_*
72097     ** Note that the expression in the result set should have already been
72455 ** as an indication to the caller that it should sort by the i-th column.
72516     "%r %s BY term out of range - should be "
73002 ** All SELECT statements should have been expanded using
73149 ** type affinity that should be used for the comparison operator.
73175 ** pExpr is a comparison operator.  Return the type affinity that should
73214 ** Return the P5 value that should be used for a binary comparison
73224 ** Return a pointer to the collation sequence that should be used by
73681 ** (2) the EP_xxx flags that indicate what the structure size should be.
74043 ** pList might be NULL following an OOM error.  But pName should never be
74068 ** pList might be NULL following an OOM error.  But pSpan should never be
76692 ** This routine should only be called after the expression has been
77374   /* The VDBE should have been allocated before this routine is called.
77852         ** value that should be stored in the sqlite_stat2 table. If so,
78010 ** in pTab that should be analyzed.
78945 ** should return either SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.  If
78949 ** should run but attempts to read the specified column will return NULL
79011 ** The pExpr should be a TK_COLUMN expression.  The table referred to
79374   assert( pParse->nested<10 );  /* Nesting should only be of limited depth */
79846 ** flag is true if the table should be stored in the auxiliary database
80637   ** should have been put there by the sqliteOpenCb routine.)
81341          " should reference only one column of table %T",
81802   /* Check to see if we should honor DESC requests on index columns
82064 ** how aiRowEst[] should be initialized.  The numbers generated here
82713 ** is set if the setStatement parameter is true.  A checkpoint should
82718 ** necessary to undo a write and the checkpoint should not be set.
83623   SrcList *pTabList,     /* The table from which we should delete things */
85756 ** TODO: How should dropping a table be handled? How should renaming a
86157   ** The collation sequence used for the comparison should be that of
86158   ** the parent key columns. The affinity of the parent key column should
86367   /* Exactly one of regOld and regNew should be non-zero. */
86501         ** the constraint, the FK should specify NO ACTION (represented
87140 ** This routine should be called when the top of the stack holds a
87501     ** should be written into a temporary table (template 4).  Set to
88301 ** The arguments to this routine should be the same as the first six
88484 ** of the conditions above fail so that the optimization should not
88740 ** other files are for internal use by SQLite and should not be
88908 ** as extensions by SQLite should #include this file instead of
89425 ** Extensions that use newer APIs should first call the
89427 ** intend to use is supported by the library.  Extensions should
89566   ** before calling APIs that follow, extension should check the
89693 ** error message text.  The calling function should free this memory
89981 ** should be passed into sqlite3BtreeSetSafetyLevel().  The is done
90651   ** N should be a positive integer.
91593     ** constraint for a CREATE TABLE.  The index should have already
91617 ** database.  iDb==1 should never be used.  iDb>=2 is used for
91986   ** function should never be used.
92997     ** then there should be a single item on the stack.  Write this
93395         ** though it should really be "INTEGER".
93779 ** iOffset should have been preset to appropriate default values
93795   ** contraversy about what the correct behavior should be.
93804     if( NEVER(v==0) ) return;  /* VDBE should have already been allocated */
93927     sqlite3ErrorMsg(pParse,"ORDER BY clause should come after %s not before",
93933     sqlite3ErrorMsg(pParse,"LIMIT clause should come after %s not before",
94255 ** pIn->nMem columns to be output.  pDest is where the output should
94326     ** then there should be a single item on the stack.  Write this
96251   ** an optimization - the correct answer should result regardless.
96751         **     where.c should not iterate over any values with a NULL value
96755         **     index or indices to use) should place a different priority on
97050 ** Instead, the entire table should be passed to sqlite3_free_table() when
98163 ** is the instruction that control should jump to if a trigger program
98193     /* Determine whether we should code this trigger */
98350   SrcList *pTabList,     /* The table in which we should change things */
99377 ** Locks nest.  Every lock should have a corresponding unlock.
99880 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
100057 ** Set *pzErrmsg to point to a buffer that should be released using
100676 ** WhereTerms.  All pointers to WhereTerms should be invalidated after
102945 ** then nEq should be passed the value 1 (as the range restricted column,
102950 ** then nEq should be passed 0.
103884 ** no conversion should be attempted before using a t2.b value as part of
104122   int iLevel,          /* Which level of pWInfo->a[] should be coded */
104388     ** should not have a NULL value stored in 'x'. If column 'x' is
104813 ** should invoke sqlite3WhereEnd() with the return value of this function
104929   ** pTabList.  But if the WHERE_ONETABLE_ONLY flag is set, then we should
105123         int doNotReorder;    /* True if this table should not be reordered */
105698 **                       have fall-back values which should be used if the
105766 ** code the yytestcase() macro should be turned off.  But it is useful
105802 ** and that yy_default[S] should be used instead.
106425 ** <li> A FILE* to which trace output should be written.
107028 ** <li>  A pointer to the parser.  This should be a pointer
110071 ** other files are for internal use by SQLite and should not be
110239 ** calls to this routine should not block, of course.  Otherwise the
110264   ** to sqlite3_initialize() should be a no-op.  But the initialization
110428 ** This routine should only be called when there are no outstanding
111351 ** should call this routine to make sure the global function exists.
111602 ** The mutex on database handle db should be held by the caller. The mutex
111638 ** This function returns true if main-memory should be used instead of
111955 ** itself. When this function is called the *pFlags variable should contain
111961 ** the VFS that should be used to open the database file. *pzFile is set to
112078     /* Check if there were any options specified that should be interpreted
113005     ** operation N should be 0.  The idea is that a test program (like the
113646 ** and a new root interior node is generated (which should always fit
113836   ** This method should return either SQLITE_OK (0), or an SQLite error
113837   ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
113839   ** sqlite3_tokenizer.pModule variable should not be initialised by
113873   ** method should either return SQLITE_OK and set the values of the
113877   ** *ppToken should be set to point at a buffer containing the
113879   ** stemming has been performed). *pnBytes should be set to the length
113882   ** *piEndOffset. *piStartOffset should be set to the index of the first
113883   ** byte of the token in the input buffer. *piEndOffset should be set
113892   ** nul-terminated.  This should either be fixed, or pInput/nBytes
113893   ** should be converted to zInput.
113949 ** code should not attempt to access or modify the fields of this structure
114281 ** indicating that all columns should be searched,
114295   int bFreeList;                 /* True if pList should be sqlite3_free()d */
114350 ** The aMI array is allocated using sqlite3_malloc(). It should be freed
116257 ** should be false. If they are sorted in ascending order, it should be
116354 ** parameter bDescDoclist should be false. If they are sorted in ascending
116355 ** order, it should be passed a non-zero value.
116965 ** rowid should be written to *pRowid.
118232   /* Determine which, if any, tokens in the expression should be deferred. */
118608         ** then any snippet() should ony highlight the "a" term, not the "b"
119135   /* The user should specify a single argument - the name of an fts3 table. */
120256 ** array, which is assumed to contain nCol entries, should contain the names
120260 ** The iDefaultCol parameter should be passed the index of the table column
120404 ** expression parser. It should be called as follows:
120559 ** true if the hash table should make its own private copy of keys and
120560 ** false if it should just use the supplied pointer.
123227 ** performance improvement, but the blob handle should always be closed
124186 ** *ppWriter. When adding the first term to a segment, *ppWriter should
125424   ** should be deleted from the database before inserting the new row. Or,
126080     /* Ideally, the start of the snippet should be pushed forward in the
126208     /* Set isHighlight to true if this term should be highlighted. */
126227 ** row). When this function is called, *ppCollist should point to the
128408       ** and then a linear search of an R-Tree node. This should be
130627 ** should be invoked with two arguments. The second argument is the name