diff --git a/manifest b/manifest index d00e840a20..096e086db0 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Begin\sadding\srequirements\snumbers\sto\sthe\sC/C++\sinterface\sdocumentation.\s(CVS\s4593) -D 2007-12-05T18:05:16 +C Continuing\swork\son\sthe\sC/C++\sinterface\srequirements\sthat\sappears\sas\ncomments\sin\ssqlite.h.in.\s(CVS\s4594) +D 2007-12-06T02:42:08 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7 F Makefile.in 30789bf70614bad659351660d76b8e533f3340e9 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -134,7 +134,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da F src/select.c 7c0ab94b8f287eb94fdb1eb101be603832ecfc34 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96 F src/shell.c c97be281cfc3dcb14902f45e4b16f20038eb83ff -F src/sqlite.h.in b886a911e1e72e3f79fb1d66553ce5c717042267 +F src/sqlite.h.in 544587c10005dde0ad8f132dd9b7816b132b2bea F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb F src/sqliteInt.h a941ccf797b45c27bc0face4e75935b5cc019202 F src/sqliteLimit.h 15ffe2116746c27ace2b428a26a4fcd6dba6fa65 @@ -597,7 +597,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5 -P bdfc19e838b369a8c5d5d23663fad690f55ba3d7 -R 9ef2020d3fc9ded9ecb9c3353fddc20a +P ae1936aadf00bec91750d41be7507cf1b81fc411 +R 7ac7d80a2d75b3b7bb12edb35b1b87a6 U drh -Z d0c1d862b6e3beefc5bad47c02091c37 +Z ee325aa2259ef8ee38a408857daf2088 diff --git a/manifest.uuid b/manifest.uuid index dd0ae2debf..d379b71530 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -ae1936aadf00bec91750d41be7507cf1b81fc411 \ No newline at end of file +2130e7125187ca46df3f65237f933b0e568a36ed \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index b2186892ac..565908249c 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.275 2007/12/05 18:05:16 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.276 2007/12/06 02:42:08 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -65,14 +65,12 @@ extern "C" { /* ** CAPI3REF: Compile-Time Library Version Numbers {F10010} ** -** {F10011} The version of the SQLite library is contained in the sqlite3.h -** header file in a #define named SQLITE_VERSION. {F10012} The SQLITE_VERSION -** macro resolves to a string constant. -** -** {F10013} The format of the version string is "X.Y.Z", where +** {F10011} The #define in the sqlite3.h header file named +** SQLITE_VERSION resolves to a string literal that identifies +** the version of the SQLite library in the format "X.Y.Z", where ** X is the major version number, Y is the minor version number and Z ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". -** For example "3.1.1beta". {END} +** {END} For example "3.1.1beta". ** ** The X value is always 3 in SQLite. The X value only changes when ** backwards compatibility is broken and we intend to never break @@ -81,11 +79,12 @@ extern "C" { ** but not backwards compatible. The Z value is incremented with ** each release but resets back to 0 when Y is incremented. ** -** {F10014} The SQLITE_VERSION_NUMBER is an integer with the value -** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", +** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are as +** with SQLITE_VERSION. {END} For example, for version "3.1.1beta", ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using ** version 3.1.1 or greater at compile time, programs may use the test -** (SQLITE_VERSION_NUMBER>=3001001). {END} +** (SQLITE_VERSION_NUMBER>=3001001). ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. */ @@ -95,9 +94,9 @@ extern "C" { /* ** CAPI3REF: Run-Time Library Version Numbers {F10020} ** -** {F10021} These routines return values equivalent to the header constants -** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. {END} The values returned -** by this routines should only be different from the header values +** {F10021} The sqlite3_libversion_number() interface returns an integer +** equal to [SQLITE_VERSION_NUMBER]. {END} The value returned +** by this routine should only be different from the header values ** if the application is compiled using an sqlite3.h header from a ** different version of SQLite than library. Cautious programmers might ** include a check in their application to verify that @@ -106,7 +105,8 @@ extern "C" { ** ** {F10022} The sqlite3_version[] string constant contains the text of the ** [SQLITE_VERSION] string. {F10023} The sqlite3_libversion() function returns -** a poiner to the sqlite3_version[] string constant. {END} The function +** a pointer to the sqlite3_version[] string constant. {END} The +** sqlite3_libversion() function ** is provided for DLL users who can only access functions and not ** constants within the DLL. */ @@ -117,19 +117,20 @@ int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** -** {F10101} This routine returns TRUE (nonzero) if SQLite was compiled with -** all of its mutexes enabled and is thus threadsafe. {F10102} It returns -** zero if the particular build is for single-threaded operation -** only. {END} +** {F10101} The sqlite3_threadsafe() routine returns nonzero +** if SQLite was compiled with its mutexes enabled or zero if +** SQLite was compiled with mutexes disabled. {END} If this +** routine returns false, then it is not safe for simultaneously +** running threads to both invoke SQLite interfaces. ** -** {F10103} Really all this routine does is return true if SQLite was +** Really all this routine does is return true if SQLite was ** compiled with the -DSQLITE_THREADSAFE=1 option and false if -** compiled with -DSQLITE_THREADSAFE=0. {U10104} If SQLite uses an +** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an ** application-defined mutex subsystem, malloc subsystem, collating ** sequence, VFS, SQL function, progress callback, commit hook, ** extension, or other accessories and these add-ons are not ** threadsafe, then clearly the combination will not be threadsafe -** either. {END} Hence, this routine never reports that the library +** either. Hence, this routine never reports that the library ** is guaranteed to be threadsafe, only when it is guaranteed not ** to be. */ @@ -187,18 +188,19 @@ typedef sqlite_uint64 sqlite3_uint64; /* ** CAPI3REF: Closing A Database Connection {F12010} ** -** {F12010} Call this function with a pointer to a structure that was -** previously returned from [sqlite3_open()], [sqlite3_open16()], or -** [sqlite3_open_v2()] and the corresponding database will by -** closed. {END} +** {F12011} The sqlite3_close() interfaces destroys an [sqlite3] object +** allocated by a prior call to [sqlite3_open()], [sqlite3_open16()], or +** [sqlite3_open_v2()]. {F12012} Sqlite3_close() releases all +** memory used by the connection and closes all open files. {END}. ** -** {F12011} All SQL statements prepared using [sqlite3_prepare_v2()] or -** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] -** before this routine is called. Otherwise, SQLITE_BUSY is returned and the -** database connection remains open. {END} +** {F12013} If the database connection contains +** [sqlite3_stmt | prepared statements] that have not been finalized +** by [sqlite3_finalize()], then sqlite3_close() returns SQLITE_BUSY +** and leaves the connection open. {F12014} Giving sqlite3_close() +** a NULL pointer is a harmless no-op. {END} ** -** {U12012} Passing this routine a database connection that has already been -** closed results in undefined behavior. {U12013} If other interfaces that +** {U12015} Passing this routine a database connection that has already been +** closed results in undefined behavior. {U12016} If other interfaces that ** reference the same database connection are pending (either in the ** same thread or in different threads) when this routine is called, ** then the behavior is undefined and is almost certainly undesirable. @@ -216,10 +218,10 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** CAPI3REF: One-Step Query Execution Interface {F12100} ** ** {F12101} The sqlite3_exec() interface evaluates zero or more -** UTF-8 encoded, semicolon-separated SQL -** statements provided as its second argument. {F12102} The SQL +** UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated +** string of its second argument. {F12102} The SQL ** statements are evaluated in the context of the database connection -** provided in the first argument. +** specified by in the first argument. ** {F12103} SQL statements are prepared one by one using ** [sqlite3_prepare()] or the equivalent, evaluated ** using one or more calls to [sqlite3_step()], then destroyed @@ -243,7 +245,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** is an array of pointers to strings holding the values for each column ** as extracted using [sqlite3_column_text()]. NULL values in the result ** set result in a NULL pointer. All other value are in their UTF-8 -** string representation. {F12110} +** string representation. {F12117} ** The 4th parameter to the callback is an array of strings ** obtained using [sqlite3_column_name()] and holding ** the names of each column, also in UTF-8. @@ -255,9 +257,16 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** {F12112} If an error occurs while parsing or evaluating the SQL ** then an appropriate error message is written into memory obtained ** from [sqlite3_malloc()] and *errmsg is made to point to that message -** assuming errmsg is not NULL. {U12113} The calling function -** is responsible for freeing the memory using [sqlite3_free()]. -** {F12114} If errmsg==NULL, then no error message is ever written. +** assuming errmsg is not NULL. +** {U12113} The calling function is responsible for freeing the memory +** using [sqlite3_free()]. +** {F12116} If [sqlite3_malloc()] fails while attempting to generate +** the error message, *errmsg is set to NULL. +** {F12114} If errmsg is NULL then no attempt is made to generate an +** error message. Is the return code SQLITE_NOMEM or the original +** error code? What happens if there are multiple errors? +** Do we get code for the first error, or is the choice of reported +** error arbitrary? ** ** {F12115} The return value is is SQLITE_OK if there are no errors and ** some other [SQLITE_OK | return code] if there is an error. @@ -278,8 +287,8 @@ int sqlite3_exec( ** Many SQLite functions return an integer result code from the set shown ** above in order to indicates success or failure. ** -** {F10211} The result codes above are the only ones returned by SQLite in its -** default configuration. {F10212} However, the +** {F10211} The result codes shown here are the only ones returned +** by SQLite in its default configuration. {F10212} However, the ** [sqlite3_extended_result_codes()] API can be used to set a database ** connectoin to return more detailed result codes. {END} ** @@ -322,9 +331,9 @@ int sqlite3_exec( ** CAPI3REF: Extended Result Codes {F10220} ** ** In its default configuration, SQLite API routines return one of 26 integer -** [result codes]. However, experience has shown that +** [SQLITE_OK | result codes]. However, experience has shown that ** many of these result codes are too course-grained. They do not provide as -** much information about problems as users might like. In an effort to +** much information about problems as programmers might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information ** about errors. {F10221} The extended result codes are enabled or disabled @@ -573,8 +582,8 @@ struct sqlite3_io_methods { ** CAPI3REF: Mutex Handle {F17110} ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an -** abstract type for a mutex object. The SQLite core never looks -** at the internal representation of an [sqlite3_mutex]. It only +** abstract type for a mutex object. {F17111} The SQLite core never looks +** at the internal representation of an [sqlite3_mutex]. {END} It only ** deals with pointers to the [sqlite3_mutex] object. ** ** Mutexes are created using [sqlite3_mutex_alloc()]. @@ -611,20 +620,21 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** -** SQLite will guarantee that the zFilename string passed to +** {F11141} SQLite will guarantee that the zFilename string passed to ** xOpen() is a full pathname as generated by xFullPathname() and ** that the string will be valid and unchanged until xClose() is -** called. So the [sqlite3_file] can store a pointer to the +** called. {END} So the [sqlite3_file] can store a pointer to the ** filename if it needs to remember the filename for some reason. ** -** The flags argument to xOpen() is a copy of the flags argument -** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()] -** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. +** {F11142} The flags argument to xOpen() includes all bits set in +** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] +** or [sqlite3_open16()] is used, then flags includes at least +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} ** If xOpen() opens a file read-only then it sets *pOutFlags to ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be ** set. ** -** SQLite will also add one of the following flags to the xOpen() +** {F11143} SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: ** ** +** {END} ** ** The file I/O implementation can use the object type flags to ** changes the way it deals with files. For example, an application @@ -646,7 +656,7 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** be doing page-aligned sector reads and writes in a random order ** and set up its I/O subsystem accordingly. ** -** SQLite might also add one of the following flags to the xOpen +** {F11144} SQLite might also add one of the following flags to the xOpen ** method: ** ** ** -** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be -** deleted when it is closed. This will always be set for TEMP -** databases and journals and for subjournals. The -** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened +** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be +** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] +** will be set for TEMP databases, journals and for subjournals. +** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except -** for the main database file. +** for the main database file. {END} ** -** Space to hold the [sqlite3_file] structure passed as the third -** argument to xOpen is allocated by caller (the SQLite core). -** szOsFile bytes are allocated for this object. The xOpen method -** fills in the allocated space. +** {F11148} At least szOsFile bytes of memory is allocated by SQLite +** to hold the [sqlite3_file] structure passed as the third +** argument to xOpen. {END} The xOpen method does not have to +** allocate the structure; it should just fill it in. ** -** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] +** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existance of a file, ** or [SQLITE_ACCESS_READWRITE] to test to see ** if a file is readable and writable, or [SQLITE_ACCESS_READ] -** to test to see if a file is at least readable. The file can be a +** to test to see if a file is at least readable. {END} The file can be a ** directory. ** -** SQLite will always allocate at least mxPathname+1 byte for -** the output buffers for xGetTempname and xFullPathname. The exact +** {F11150} SQLite will always allocate at least mxPathname+1 byte for +** the output buffers for xGetTempname and xFullPathname. {F11151} The exact ** size of the output buffer is also passed as a parameter to both -** methods. If the output buffer is not large enough, SQLITE_CANTOPEN +** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN ** should be returned. As this is handled as a fatal error by SQLite, -** vfs implementations should endevour to prevent this by setting +** vfs implementations should endeavor to prevent this by setting ** mxPathname to a sufficiently large value. ** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces @@ -718,15 +728,15 @@ struct sqlite3_vfs { }; /* -** CAPI3REF: Flags for the xAccess VFS method {F11150} +** CAPI3REF: Flags for the xAccess VFS method {F11190} ** -** {F11151} These integer constants can be used as the third parameter to +** {F11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine ** the kind of what kind of permissions the xAccess method is -** looking for. {F11152} With SQLITE_ACCESS_EXISTS, the xAccess method -** simply checks to see if the file exists. {F11153} With +** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method +** simply checks to see if the file exists. {F11193} With ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see -** if the file is both readable and writable. {F11154} With +** if the file is both readable and writable. {F11194} With ** SQLITE_ACCESS_READ the xAccess method ** checks to see if the file is readable. */ @@ -737,8 +747,10 @@ struct sqlite3_vfs { /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} ** -** {F12201} This routine enables or disables the -** [SQLITE_IOERR_READ | extended result codes] feature. {F12202} +** {F12201} The sqlite3_extended_result_codes() routine enables or disables the +** [SQLITE_IOERR_READ | extended result codes] feature on a database +** connection if its 2nd parameter is +** non-zero or zero, respectively. {F12202} ** By default, SQLite API routines return one of only 26 integer ** [SQLITE_OK | result codes]. {F12203} When extended result codes ** are enabled by this routine, the repetoire of result codes can be @@ -799,12 +811,12 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); ** triggers are not counted. {F12243} Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** -** {F12244} Within the body of a trigger, the sqlite3_changes() interface can be -** called to find the number of +** {F12244} Within the body of a trigger, the sqlite3_changes() interface +** can be called to find the number of ** changes in the most recently completed INSERT, UPDATE, or DELETE -** statement within the body of the trigger. +** statement within the body of the same trigger. ** -** {F12245} All changes are counted, even if they were later undone by a +** {F12245} All changes are counted, even if they are later undone by a ** ROLLBACK or ABORT. {F12246} Except, changes associated with creating and ** dropping tables are not counted. ** @@ -840,8 +852,9 @@ int sqlite3_changes(sqlite3*); ** ** See also the [sqlite3_change()] interface. ** -** SQLite implements the command "DELETE FROM table" without a WHERE clause -** by dropping and recreating the table. (This is much faster than going +** {F12265} SQLite implements the command "DELETE FROM table" without +** a WHERE clause by dropping and recreating the table. (This is much +** faster than going ** through and deleting individual elements form the table.) Because of ** this optimization, the change count for "DELETE FROM table" will be ** zero regardless of the number of elements that were originally in the @@ -868,10 +881,15 @@ int sqlite3_total_changes(sqlite3*); ** is not safe to call this routine with a database connection that ** is closed or might close before sqlite3_interrupt() returns. ** +** If an SQL is very nearly finished at the time when sqlite3_interrupt() +** is called, then it might not have an opportunity to be interrupted. +** It might continue to completion. ** {F12274} The SQL operation that is interrupted will return -** [SQLITE_INTERRUPT]. {F12275} If an interrupted operation was an -** update that is inside an explicit transaction, then the entire -** transaction will be rolled back automatically. +** [SQLITE_INTERRUPT]. {F12275} If the interrupted SQL operation is an +** INSERT, UPDATE, or DELETE that is inside an explicit transaction, +** then the entire transaction will be rolled back automatically. +** {F12276} A call to sqlite3_interrupt() has no effect on SQL statements +** that are started after sqlite3_interrupt() returns. */ void sqlite3_interrupt(sqlite3*); @@ -879,13 +897,13 @@ void sqlite3_interrupt(sqlite3*); ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510} ** ** These routines are useful for command-line input to determine if the -** currently entered text forms one or more complete SQL statements or -** if additional input is needed before sending the statements into +** currently entered text seems to form complete a SQL statement or +** if additional input is needed before sending the text into ** SQLite for parsing. These routines return true if the input string ** appears to be a complete SQL statement. A statement is judged to be ** complete if it ends with a semicolon and is not a fragment of a ** CREATE TRIGGER statement. These routines do not parse the SQL and -** will not detect syntactically incorrect SQL. +** so will not detect syntactically incorrect SQL. ** ** {F10511} These functions return true if the given input string ** ends with a semicolon optionally followed by whitespace or @@ -909,7 +927,7 @@ int sqlite3_complete16(const void *sql); ** invoked whenever an attempt is made to open a database table ** that another thread or process has locked. ** {F12312} If the busy callback is NULL, then [SQLITE_BUSY] -** (or sometimes [SQLITE_IOERR_BLOCKED]) +** or [SQLITE_IOERR_BLOCKED] ** is returned immediately upon encountering the lock. ** {F12313} If the busy callback is not NULL, then the ** callback will be invoked with two arguments. {F12314} The @@ -922,23 +940,24 @@ int sqlite3_complete16(const void *sql); ** {F12317} If the callback returns non-zero, then another attempt ** is made to open the database for reading and the cycle repeats. ** -** {U12318} The presence of a busy handler does not guarantee that -** it will be invoked when there is lock contention. +** The presence of a busy handler does not guarantee that +** it will be invoked when there is lock contention. {F12319} ** If SQLite determines that invoking the busy handler could result in -** a deadlock, it will return [SQLITE_BUSY] instead. {END} +** a deadlock, it will go ahead and return [SQLITE_BUSY] or +** [SQLITE_IOERR_BLOCKED] instead of invoking the +** busy handler. {END} ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying ** to promote to an exclusive lock. The first process cannot proceed ** because it is blocked by the second and the second process cannot ** proceed because it is blocked by the first. If both processes -** invoke the busy handlers, neither will make any progress. -** {F12319} Therefore, +** invoke the busy handlers, neither will make any progress. Therefore, ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this ** will induce the first process to release its read lock and allow ** the second process to proceed. ** -** {F12321} The default busy callback is NULL. +** {F12321} The default busy callback is NULL. {END} ** ** {F12322} The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] ** when SQLite is in the middle of a large transaction where all the @@ -972,14 +991,15 @@ int sqlite3_complete16(const void *sql); ** So if two database connections share a single cache, then changing ** the busy handler on one connection will also change the busy ** handler in the other connection. {F12332} The busy handler is invoked -** in the thread that was running when the SQLITE_BUSY was hit. +** in the thread that was running when the lock contention occurs. */ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* ** CAPI3REF: Set A Busy Timeout {F12340} ** -** {F12341} This routine sets a busy handler that sleeps for a while when a +** {F12341} This routine sets a [sqlite3_busy_handler | busy handler] +** that sleeps for a while when a ** table is locked. {F12342} The handler will sleep multiple times until ** at least "ms" milliseconds of sleeping have been done. {F12343} After ** "ms" milliseconds of sleeping, the handler returns 0 which @@ -1153,9 +1173,10 @@ char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem {F17300} ** -** {F17301} The SQLite core (not counting operating-system specific VFS -** implementations) uses these three routines for all of its own -** internal memory allocation needs. {END} +** {F17301} The SQLite core uses these three routines for all of its own +** internal memory allocation needs. {END} "Core" in the previous sentence +** does not include operating-system specific VFS implementation. The +** windows VFS uses native malloc and free for some operations. ** ** {F17302} The sqlite3_malloc() routine returns a pointer to a block ** of memory at least N bytes in length, where N is the parameter. @@ -1192,6 +1213,9 @@ char *sqlite3_snprintf(int,char*,const char*, ...); ** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation ** is not freed. ** +** {F17316} The memory returned by sqlite3_malloc() and sqlite3_realloc() +** is always aligned to at least an 8 byte boundary. {END} +** ** {F17381} The default implementation ** of the memory allocation subsystem uses the malloc(), realloc() ** and free() provided by the standard C library. {F17382} However, if @@ -1210,7 +1234,7 @@ char *sqlite3_snprintf(int,char*,const char*, ...); ** is no longer provided. Only built-in memory allocators can be ** used. ** -** Exception: The windows OS interface layer calls +** The windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite ** and whatever filename encoding is used by the particular windows @@ -1236,10 +1260,12 @@ void sqlite3_free(void*); ** any overhead added by SQLite, but not overhead added by the ** library malloc() that backs the sqlite3_malloc() implementation. ** {F17373} The sqlite3_memory_highwater() routines returns the -** maximum number of bytes that have been outstanding since the -** highwater mark was last reset. +** maximum number of bytes that have been outstanding at any time +** since the highwater mark was last reset. ** {F17374} The byte count returned by sqlite3_memory_highwater() -** uses the same byte counting rules as sqlite3_memory_used(). +** uses the same byte counting rules as sqlite3_memory_used(). {END} +** In other words, overhead added internally by SQLite is counted, +** but overhead from the underlying system malloc is not. ** {F17375} If the parameter to sqlite3_memory_highwater() is true, ** then the highwater mark is reset to the current value of ** sqlite3_memory_used() and the prior highwater mark (before the @@ -1260,20 +1286,28 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag); ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. {F12503} At various ** points during the compilation process, as logic is being created ** to perform various actions, the authorizer callback is invoked to -** see if those actions are allowed. {X12504} The authorizer callback should +** see if those actions are allowed. The authorizer callback should ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be -** rejected with an error. {END} +** rejected with an error. {F12504} If the authorizer callback returns +** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] +** then [sqlite3_prepare_v2()] or equivalent call that triggered +** the authorizer shall +** fail with an SQLITE_ERROR error code and an appropriate error message. {END} ** -** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return -** codes might mean something different or they might mean the same -** thing. If the action is, for example, to perform a delete opertion, -** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation -** to fail with an error. But if the action is to read a specific column -** from a specific table, then [SQLITE_DENY] will cause the entire -** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be -** read instead of the actual column value. +** When the callback returns [SQLITE_OK], that means the operation +** requested is ok. {F12505} When the callback returns [SQLITE_DENY], the +** [sqlite3_prepare_v2()] or equivalent call that triggered the +** authorizer shall fail +** with an SQLITE_ERROR error code and an error message explaining that +** access is denied. {F12506} If the authorizer code (the 2nd parameter +** to the authorizer callback is anything other than [SQLITE_READ], then +** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. +** If the authorizer code is [SQLITE_READ] and the callback returns +** [SQLITE_IGNORE] then the prepared statement is constructed to +** insert a NULL value in place of the table column that would have +** been read if [SQLITE_OK] had been returned. {END} ** ** {F12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the sqlite3_set_authorizer() interface. @@ -1311,7 +1345,7 @@ int sqlite3_set_authorizer( ); /* -** CAPI3REF: Authorizer Return Codes {F12505} +** CAPI3REF: Authorizer Return Codes {F12590} ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order @@ -1323,20 +1357,20 @@ int sqlite3_set_authorizer( #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ /* -** CAPI3REF: Authorizer Action Codes +** CAPI3REF: Authorizer Action Codes {F12550} ** ** The [sqlite3_set_authorizer()] interface registers a callback function -** that is invoked to authorizer certain SQL statement actions. The +** that is invoked to authorizer certain SQL statement actions. {F12551} The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that -** the authorizer callback may be passed. +** the authorizer callback may be passed. {END} ** ** These action code values signify what kind of operation is to be -** authorized. The 3rd and 4th parameters to the authorization callback -** function will be parameters or NULL depending on which of these -** codes is used as the second parameter. The 5th parameter to the +** authorized. {F12552} The 3rd and 4th parameters to the authorization +** callback function will be parameters or NULL depending on which of these +** codes is used as the second parameter. {F12553} The 5th parameter to the ** authorizer callback is the name of the database ("main", "temp", -** etc.) if applicable. The 6th parameter to the authorizer callback +** etc.) if applicable. {F12554} The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. @@ -1376,21 +1410,33 @@ int sqlite3_set_authorizer( #define SQLITE_COPY 0 /* No longer used */ /* -** CAPI3REF: Tracing And Profiling Functions {F12290} +** CAPI3REF: Tracing And Profiling Functions {F12280} ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. ** -** {F12291} The callback function registered by sqlite3_trace() is invoked +** {F12281} The callback function registered by sqlite3_trace() is invoked ** at the first [sqlite3_step()] for the evaluation of an SQL statement. -** {F12292} Only a single trace callback can be registered at a time. -** Each call to sqlite3_trace() overrides the previous. {F12293} A -** NULL callback for sqlite3_trace() disables tracing. -** -** {F12295} The callback function registered by sqlite3_profile() is invoked -** as each SQL statement finishes and includes -** information on how long that statement ran.{END} +** {F12282} Only a single trace callback can be registered at a time. +** Each call to sqlite3_trace() overrides the previous. {F12283} A +** NULL callback for sqlite3_trace() disables tracing. {F12284} The +** first argument to the trace callback is a copy of the pointer which +** was the 3rd argument to sqlite3_trace. {F12285} The second argument +** to the trace callback is a zero-terminated UTF8 string containing +** the original text of the SQL statement as it was passed into +** [sqlite3_prepare_v2()] or the equivalent. {END} Note that the +** host parameter are not expanded in the SQL statement text. ** +** {F12287} The callback function registered by sqlite3_profile() is invoked +** as each SQL statement finishes. {F12288} The first parameter to the +** profile callback is a copy of the 3rd parameter to sqlite3_profile(). +** {F12289} The second parameter to the profile callback is a +** zero-terminated UTF-8 string that contains the complete text of +** the SQL statement as it was processed by [sqlite3_prepare_v2()] or +** the equivalent. {F12290} The third parameter to the profile +** callback is an estimate of the number of nanoseconds of +** wall-clock time required to run the SQL statement from start +** to finish. {END} ** ** The sqlite3_profile() API is currently considered experimental and ** is subject to change. @@ -1462,7 +1508,7 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); ** to [sqlite3_close()] when it is no longer required. ** ** {F12709} The [sqlite3_open_v2()] interface works like [sqlite3_open()] -** except that provides two additional parameters for additional control +** except that it acccepts two additional parameters for additional control ** over the new database connection. {F12710} The flags parameter can be ** one of: ** @@ -1563,8 +1609,8 @@ const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {F13000} ** -** Instance of this object represent single SQL statements. This -** is variously known as a "prepared statement" or a +** An instance of this object represent single SQL statements. This +** object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". ** ** The life of a statement object goes something like this: @@ -1603,17 +1649,18 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** than zero, then zSql is read up to the first zero terminator. ** {F13014} If nByte is non-negative, then it is the maximum number of ** bytes read from zSql. When nByte is non-negative, the -** zSql string ends at either the first '\000' character or +** zSql string ends at either the first '\000' or '\u0000' character or ** until the nByte-th byte, whichever comes first. {END} ** ** {F13015} *pzTail is made to point to the first byte past the end of the -** first SQL statement in zSql. This routine only compiles the first statement -** in zSql, so *pzTail is left pointing to what remains uncompiled. {END} +** first SQL statement in zSql. These routines only compiles the first +** statement in zSql, so *pzTail is left pointing to what remains +** uncompiled. {END} ** ** {F13016} *ppStmt is left pointing to a compiled ** [sqlite3_stmt | SQL statement structure] that can be ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be -** set to NULL. {F13017} If the input text contained no SQL (if the input +** set to NULL. {F13017} If the input text contains no SQL (if the input ** is and empty string or a comment) then *ppStmt is set to NULL. ** {U13018} The calling procedure is responsible for deleting the ** compiled SQL statement @@ -1696,7 +1743,8 @@ int sqlite3_prepare16_v2( ** pointer is valid until the statement ** is deleted using sqlite3_finalize(). ** {F13103} The string returned by sqlite3_sql() is always UTF8 even -** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()]. +** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()] +** or the equivalent. ** ** {F13104} If the statement was compiled using either of the legacy ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this @@ -1707,10 +1755,11 @@ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {F15000} ** -** SQLite uses dynamic typing for the values it stores. Values can -** be integers, floating point values, strings, BLOBs, or NULL. When -** passing around values internally, each value is represented as -** an instance of the sqlite3_value object. +** {F15001} SQLite uses the sqlite3_value object to represent all values +** that are or can be stored in a database table. {END} +** SQLite uses dynamic typing for the values it stores. +** {F15002} Values stored in sqlite3_value objects can be +** be integers, floating point values, strings, BLOBs, or NULL. */ typedef struct Mem sqlite3_value; @@ -1718,8 +1767,8 @@ typedef struct Mem sqlite3_value; ** CAPI3REF: SQL Function Context Object {F16001} ** ** The context in which an SQL function executes is stored in an -** sqlite3_context object. A pointer to such an object is the -** first parameter to user-defined SQL functions. +** sqlite3_context object. {F16002} A pointer to an sqlite3_context +** object is always first parameter to application-defined SQL functions. */ typedef struct sqlite3_context sqlite3_context; @@ -1727,7 +1776,7 @@ typedef struct sqlite3_context sqlite3_context; ** CAPI3REF: Binding Values To Prepared Statements {F13500} ** ** {F13501} In the SQL strings input to [sqlite3_prepare_v2()] and its -** variants, one or more literals can be replace by a parameter in one +** variants, literals may be replace by a parameter in one ** of these forms: ** **