More documentation spellcheck and cleanup. No changes to code. (CVS 5260)
FossilOrigin-Name: 8c457fb08b93aa1aa9f62d0ec31755d74416e16b
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
C Fix\sa\sproblem\sin\sthe\stest\ssuite\sthat\scould\scause\sa\scrash\sif\susing\sa\spre-allocated\sblock\sof\smemory\sfor\spages\s(the\sproblem\swas\sthat\ssqlite3_shutdown()\swas\sbeing\scalled\swhile\sthere\swere\sstill\sopen\sdatabase\sconnections).\s(CVS\s5259)
|
||||
D 2008-06-21T08:12:15
|
||||
C More\sdocumentation\sspellcheck\sand\scleanup.\sNo\schanges\sto\scode.\s(CVS\s5260)
|
||||
D 2008-06-21T11:20:48
|
||||
F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7
|
||||
F Makefile.in ff6f90048555a0088f6a4b7406bed5e55a7c4eff
|
||||
F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
|
||||
@@ -143,7 +143,7 @@ F src/printf.c 8b063da9dcde26b7c500a01444b718d86f21bc6e
|
||||
F src/random.c 5c754319d38abdd6acd74601ee0105504adc508a
|
||||
F src/select.c 8393c47a170923f40602622bfa59b8e7cbff9027
|
||||
F src/shell.c a12ea645271b7876c8f080146f48e20b00d367ec
|
||||
F src/sqlite.h.in 27af4a9f16fcd9f877f66e211442f0b964d0e415
|
||||
F src/sqlite.h.in b38a20988588df2467722d5e0be9a3e66bec7203
|
||||
F src/sqlite3ext.h f162a72daef5ebf8b211fe8c0ec96e85d22fbf9b
|
||||
F src/sqliteInt.h 005b2f0aa10acd20435b46d4a9f84e20855c6f35
|
||||
F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
|
||||
@@ -600,7 +600,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
|
||||
F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
|
||||
F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1
|
||||
F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
|
||||
P 2904d26ba43b0ded5b43f696ba2d8cd19d4244de
|
||||
R c113c331a7360a8ae8154a587ec4ebd9
|
||||
U danielk1977
|
||||
Z 424aee893f8bd1e1c8ade0a3dc854ce4
|
||||
P 3d413e9b466a871650597407016131df4d07b3d2
|
||||
R 3068395447a488d855036458cdac3d08
|
||||
U mihailim
|
||||
Z cc370ba2bcd1d75c705436aa5f9d6ee7
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
3d413e9b466a871650597407016131df4d07b3d2
|
||||
8c457fb08b93aa1aa9f62d0ec31755d74416e16b
|
||||
+172
-197
@@ -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.343 2008/06/21 06:16:43 mihailim Exp $
|
||||
** @(#) $Id: sqlite.h.in,v 1.344 2008/06/21 11:20:48 mihailim Exp $
|
||||
*/
|
||||
#ifndef _SQLITE3_H_
|
||||
#define _SQLITE3_H_
|
||||
@@ -1026,8 +1026,8 @@ struct sqlite3_mem_methods {
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_MALLOC</dt>
|
||||
** <dd>This option takes a single argument which is a pointer to an
|
||||
** instance of the [sqlite3_mem_methods] structure. The argument specifics
|
||||
** alternative low-level memory allocation routines to be used in place
|
||||
** instance of the [sqlite3_mem_methods] structure. The argument specifies
|
||||
** alternative low-level memory allocation routines to be used in place of
|
||||
** the memory allocation routines built into SQLite.</dd>
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_GETMALLOC</dt>
|
||||
@@ -1057,27 +1057,23 @@ struct sqlite3_mem_methods {
|
||||
** argument must be a multiple of 16. The first
|
||||
** argument should point to an allocation of at least (sz+4)*N bytes of memory.
|
||||
** SQLite will use no more than one scratch buffer at once per thread, so
|
||||
** N should be set to the expected maximum number of threads. The sz
|
||||
** N should be set to the expected maximum number of threads. The sz
|
||||
** parameter should be 6 times the size of the largest database page size.
|
||||
** Scratch buffers are used as part of the btree balance operation. If
|
||||
** The btree balancer needs additional memory beyond what is provided by
|
||||
** scratch buffers or if no scratch buffer space is specified, then SQLite
|
||||
** goes to [sqlite3_malloc()] to obtain the memory it needs.
|
||||
** </dd>
|
||||
** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_PAGECACHE</dt>
|
||||
** <dd>This option specifies a static memory buffer that SQLite can use for
|
||||
** the database page cache. There are three arguments:
|
||||
** A pointer to the memory, the
|
||||
** size of each page buffer (sz), and the number of pages (N). The sz
|
||||
** argument must be a power of two between 512 and 32768. The first
|
||||
** the database page cache. There are three arguments: A pointer to the
|
||||
** memory, the size of each page buffer (sz), and the number of pages (N).
|
||||
** The sz argument must be a power of two between 512 and 32768. The first
|
||||
** argument should point to an allocation of at least (sz+4)*N bytes of memory.
|
||||
** SQLite will use the memory provided by the first argument to satisfy
|
||||
** its memory needs for the first N pages that it adds to cache. If
|
||||
** additional page cache memory is needed beyond what is provided by
|
||||
** this option, then SQLite goes to [sqlite3_malloc()] for the additional
|
||||
** storage space.
|
||||
** </dd>
|
||||
** SQLite will use the memory provided by the first argument to satisfy its
|
||||
** memory needs for the first N pages that it adds to cache. If additional
|
||||
** page cache memory is needed beyond what is provided by this option, then
|
||||
** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd>
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_HEAP</dt>
|
||||
** <dd>This option specifies a static memory buffer that SQLite will use
|
||||
@@ -1087,12 +1083,11 @@ struct sqlite3_mem_methods {
|
||||
** bytes in the memory buffer, and the minimum allocation size. When
|
||||
** this configuration option is used, SQLite never calls the system
|
||||
** malloc() implementation but instead uses the supplied memory buffer
|
||||
** to satisfy all [sqlite3_malloc()] requests.
|
||||
** </dd>
|
||||
** to satisfy all [sqlite3_malloc()] requests.</dd>
|
||||
**
|
||||
** <dt>SQLITE_CONFIG_MUTEX</dt>
|
||||
** <dd>This option takes a single argument which is a pointer to an
|
||||
** instance of the [sqlite3_mutex_methods] structure. The argument specifics
|
||||
** instance of the [sqlite3_mutex_methods] structure. The argument specifies
|
||||
** alternative low-level mutex routines to be used in place
|
||||
** the mutex routines built into SQLite.</dd>
|
||||
**
|
||||
@@ -1119,25 +1114,22 @@ struct sqlite3_mem_methods {
|
||||
#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
|
||||
#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
|
||||
|
||||
|
||||
/*
|
||||
** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
|
||||
**
|
||||
** The sqlite3_extended_result_codes() routine enables or disables the
|
||||
** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
|
||||
** The extended result codes are disabled by default for historical
|
||||
** compatibility.
|
||||
** compatibility considerations.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
** {F12201} Each new [database connection] shall have the
|
||||
** [extended result codes] feature
|
||||
** disabled by default.
|
||||
** {F12201} Each new [database connection] shall have the
|
||||
** [extended result codes] feature disabled by default.
|
||||
**
|
||||
** {F12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable
|
||||
** [extended result codes] for the
|
||||
** [database connection] D if the F parameter
|
||||
** is true, or disable them if F is false.
|
||||
** [extended result codes] for the [database connection] D
|
||||
** if the F parameter is true, or disable them if F is false.
|
||||
*/
|
||||
int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
||||
|
||||
@@ -1152,44 +1144,42 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
||||
** is another alias for the rowid.
|
||||
**
|
||||
** This routine returns the rowid of the most recent
|
||||
** successful INSERT into the database from the database connection
|
||||
** shown in the first argument. If no successful inserts
|
||||
** have ever occurred on this database connection, zero is returned.
|
||||
** successful INSERT into the database from the [database connection]
|
||||
** in the first argument. If no successful INSERTs
|
||||
** have ever occurred on that database connection, zero is returned.
|
||||
**
|
||||
** If an INSERT occurs within a trigger, then the rowid of the
|
||||
** inserted row is returned by this routine as long as the trigger
|
||||
** is running. But once the trigger terminates, the value returned
|
||||
** by this routine reverts to the last value inserted before the
|
||||
** trigger fired.
|
||||
** If an INSERT occurs within a trigger, then the rowid of the inserted
|
||||
** row is returned by this routine as long as the trigger is running.
|
||||
** But once the trigger terminates, the value returned by this routine
|
||||
** reverts to the last value inserted before the trigger fired.
|
||||
**
|
||||
** An INSERT that fails due to a constraint violation is not a
|
||||
** successful insert and does not change the value returned by this
|
||||
** successful INSERT and does not change the value returned by this
|
||||
** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
|
||||
** and INSERT OR ABORT make no changes to the return value of this
|
||||
** routine when their insertion fails. When INSERT OR REPLACE
|
||||
** routine when their insertion fails. When INSERT OR REPLACE
|
||||
** encounters a constraint violation, it does not fail. The
|
||||
** INSERT continues to completion after deleting rows that caused
|
||||
** the constraint problem so INSERT OR REPLACE will always change
|
||||
** the return value of this interface.
|
||||
** the return value of this interface.
|
||||
**
|
||||
** For the purposes of this routine, an insert is considered to
|
||||
** For the purposes of this routine, an INSERT is considered to
|
||||
** be successful even if it is subsequently rolled back.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
** {F12221} The [sqlite3_last_insert_rowid()] function returns the
|
||||
** rowid of the most recent successful insert done
|
||||
** on the same database connection and within the same
|
||||
** or higher level trigger context, or zero if there have
|
||||
** been no qualifying inserts.
|
||||
** {F12221} The [sqlite3_last_insert_rowid()] function returns the rowid
|
||||
** of the most recent successful INSERT performed on the same
|
||||
** [database connection] and within the same or higher level
|
||||
** trigger context, or zero if there have been no qualifying inserts.
|
||||
**
|
||||
** {F12223} The [sqlite3_last_insert_rowid()] function returns
|
||||
** {F12223} The [sqlite3_last_insert_rowid()] function returns the
|
||||
** same value when called from the same trigger context
|
||||
** immediately before and after a ROLLBACK.
|
||||
**
|
||||
** LIMITATIONS:
|
||||
**
|
||||
** {U12232} If a separate thread does a new insert on the same
|
||||
** {U12232} If a separate thread performs a new INSERT on the same
|
||||
** database connection while the [sqlite3_last_insert_rowid()]
|
||||
** function is running and thus changes the last insert rowid,
|
||||
** then the value returned by [sqlite3_last_insert_rowid()] is
|
||||
@@ -1203,9 +1193,9 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
||||
**
|
||||
** This function returns the number of database rows that were changed
|
||||
** or inserted or deleted by the most recently completed SQL statement
|
||||
** on the connection specified by the first parameter. Only
|
||||
** changes that are directly specified by the INSERT, UPDATE, or
|
||||
** DELETE statement are counted. Auxiliary changes caused by
|
||||
** on the [database connection] specified by the first parameter.
|
||||
** Only changes that are directly specified by the INSERT, UPDATE,
|
||||
** or DELETE statement are counted. Auxiliary changes caused by
|
||||
** triggers are not counted. Use the [sqlite3_total_changes()] function
|
||||
** to find the total number of changes including changes caused by triggers.
|
||||
**
|
||||
@@ -1229,23 +1219,22 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
||||
** most recent INSERT, UPDATE, or DELETE statement within the same
|
||||
** trigger context.
|
||||
**
|
||||
** So when called from the top level, this function returns the
|
||||
** Thus, when called from the top level, this function returns the
|
||||
** number of changes in the most recent INSERT, UPDATE, or DELETE
|
||||
** that also occurred at the top level.
|
||||
** Within the body of a trigger, the sqlite3_changes() interface
|
||||
** can be called to find the number of
|
||||
** that also occurred at the top level. 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 same trigger.
|
||||
** However, the number returned does not include in changes
|
||||
** caused by subtriggers since they have their own context.
|
||||
** However, the number returned does not include changes
|
||||
** caused by subtriggers since those have their own context.
|
||||
**
|
||||
** 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 from the
|
||||
** table.) Because of this optimization, the deletions in
|
||||
** "DELETE FROM table" are not row changes and will not be counted
|
||||
** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
|
||||
** To get an accurate count of the number of rows deleted, use
|
||||
** 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 from the table.) Because of this
|
||||
** optimization, the deletions in "DELETE FROM table" are not row changes and
|
||||
** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
|
||||
** functions, regardless of the number of elements that were originally
|
||||
** in the table. To get an accurate count of the number of rows deleted, use
|
||||
** "DELETE FROM table WHERE 1" instead.
|
||||
**
|
||||
** INVARIANTS:
|
||||
@@ -1257,7 +1246,7 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
||||
** not been any qualifying row changes.
|
||||
**
|
||||
** {F12243} Statements of the form "DELETE FROM tablename" with no
|
||||
** WHERE clause shall cause subsequent calls to
|
||||
** WHERE clause shall cause subsequent calls to
|
||||
** [sqlite3_changes()] to return zero, regardless of the
|
||||
** number of rows originally in the table.
|
||||
**
|
||||
@@ -1271,40 +1260,37 @@ int sqlite3_changes(sqlite3*);
|
||||
|
||||
/*
|
||||
** CAPI3REF: Total Number Of Rows Modified {F12260}
|
||||
***
|
||||
** This function returns the number of row changes caused
|
||||
** by INSERT, UPDATE or DELETE statements since the database handle
|
||||
** was opened. The count includes all changes from all trigger
|
||||
** contexts. But the count does not include changes used to
|
||||
** implement REPLACE constraints, do rollbacks or ABORT processing,
|
||||
** or DROP table processing.
|
||||
** The changes
|
||||
** are counted as soon as the statement that makes them is completed
|
||||
** (when the statement handle is passed to [sqlite3_reset()] or
|
||||
**
|
||||
** This function returns the number of row changes caused by INSERT,
|
||||
** UPDATE or DELETE statements since the [database connection] was opened.
|
||||
** The count includes all changes from all trigger contexts. However,
|
||||
** the count does not include changes used to implement REPLACE constraints,
|
||||
** do rollbacks or ABORT processing, or DROP table processing.
|
||||
** The changes are counted as soon as the statement that makes them is
|
||||
** completed (when the statement handle is passed to [sqlite3_reset()] or
|
||||
** [sqlite3_finalize()]).
|
||||
**
|
||||
** 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 from 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
|
||||
** table. To get an accurate count of the number of rows deleted, use
|
||||
** 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 from the table.) Because of this
|
||||
** optimization, the deletions in "DELETE FROM table" are not row changes and
|
||||
** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
|
||||
** functions, regardless of the number of elements that were originally
|
||||
** in the table. To get an accurate count of the number of rows deleted, use
|
||||
** "DELETE FROM table WHERE 1" instead.
|
||||
**
|
||||
** See also the [sqlite3_changes()] interface.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
**
|
||||
** {F12261} The [sqlite3_total_changes()] returns the total number
|
||||
** of row changes caused by INSERT, UPDATE, and/or DELETE
|
||||
** statements on the same [database connection], in any
|
||||
** trigger context, since the database connection was
|
||||
** created.
|
||||
** trigger context, since the database connection was created.
|
||||
**
|
||||
** {F12263} Statements of the form "DELETE FROM tablename" with no
|
||||
** WHERE clause shall not change the value returned
|
||||
** by [sqlite3_total_changes()]
|
||||
** by [sqlite3_total_changes()].
|
||||
**
|
||||
** LIMITATIONS:
|
||||
**
|
||||
@@ -1319,22 +1305,24 @@ int sqlite3_total_changes(sqlite3*);
|
||||
**
|
||||
** This function causes any pending database operation to abort and
|
||||
** return at its earliest opportunity. This routine is typically
|
||||
** called in response to a user action such as pressing "Cancel"
|
||||
** called in response to an user action such as pressing "Cancel"
|
||||
** or Ctrl-C where the user wants a long query operation to halt
|
||||
** immediately.
|
||||
**
|
||||
** It is safe to call this routine from a thread different from the
|
||||
** thread that is currently running the database operation. But it
|
||||
** is not safe to call this routine with a database connection that
|
||||
** 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.
|
||||
** An SQL operation that is interrupted will return
|
||||
** [SQLITE_INTERRUPT]. 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.
|
||||
** If an SQL operation is very nearly finished at the time when
|
||||
** sqlite3_interrupt() is called, then it might not have an opportunity
|
||||
** to be interrupted and might continue to completion.
|
||||
**
|
||||
** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
|
||||
** 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.
|
||||
**
|
||||
** A call to sqlite3_interrupt() has no effect on SQL statements
|
||||
** that are started after sqlite3_interrupt() returns.
|
||||
**
|
||||
@@ -1342,8 +1330,7 @@ int sqlite3_total_changes(sqlite3*);
|
||||
**
|
||||
** {F12271} The [sqlite3_interrupt()] interface will force all running
|
||||
** SQL statements associated with the same database connection
|
||||
** to halt after processing at most one additional row of
|
||||
** data.
|
||||
** to halt after processing at most one additional row of data.
|
||||
**
|
||||
** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
|
||||
** will return [SQLITE_INTERRUPT].
|
||||
@@ -1369,16 +1356,15 @@ void sqlite3_interrupt(sqlite3*);
|
||||
** independent tokens (they are part of the token in which they are
|
||||
** embedded) and thus do not count as a statement terminator.
|
||||
**
|
||||
** These routines do not parse the SQL and
|
||||
** so will not detect syntactically incorrect SQL.
|
||||
** These routines do not parse the SQL statements thus
|
||||
** will not detect syntactically incorrect SQL.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
|
||||
** return true (non-zero) if and only if the last
|
||||
** non-whitespace token in their input is a semicolon that
|
||||
** is not in between the BEGIN and END of a CREATE TRIGGER
|
||||
** statement.
|
||||
** return true (non-zero) if and only if the last non-whitespace
|
||||
** token in their input is a semicolon that is not in between
|
||||
** the BEGIN and END of a CREATE TRIGGER statement.
|
||||
**
|
||||
** LIMITATIONS:
|
||||
**
|
||||
@@ -1394,29 +1380,27 @@ int sqlite3_complete16(const void *sql);
|
||||
/*
|
||||
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
|
||||
**
|
||||
** This routine identifies a callback function that might be
|
||||
** invoked whenever an attempt is made to open a database table
|
||||
** that another thread or process has locked.
|
||||
** If the busy callback is NULL, then [SQLITE_BUSY]
|
||||
** or [SQLITE_IOERR_BLOCKED]
|
||||
** is returned immediately upon encountering the lock.
|
||||
** If the busy callback is not NULL, then the
|
||||
** callback will be invoked with two arguments. The
|
||||
** first argument to the handler is a copy of the void* pointer which
|
||||
** is the third argument to this routine. The second argument to
|
||||
** the handler is the number of times that the busy handler has
|
||||
** been invoked for this locking event. If the
|
||||
** This routine sets a callback function that might be invoked whenever
|
||||
** an attempt is made to open a database table that another thread
|
||||
** or process has locked.
|
||||
**
|
||||
** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
|
||||
** is returned immediately upon encountering the lock. If the busy callback
|
||||
** is not NULL, then the callback will be invoked with two arguments.
|
||||
**
|
||||
** The first argument to the handler is a copy of the void* pointer which
|
||||
** is the third argument to sqlite3_busy_handler(). The second argument to
|
||||
** the handler callback is the number of times that the busy handler has
|
||||
** been invoked for this locking event. If the
|
||||
** busy callback returns 0, then no additional attempts are made to
|
||||
** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
|
||||
** If the callback returns non-zero, then another attempt
|
||||
** is made to open the database for reading and the cycle repeats.
|
||||
**
|
||||
** The presence of a busy handler does not guarantee that
|
||||
** it will be invoked when there is lock contention.
|
||||
** If SQLite determines that invoking the busy handler could result in
|
||||
** a deadlock, it will go ahead and return [SQLITE_BUSY] or
|
||||
** [SQLITE_IOERR_BLOCKED] instead of invoking the
|
||||
** busy handler.
|
||||
** The presence of a busy handler does not guarantee that it will be invoked
|
||||
** when there is lock contention. If SQLite determines that invoking the busy
|
||||
** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
|
||||
** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
|
||||
** 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
|
||||
@@ -1441,14 +1425,14 @@ int sqlite3_complete16(const void *sql);
|
||||
** code is promoted from the relatively benign [SQLITE_BUSY] to
|
||||
** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
|
||||
** forces an automatic rollback of the changes. See the
|
||||
** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
|
||||
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
|
||||
** CorruptionFollowingBusyError</a> wiki page for a discussion of why
|
||||
** this is important.
|
||||
**
|
||||
** There can only be a single busy handler defined for each database
|
||||
** connection. Setting a new busy handler clears any previous one.
|
||||
** Note that calling [sqlite3_busy_timeout()] will also set or clear
|
||||
** the busy handler.
|
||||
**
|
||||
** There can only be a single busy handler defined for each
|
||||
** [database connection]. Setting a new busy handler clears any
|
||||
** previously set handler. Note that calling [sqlite3_busy_timeout()]
|
||||
** will also set or clear the busy handler.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
@@ -1459,13 +1443,13 @@ int sqlite3_complete16(const void *sql);
|
||||
**
|
||||
** {F12312} The default busy handler for new database connections is NULL.
|
||||
**
|
||||
** {F12314} When two or more database connection share a [sqlite3_enable_shared_cache | common cache],
|
||||
** {F12314} When two or more database connection share a
|
||||
** [sqlite3_enable_shared_cache | common cache],
|
||||
** the busy handler for the database connection currently using
|
||||
** the cache is invoked when the cache encounters a lock.
|
||||
**
|
||||
** {F12316} If a busy handler callback returns zero, then the SQLite
|
||||
** interface that provoked the locking event will return
|
||||
** [SQLITE_BUSY].
|
||||
** {F12316} If a busy handler callback returns zero, then the SQLite interface
|
||||
** that provoked the locking event will return [SQLITE_BUSY].
|
||||
**
|
||||
** {F12318} SQLite will invokes the busy handler with two arguments which
|
||||
** are a copy of the pointer supplied by the 3rd parameter to
|
||||
@@ -1474,27 +1458,27 @@ int sqlite3_complete16(const void *sql);
|
||||
**
|
||||
** LIMITATIONS:
|
||||
**
|
||||
** {U12319} A busy handler should not call close the database connection
|
||||
** or prepared statement that invoked the busy handler.
|
||||
** {U12319} A busy handler should not close the database connection
|
||||
** or [prepared statement] that invoked the busy handler.
|
||||
*/
|
||||
int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
||||
|
||||
/*
|
||||
** CAPI3REF: Set A Busy Timeout {F12340}
|
||||
**
|
||||
** This routine sets a [sqlite3_busy_handler | busy handler]
|
||||
** that sleeps for a while when a
|
||||
** table is locked. 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
|
||||
** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
|
||||
** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
|
||||
** for a specified amount of time when a table is locked. The handler
|
||||
** will sleep multiple times until at least "ms" milliseconds of sleeping
|
||||
** have accumulated. {F12343} After "ms" milliseconds of sleeping,
|
||||
** the handler returns 0 which causes [sqlite3_step()] to return
|
||||
** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
|
||||
**
|
||||
** Calling this routine with an argument less than or equal to zero
|
||||
** turns off all busy handlers.
|
||||
**
|
||||
** There can only be a single busy handler for a particular database
|
||||
** connection. If another busy handler was defined
|
||||
** (using [sqlite3_busy_handler()]) prior to calling
|
||||
** There can only be a single busy handler for a particular
|
||||
** [database connection] any any given moment. If another busy handler
|
||||
** was defined (using [sqlite3_busy_handler()]) prior to calling
|
||||
** this routine, that other busy handler is cleared.
|
||||
**
|
||||
** INVARIANTS:
|
||||
@@ -1527,16 +1511,14 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
|
||||
** numbers are obtained separately. Let N be the number of rows
|
||||
** and M be the number of columns.
|
||||
**
|
||||
** A result table is an array of pointers to zero-terminated
|
||||
** UTF-8 strings. There are (N+1)*M elements in the array.
|
||||
** The first M pointers point to zero-terminated strings that
|
||||
** contain the names of the columns.
|
||||
** The remaining entries all point to query results. NULL
|
||||
** values are give a NULL pointer. All other values are in
|
||||
** their UTF-8 zero-terminated string representation as returned by
|
||||
** [sqlite3_column_text()].
|
||||
** A result table is an array of pointers to zero-terminated UTF-8 strings.
|
||||
** There are (N+1)*M elements in the array. The first M pointers point
|
||||
** to zero-terminated strings that contain the names of the columns.
|
||||
** The remaining entries all point to query results. NULL values result
|
||||
** in NULL pointers. All other values are in their UTF-8 zero-terminated
|
||||
** string representation as returned by [sqlite3_column_text()].
|
||||
**
|
||||
** A result table might consists of one or more memory allocations.
|
||||
** A result table might consist of one or more memory allocations.
|
||||
** It is not safe to pass a result table directly to [sqlite3_free()].
|
||||
** A result table should be deallocated using [sqlite3_free_table()].
|
||||
**
|
||||
@@ -1571,11 +1553,11 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
|
||||
** string of its 2nd parameter. It returns a result table to the
|
||||
** pointer given in its 3rd parameter.
|
||||
**
|
||||
** After the calling function has finished using the result, it should
|
||||
** pass the pointer to the result table to sqlite3_free_table() in order to
|
||||
** release the memory that was malloced. Because of the way the
|
||||
** After the calling function has finished using the result, it should
|
||||
** pass the pointer to the result table to sqlite3_free_table() in order to
|
||||
** release the memory that was malloced. Because of the way the
|
||||
** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
|
||||
** function must not try to call [sqlite3_free()] directly. Only
|
||||
** function must not try to call [sqlite3_free()] directly. Only
|
||||
** [sqlite3_free_table()] is able to release the memory properly and safely.
|
||||
**
|
||||
** The sqlite3_get_table() interface is implemented as a wrapper around
|
||||
@@ -1583,8 +1565,7 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
|
||||
** to any internal data structures of SQLite. It uses only the public
|
||||
** interface defined here. As a consequence, errors that occur in the
|
||||
** wrapper layer outside of the internal [sqlite3_exec()] call are not
|
||||
** reflected in subsequent calls to [sqlite3_errcode()] or
|
||||
** [sqlite3_errmsg()].
|
||||
** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
@@ -1594,19 +1575,18 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
|
||||
** *resultp output pointer to NULL and returns [SQLITE_NOMEM].
|
||||
**
|
||||
** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
|
||||
** then [sqlite3_get_table()] write the number of columns in the
|
||||
** then [sqlite3_get_table()] writes the number of columns in the
|
||||
** result set of the query into *ncolumn if the query is
|
||||
** successful (if the function returns SQLITE_OK).
|
||||
**
|
||||
** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
|
||||
** then [sqlite3_get_table()] write the number of rows in the
|
||||
** then [sqlite3_get_table()] writes the number of rows in the
|
||||
** result set of the query into *nrow if the query is
|
||||
** successful (if the function returns SQLITE_OK).
|
||||
**
|
||||
** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
|
||||
** to the number of columns in the result set of the query in the
|
||||
** sql parameter, or to zero if the query in sql has an empty
|
||||
** result set.
|
||||
** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value to the
|
||||
** number of columns in the result set of the query in the sql
|
||||
** parameter, or to zero if the query in sql has an empty result set.
|
||||
*/
|
||||
int sqlite3_get_table(
|
||||
sqlite3*, /* An open database */
|
||||
@@ -1661,7 +1641,7 @@ void sqlite3_free_table(char **result);
|
||||
** character it escapes that character and allows it to be inserted into
|
||||
** the string.
|
||||
**
|
||||
** For example, so some string variable contains text as follows:
|
||||
** For example, assume the string variable zText contains text as follows:
|
||||
**
|
||||
** <blockquote><pre>
|
||||
** char *zText = "It's a happy day!";
|
||||
@@ -1689,14 +1669,14 @@ void sqlite3_free_table(char **result);
|
||||
** INSERT INTO table1 VALUES('It's a happy day!');
|
||||
** </pre></blockquote>
|
||||
**
|
||||
** This second example is an SQL syntax error. As a general rule you
|
||||
** should always use %q instead of %s when inserting text into a string
|
||||
** literal.
|
||||
** This second example is an SQL syntax error. As a general rule you should
|
||||
** always use %q instead of %s when inserting text into a string literal.
|
||||
**
|
||||
** The %Q option works like %q except it also adds single quotes around
|
||||
** the outside of the total string. Or if the parameter in the argument
|
||||
** list is a NULL pointer, %Q substitutes the text "NULL" (without single
|
||||
** quotes) in place of the %Q option. {END} So, for example, one could say:
|
||||
** the outside of the total string. Additionally, if the parameter in the
|
||||
** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
|
||||
** single quotes) in place of the %Q option. {END} So, for example,
|
||||
** one could say:
|
||||
**
|
||||
** <blockquote><pre>
|
||||
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
|
||||
@@ -1722,12 +1702,11 @@ void sqlite3_free_table(char **result);
|
||||
** UTF-8 string into the buffer pointed to by the second parameter
|
||||
** provided that the first parameter is greater than zero.
|
||||
**
|
||||
** {F17407} The [sqlite3_snprintf()] interface does not writes slots of
|
||||
** {F17407} The [sqlite3_snprintf()] interface does not write slots of
|
||||
** its output buffer (the second parameter) outside the range
|
||||
** of 0 through N-1 (where N is the first parameter)
|
||||
** regardless of the length of the string
|
||||
** requested by the format specification.
|
||||
**
|
||||
*/
|
||||
char *sqlite3_mprintf(const char*,...);
|
||||
char *sqlite3_vmprintf(const char*, va_list);
|
||||
@@ -1768,7 +1747,7 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
|
||||
** If the second parameter to sqlite3_realloc() is zero or
|
||||
** negative then the behavior is exactly the same as calling
|
||||
** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
|
||||
** Sqlite3_realloc() returns a pointer to a memory allocation
|
||||
** sqlite3_realloc() returns a pointer to a memory allocation
|
||||
** of at least N bytes in size or NULL if sufficient memory is unavailable.
|
||||
** If M is the size of the prior allocation, then min(N,M) bytes
|
||||
** of the prior allocation are copied into the beginning of buffer returned
|
||||
@@ -1779,23 +1758,19 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
|
||||
** The memory returned by sqlite3_malloc() and sqlite3_realloc()
|
||||
** is always aligned to at least an 8 byte boundary. {END}
|
||||
**
|
||||
** The default implementation
|
||||
** of the memory allocation subsystem uses the malloc(), realloc()
|
||||
** and free() provided by the standard C library. {F17382} However, if
|
||||
** SQLite is compiled with the following C preprocessor macro
|
||||
**
|
||||
** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
|
||||
**
|
||||
** where <i>NNN</i> is an integer, then SQLite create a static
|
||||
** array of at least <i>NNN</i> bytes in size and use that array
|
||||
** for all of its dynamic memory allocation needs. {END} Additional
|
||||
** memory allocator options may be added in future releases.
|
||||
** The default implementation of the memory allocation subsystem uses
|
||||
** the malloc(), realloc() and free() provided by the standard C library.
|
||||
** {F17382} However, if SQLite is compiled with the
|
||||
** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i>
|
||||
** is an integer), then SQLite create a static array of at least
|
||||
** <i>NNN</i> bytes in size and uses that array for all of its dynamic
|
||||
** memory allocation needs. {END} Additional memory allocator options
|
||||
** may be added in future releases.
|
||||
**
|
||||
** In SQLite version 3.5.0 and 3.5.1, it was possible to define
|
||||
** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
|
||||
** implementation of these routines to be omitted. That capability
|
||||
** is no longer provided. Only built-in memory allocators can be
|
||||
** used.
|
||||
** is no longer provided. Only built-in memory allocators can be used.
|
||||
**
|
||||
** The Windows OS interface layer calls
|
||||
** the system malloc() and free() directly when converting
|
||||
@@ -1807,10 +1782,10 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to
|
||||
** newly checked-out block of at least N bytes of memory
|
||||
** that is 8-byte aligned,
|
||||
** or it returns NULL if it is unable to fulfill the request.
|
||||
** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to
|
||||
** a newly checked-out block of at least N bytes of memory
|
||||
** that is 8-byte aligned, or it returns NULL if it is unable
|
||||
** to fulfill the request.
|
||||
**
|
||||
** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
|
||||
** N is less than or equal to zero.
|
||||
@@ -1836,8 +1811,9 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
|
||||
** that is 8-byte aligned, or a NULL pointer.
|
||||
**
|
||||
** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
|
||||
** copies the first K bytes of content from P into the newly allocated
|
||||
** where K is the lesser of N and the size of the buffer P.
|
||||
** copies the first K bytes of content from P into the newly
|
||||
** allocated block, where K is the lesser of N and the size of
|
||||
** the buffer P.
|
||||
**
|
||||
** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
|
||||
** releases the buffer P.
|
||||
@@ -1848,14 +1824,13 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
|
||||
** LIMITATIONS:
|
||||
**
|
||||
** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
|
||||
** must be either NULL or else a pointer obtained from a prior
|
||||
** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
|
||||
** not been released.
|
||||
** must be either NULL or else pointers obtained from a prior
|
||||
** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
|
||||
** not yet been released.
|
||||
**
|
||||
** {U17351} The application must not read or write any part of
|
||||
** a block of memory after it has been released using
|
||||
** [sqlite3_free()] or [sqlite3_realloc()].
|
||||
**
|
||||
*/
|
||||
void *sqlite3_malloc(int);
|
||||
void *sqlite3_realloc(void*, int);
|
||||
@@ -1866,7 +1841,7 @@ void sqlite3_free(void*);
|
||||
**
|
||||
** SQLite provides these two interfaces for reporting on the status
|
||||
** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
|
||||
** the memory allocation subsystem included within the SQLite.
|
||||
** routines, which form the built-in memory allocation subsystem.
|
||||
**
|
||||
** INVARIANTS:
|
||||
**
|
||||
@@ -1875,8 +1850,8 @@ void sqlite3_free(void*);
|
||||
** (malloced but not freed).
|
||||
**
|
||||
** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
|
||||
** value of [sqlite3_memory_used()]
|
||||
** since the high-water mark was last reset.
|
||||
** value of [sqlite3_memory_used()] since the high-water mark
|
||||
** was last reset.
|
||||
**
|
||||
** {F17374} The values returned by [sqlite3_memory_used()] and
|
||||
** [sqlite3_memory_highwater()] include any overhead
|
||||
|
||||
Reference in New Issue
Block a user