Deleted Added
sdiff udiff text old ( 226031 ) new ( 226128 )
full compact
sqlite3.h (226031) sqlite3.h (226128)
1/*
2** 2001 September 15
3**
4** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
6**
7** May you do good and not evil.
8** May you find forgiveness for yourself and forgive others.

--- 83 unchanged lines hidden (view full) ---

92** numbers used in [SQLITE_VERSION].)^
93** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
94** be larger than the release from which it is derived. Either Y will
95** be held constant and Z will be incremented or else Y will be incremented
96** and Z will be reset to zero.
97**
98** Since version 3.6.18, SQLite source code has been stored in the
99** <a href="http://www.fossil-scm.org/">Fossil configuration management
1/*
2** 2001 September 15
3**
4** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
6**
7** May you do good and not evil.
8** May you find forgiveness for yourself and forgive others.

--- 83 unchanged lines hidden (view full) ---

92** numbers used in [SQLITE_VERSION].)^
93** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
94** be larger than the release from which it is derived. Either Y will
95** be held constant and Z will be incremented or else Y will be incremented
96** and Z will be reset to zero.
97**
98** Since version 3.6.18, SQLite source code has been stored in the
99** <a href="http://www.fossil-scm.org/">Fossil configuration management
100** system. ^The SQLITE_SOURCE_ID macro evalutes to
100** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
101** a string which identifies a particular check-in of SQLite
102** within its configuration management system. ^The SQLITE_SOURCE_ID
103** string contains the date and time of the check-in (UTC) and an SHA1
104** hash of the entire source tree.
105**
106** See also: [sqlite3_libversion()],
107** [sqlite3_libversion_number()], [sqlite3_sourceid()],
108** [sqlite_version()] and [sqlite_source_id()].
109*/
101** a string which identifies a particular check-in of SQLite
102** within its configuration management system. ^The SQLITE_SOURCE_ID
103** string contains the date and time of the check-in (UTC) and an SHA1
104** hash of the entire source tree.
105**
106** See also: [sqlite3_libversion()],
107** [sqlite3_libversion_number()], [sqlite3_sourceid()],
108** [sqlite_version()] and [sqlite_source_id()].
109*/
110#define SQLITE_VERSION "3.6.23.1"
111#define SQLITE_VERSION_NUMBER 3006023
112#define SQLITE_SOURCE_ID "2010-03-26 22:28:06 b078b588d617e07886ad156e9f54ade6d823568e"
110#define SQLITE_VERSION "3.7.8"
111#define SQLITE_VERSION_NUMBER 3007008
112#define SQLITE_SOURCE_ID "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177"
113
114/*
115** CAPI3REF: Run-Time Library Version Numbers
116** KEYWORDS: sqlite3_version, sqlite3_sourceid
117**
118** These interfaces provide the same information as the [SQLITE_VERSION],
119** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
120** but are associated with the library instead of the header file. ^(Cautious

--- 9 unchanged lines hidden (view full) ---

130** </pre></blockquote>)^
131**
132** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
133** macro. ^The sqlite3_libversion() function returns a pointer to the
134** to the sqlite3_version[] string constant. The sqlite3_libversion()
135** function is provided for use in DLLs since DLL users usually do not have
136** direct access to string constants within the DLL. ^The
137** sqlite3_libversion_number() function returns an integer equal to
113
114/*
115** CAPI3REF: Run-Time Library Version Numbers
116** KEYWORDS: sqlite3_version, sqlite3_sourceid
117**
118** These interfaces provide the same information as the [SQLITE_VERSION],
119** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
120** but are associated with the library instead of the header file. ^(Cautious

--- 9 unchanged lines hidden (view full) ---

130** </pre></blockquote>)^
131**
132** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
133** macro. ^The sqlite3_libversion() function returns a pointer to the
134** to the sqlite3_version[] string constant. The sqlite3_libversion()
135** function is provided for use in DLLs since DLL users usually do not have
136** direct access to string constants within the DLL. ^The
137** sqlite3_libversion_number() function returns an integer equal to
138** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
139** a pointer to a string constant whose value is the same as the
138** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
139** a pointer to a string constant whose value is the same as the
140** [SQLITE_SOURCE_ID] C preprocessor macro.
141**
142** See also: [sqlite_version()] and [sqlite_source_id()].
143*/
144SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
145SQLITE_API const char *sqlite3_libversion(void);
146SQLITE_API const char *sqlite3_sourceid(void);
147SQLITE_API int sqlite3_libversion_number(void);
148
140** [SQLITE_SOURCE_ID] C preprocessor macro.
141**
142** See also: [sqlite_version()] and [sqlite_source_id()].
143*/
144SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
145SQLITE_API const char *sqlite3_libversion(void);
146SQLITE_API const char *sqlite3_sourceid(void);
147SQLITE_API int sqlite3_libversion_number(void);
148
149#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
150/*
151** CAPI3REF: Run-Time Library Compilation Options Diagnostics
152**
149/*
150** CAPI3REF: Run-Time Library Compilation Options Diagnostics
151**
153** ^The sqlite3_compileoption_used() function returns 0 or 1
154** indicating whether the specified option was defined at
155** compile time. ^The SQLITE_ prefix may be omitted from the
156** option name passed to sqlite3_compileoption_used().
152** ^The sqlite3_compileoption_used() function returns 0 or 1
153** indicating whether the specified option was defined at
154** compile time. ^The SQLITE_ prefix may be omitted from the
155** option name passed to sqlite3_compileoption_used().
157**
156**
158** ^The sqlite3_compileoption_get() function allows interating
157** ^The sqlite3_compileoption_get() function allows iterating
159** over the list of options that were defined at compile time by
160** returning the N-th compile time option string. ^If N is out of range,
158** over the list of options that were defined at compile time by
159** returning the N-th compile time option string. ^If N is out of range,
161** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
162** prefix is omitted from any strings returned by
160** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
161** prefix is omitted from any strings returned by
163** sqlite3_compileoption_get().
164**
165** ^Support for the diagnostic functions sqlite3_compileoption_used()
162** sqlite3_compileoption_get().
163**
164** ^Support for the diagnostic functions sqlite3_compileoption_used()
166** and sqlite3_compileoption_get() may be omitted by specifing the
165** and sqlite3_compileoption_get() may be omitted by specifying the
167** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
168**
169** See also: SQL functions [sqlite_compileoption_used()] and
170** [sqlite_compileoption_get()] and the [compile_options pragma].
171*/
166** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
167**
168** See also: SQL functions [sqlite_compileoption_used()] and
169** [sqlite_compileoption_get()] and the [compile_options pragma].
170*/
171#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
172SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
173SQLITE_API const char *sqlite3_compileoption_get(int N);
172SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
173SQLITE_API const char *sqlite3_compileoption_get(int N);
174#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
174#endif
175
176/*
177** CAPI3REF: Test To See If The Library Is Threadsafe
178**
179** ^The sqlite3_threadsafe() function returns zero if and only if
180** SQLite was compiled mutexing code omitted due to the
181** [SQLITE_THREADSAFE] compile-time option being set to 0.
182**
183** SQLite can be compiled with or without mutexes. When
184** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
185** are enabled and SQLite is threadsafe. When the
175
176/*
177** CAPI3REF: Test To See If The Library Is Threadsafe
178**
179** ^The sqlite3_threadsafe() function returns zero if and only if
180** SQLite was compiled mutexing code omitted due to the
181** [SQLITE_THREADSAFE] compile-time option being set to 0.
182**
183** SQLite can be compiled with or without mutexes. When
184** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
185** are enabled and SQLite is threadsafe. When the
186** [SQLITE_THREADSAFE] macro is 0,
186** [SQLITE_THREADSAFE] macro is 0,
187** the mutexes are omitted. Without the mutexes, it is not safe
188** to use SQLite concurrently from more than one thread.
189**
190** Enabling mutexes incurs a measurable performance penalty.
191** So if speed is of utmost importance, it makes sense to disable
192** the mutexes. But for maximum safety, mutexes should be enabled.
193** ^The default behavior is for mutexes to be enabled.
194**

--- 39 unchanged lines hidden (view full) ---

234** SQLite includes typedefs for 64-bit signed and unsigned integers.
235**
236** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
237** The sqlite_int64 and sqlite_uint64 types are supported for backwards
238** compatibility only.
239**
240** ^The sqlite3_int64 and sqlite_int64 types can store integer values
241** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
187** the mutexes are omitted. Without the mutexes, it is not safe
188** to use SQLite concurrently from more than one thread.
189**
190** Enabling mutexes incurs a measurable performance penalty.
191** So if speed is of utmost importance, it makes sense to disable
192** the mutexes. But for maximum safety, mutexes should be enabled.
193** ^The default behavior is for mutexes to be enabled.
194**

--- 39 unchanged lines hidden (view full) ---

234** SQLite includes typedefs for 64-bit signed and unsigned integers.
235**
236** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
237** The sqlite_int64 and sqlite_uint64 types are supported for backwards
238** compatibility only.
239**
240** ^The sqlite3_int64 and sqlite_int64 types can store integer values
241** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
242** sqlite3_uint64 and sqlite_uint64 types can store integer values
242** sqlite3_uint64 and sqlite_uint64 types can store integer values
243** between 0 and +18446744073709551615 inclusive.
244*/
245#ifdef SQLITE_INT64_TYPE
246 typedef SQLITE_INT64_TYPE sqlite_int64;
247 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
248#elif defined(_MSC_VER) || defined(__BORLANDC__)
249 typedef __int64 sqlite_int64;
250 typedef unsigned __int64 sqlite_uint64;

--- 12 unchanged lines hidden (view full) ---

263# define double sqlite3_int64
264#endif
265
266/*
267** CAPI3REF: Closing A Database Connection
268**
269** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
270** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
243** between 0 and +18446744073709551615 inclusive.
244*/
245#ifdef SQLITE_INT64_TYPE
246 typedef SQLITE_INT64_TYPE sqlite_int64;
247 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
248#elif defined(_MSC_VER) || defined(__BORLANDC__)
249 typedef __int64 sqlite_int64;
250 typedef unsigned __int64 sqlite_uint64;

--- 12 unchanged lines hidden (view full) ---

263# define double sqlite3_int64
264#endif
265
266/*
267** CAPI3REF: Closing A Database Connection
268**
269** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
270** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
271** successfullly destroyed and all associated resources are deallocated.
271** successfully destroyed and all associated resources are deallocated.
272**
273** Applications must [sqlite3_finalize | finalize] all [prepared statements]
274** and [sqlite3_blob_close | close] all [BLOB handles] associated with
275** the [sqlite3] object prior to attempting to close the object. ^If
276** sqlite3_close() is called on a [database connection] that still has
277** outstanding [prepared statements] or [BLOB handles], then it returns
278** SQLITE_BUSY.
279**
280** ^If [sqlite3_close()] is invoked while a transaction is open,
281** the transaction is automatically rolled back.
282**
283** The C parameter to [sqlite3_close(C)] must be either a NULL
284** pointer or an [sqlite3] object pointer obtained
285** from [sqlite3_open()], [sqlite3_open16()], or
286** [sqlite3_open_v2()], and not previously closed.
272**
273** Applications must [sqlite3_finalize | finalize] all [prepared statements]
274** and [sqlite3_blob_close | close] all [BLOB handles] associated with
275** the [sqlite3] object prior to attempting to close the object. ^If
276** sqlite3_close() is called on a [database connection] that still has
277** outstanding [prepared statements] or [BLOB handles], then it returns
278** SQLITE_BUSY.
279**
280** ^If [sqlite3_close()] is invoked while a transaction is open,
281** the transaction is automatically rolled back.
282**
283** The C parameter to [sqlite3_close(C)] must be either a NULL
284** pointer or an [sqlite3] object pointer obtained
285** from [sqlite3_open()], [sqlite3_open16()], or
286** [sqlite3_open_v2()], and not previously closed.
287** ^Calling sqlite3_close() with a NULL pointer argument is a
287** ^Calling sqlite3_close() with a NULL pointer argument is a
288** harmless no-op.
289*/
290SQLITE_API int sqlite3_close(sqlite3 *);
291
292/*
293** The type for a callback function.
294** This is legacy and deprecated. It is included for historical
295** compatibility and is not documented.
296*/
297typedef int (*sqlite3_callback)(void*,int,char**, char**);
298
299/*
300** CAPI3REF: One-Step Query Execution Interface
301**
302** The sqlite3_exec() interface is a convenience wrapper around
303** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
304** that allows an application to run multiple statements of SQL
288** harmless no-op.
289*/
290SQLITE_API int sqlite3_close(sqlite3 *);
291
292/*
293** The type for a callback function.
294** This is legacy and deprecated. It is included for historical
295** compatibility and is not documented.
296*/
297typedef int (*sqlite3_callback)(void*,int,char**, char**);
298
299/*
300** CAPI3REF: One-Step Query Execution Interface
301**
302** The sqlite3_exec() interface is a convenience wrapper around
303** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
304** that allows an application to run multiple statements of SQL
305** without having to use a lot of C code.
305** without having to use a lot of C code.
306**
307** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
308** semicolon-separate SQL statements passed into its 2nd argument,
309** in the context of the [database connection] passed in as its 1st
310** argument. ^If the callback function of the 3rd argument to
311** sqlite3_exec() is not NULL, then it is invoked for each result row
312** coming out of the evaluated SQL statements. ^The 4th argument to
306**
307** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
308** semicolon-separate SQL statements passed into its 2nd argument,
309** in the context of the [database connection] passed in as its 1st
310** argument. ^If the callback function of the 3rd argument to
311** sqlite3_exec() is not NULL, then it is invoked for each result row
312** coming out of the evaluated SQL statements. ^The 4th argument to
313** to sqlite3_exec() is relayed through to the 1st argument of each
313** sqlite3_exec() is relayed through to the 1st argument of each
314** callback invocation. ^If the callback pointer to sqlite3_exec()
315** is NULL, then no callback is ever invoked and result rows are
316** ignored.
317**
318** ^If an error occurs while evaluating the SQL statements passed into
319** sqlite3_exec(), then execution of the current statement stops and
320** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
321** is not NULL then any error message is written into memory obtained

--- 15 unchanged lines hidden (view full) ---

337** [sqlite3_column_text()], one for each column. ^If an element of a
338** result row is NULL then the corresponding string pointer for the
339** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
340** sqlite3_exec() callback is an array of pointers to strings where each
341** entry represents the name of corresponding result column as obtained
342** from [sqlite3_column_name()].
343**
344** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
314** callback invocation. ^If the callback pointer to sqlite3_exec()
315** is NULL, then no callback is ever invoked and result rows are
316** ignored.
317**
318** ^If an error occurs while evaluating the SQL statements passed into
319** sqlite3_exec(), then execution of the current statement stops and
320** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
321** is not NULL then any error message is written into memory obtained

--- 15 unchanged lines hidden (view full) ---

337** [sqlite3_column_text()], one for each column. ^If an element of a
338** result row is NULL then the corresponding string pointer for the
339** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
340** sqlite3_exec() callback is an array of pointers to strings where each
341** entry represents the name of corresponding result column as obtained
342** from [sqlite3_column_name()].
343**
344** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
345** to an empty string, or a pointer that contains only whitespace and/or
345** to an empty string, or a pointer that contains only whitespace and/or
346** SQL comments, then no SQL statements are evaluated and the database
347** is not changed.
348**
349** Restrictions:
350**
351** <ul>
352** <li> The application must insure that the 1st parameter to sqlite3_exec()
353** is a valid and open [database connection].

--- 16 unchanged lines hidden (view full) ---

370** KEYWORDS: SQLITE_OK {error code} {error codes}
371** KEYWORDS: {result code} {result codes}
372**
373** Many SQLite functions return an integer result code from the set shown
374** here in order to indicates success or failure.
375**
376** New error codes may be added in future versions of SQLite.
377**
346** SQL comments, then no SQL statements are evaluated and the database
347** is not changed.
348**
349** Restrictions:
350**
351** <ul>
352** <li> The application must insure that the 1st parameter to sqlite3_exec()
353** is a valid and open [database connection].

--- 16 unchanged lines hidden (view full) ---

370** KEYWORDS: SQLITE_OK {error code} {error codes}
371** KEYWORDS: {result code} {result codes}
372**
373** Many SQLite functions return an integer result code from the set shown
374** here in order to indicates success or failure.
375**
376** New error codes may be added in future versions of SQLite.
377**
378** See also: [SQLITE_IOERR_READ | extended result codes]
378** See also: [SQLITE_IOERR_READ | extended result codes],
379** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
379*/
380#define SQLITE_OK 0 /* Successful result */
381/* beginning-of-error-codes */
382#define SQLITE_ERROR 1 /* SQL error or missing database */
383#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
384#define SQLITE_PERM 3 /* Access permission denied */
385#define SQLITE_ABORT 4 /* Callback routine requested an abort */
386#define SQLITE_BUSY 5 /* The database file is locked */
387#define SQLITE_LOCKED 6 /* A table in the database is locked */
388#define SQLITE_NOMEM 7 /* A malloc() failed */
389#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
390#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
391#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
392#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
380*/
381#define SQLITE_OK 0 /* Successful result */
382/* beginning-of-error-codes */
383#define SQLITE_ERROR 1 /* SQL error or missing database */
384#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
385#define SQLITE_PERM 3 /* Access permission denied */
386#define SQLITE_ABORT 4 /* Callback routine requested an abort */
387#define SQLITE_BUSY 5 /* The database file is locked */
388#define SQLITE_LOCKED 6 /* A table in the database is locked */
389#define SQLITE_NOMEM 7 /* A malloc() failed */
390#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
391#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
392#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
393#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
393#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
394#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
394#define SQLITE_FULL 13 /* Insertion failed because database is full */
395#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
395#define SQLITE_FULL 13 /* Insertion failed because database is full */
396#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
396#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
397#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
397#define SQLITE_EMPTY 16 /* Database is empty */
398#define SQLITE_SCHEMA 17 /* The database schema changed */
399#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
400#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
401#define SQLITE_MISMATCH 20 /* Data type mismatch */
402#define SQLITE_MISUSE 21 /* Library used incorrectly */
403#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
404#define SQLITE_AUTH 23 /* Authorization denied */

--- 39 unchanged lines hidden (view full) ---

444#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
445#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
446#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
447#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
448#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
449#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
450#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
451#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
398#define SQLITE_EMPTY 16 /* Database is empty */
399#define SQLITE_SCHEMA 17 /* The database schema changed */
400#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
401#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
402#define SQLITE_MISMATCH 20 /* Data type mismatch */
403#define SQLITE_MISUSE 21 /* Library used incorrectly */
404#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
405#define SQLITE_AUTH 23 /* Authorization denied */

--- 39 unchanged lines hidden (view full) ---

445#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
446#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
447#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
448#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
449#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
450#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
451#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
452#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
452#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8) )
453#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
454#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
455#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
456#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
457#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
458#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
459#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
460#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
461#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
462#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
463#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
453
454/*
455** CAPI3REF: Flags For File Open Operations
456**
457** These bit values are intended for use in the
458** 3rd parameter to the [sqlite3_open_v2()] interface and
464
465/*
466** CAPI3REF: Flags For File Open Operations
467**
468** These bit values are intended for use in the
469** 3rd parameter to the [sqlite3_open_v2()] interface and
459** in the 4th parameter to the xOpen method of the
460** [sqlite3_vfs] object.
470** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
461*/
462#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
463#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
464#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
465#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
466#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
467#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
471*/
472#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
473#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
474#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
475#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
476#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
477#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
478#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
468#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
469#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
470#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
471#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
472#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
473#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
474#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
475#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
476#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
477#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
478#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
479#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
480#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
481#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
482#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
483#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
484#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
485#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
486#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
487#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
488#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
489#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
490#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
479
491
492/* Reserved: 0x00F00000 */
493
480/*
481** CAPI3REF: Device Characteristics
482**
494/*
495** CAPI3REF: Device Characteristics
496**
483** The xDeviceCapabilities method of the [sqlite3_io_methods]
497** The xDeviceCharacteristics method of the [sqlite3_io_methods]
484** object returns an integer which is a vector of the these
485** bit values expressing I/O characteristics of the mass storage
486** device that holds the file that the [sqlite3_io_methods]
487** refers to.
488**
489** The SQLITE_IOCAP_ATOMIC property means that all writes of
490** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
491** mean that writes of blocks that are nnn bytes in size and
492** are aligned to an address which is an integer multiple of
493** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
494** that when data is appended to a file, the data is appended
495** first then the size of the file is extended, never the other
496** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
497** information is written to disk in the same order as calls
498** to xWrite().
499*/
498** object returns an integer which is a vector of the these
499** bit values expressing I/O characteristics of the mass storage
500** device that holds the file that the [sqlite3_io_methods]
501** refers to.
502**
503** The SQLITE_IOCAP_ATOMIC property means that all writes of
504** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
505** mean that writes of blocks that are nnn bytes in size and
506** are aligned to an address which is an integer multiple of
507** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
508** that when data is appended to a file, the data is appended
509** first then the size of the file is extended, never the other
510** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
511** information is written to disk in the same order as calls
512** to xWrite().
513*/
500#define SQLITE_IOCAP_ATOMIC 0x00000001
501#define SQLITE_IOCAP_ATOMIC512 0x00000002
502#define SQLITE_IOCAP_ATOMIC1K 0x00000004
503#define SQLITE_IOCAP_ATOMIC2K 0x00000008
504#define SQLITE_IOCAP_ATOMIC4K 0x00000010
505#define SQLITE_IOCAP_ATOMIC8K 0x00000020
506#define SQLITE_IOCAP_ATOMIC16K 0x00000040
507#define SQLITE_IOCAP_ATOMIC32K 0x00000080
508#define SQLITE_IOCAP_ATOMIC64K 0x00000100
509#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
510#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
514#define SQLITE_IOCAP_ATOMIC 0x00000001
515#define SQLITE_IOCAP_ATOMIC512 0x00000002
516#define SQLITE_IOCAP_ATOMIC1K 0x00000004
517#define SQLITE_IOCAP_ATOMIC2K 0x00000008
518#define SQLITE_IOCAP_ATOMIC4K 0x00000010
519#define SQLITE_IOCAP_ATOMIC8K 0x00000020
520#define SQLITE_IOCAP_ATOMIC16K 0x00000040
521#define SQLITE_IOCAP_ATOMIC32K 0x00000080
522#define SQLITE_IOCAP_ATOMIC64K 0x00000100
523#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
524#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
525#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
511
512/*
513** CAPI3REF: File Locking Levels
514**
515** SQLite uses one of these integer values as the second
516** argument to calls it makes to the xLock() and xUnlock() methods
517** of an [sqlite3_io_methods] object.
518*/

--- 11 unchanged lines hidden (view full) ---

530** these integer values as the second argument.
531**
532** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
533** sync operation only needs to flush data to mass storage. Inode
534** information need not be flushed. If the lower four bits of the flag
535** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
536** If the lower four bits equal SQLITE_SYNC_FULL, that means
537** to use Mac OS X style fullsync instead of fsync().
526
527/*
528** CAPI3REF: File Locking Levels
529**
530** SQLite uses one of these integer values as the second
531** argument to calls it makes to the xLock() and xUnlock() methods
532** of an [sqlite3_io_methods] object.
533*/

--- 11 unchanged lines hidden (view full) ---

545** these integer values as the second argument.
546**
547** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
548** sync operation only needs to flush data to mass storage. Inode
549** information need not be flushed. If the lower four bits of the flag
550** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
551** If the lower four bits equal SQLITE_SYNC_FULL, that means
552** to use Mac OS X style fullsync instead of fsync().
553**
554** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
555** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
556** settings. The [synchronous pragma] determines when calls to the
557** xSync VFS method occur and applies uniformly across all platforms.
558** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
559** energetic or rigorous or forceful the sync operations are and
560** only make a difference on Mac OSX for the default SQLite code.
561** (Third-party VFS implementations might also make the distinction
562** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
563** operating systems natively supported by SQLite, only Mac OSX
564** cares about the difference.)
538*/
539#define SQLITE_SYNC_NORMAL 0x00002
540#define SQLITE_SYNC_FULL 0x00003
541#define SQLITE_SYNC_DATAONLY 0x00010
542
543/*
544** CAPI3REF: OS Interface Open File Handle
545**
565*/
566#define SQLITE_SYNC_NORMAL 0x00002
567#define SQLITE_SYNC_FULL 0x00003
568#define SQLITE_SYNC_DATAONLY 0x00010
569
570/*
571** CAPI3REF: OS Interface Open File Handle
572**
546** An [sqlite3_file] object represents an open file in the
573** An [sqlite3_file] object represents an open file in the
547** [sqlite3_vfs | OS interface layer]. Individual OS interface
548** implementations will
549** want to subclass this object by appending additional fields
550** for their own use. The pMethods entry is a pointer to an
551** [sqlite3_io_methods] object that defines methods for performing
552** I/O operations on the open file.
553*/
554typedef struct sqlite3_file sqlite3_file;
555struct sqlite3_file {
556 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
557};
558
559/*
560** CAPI3REF: OS Interface File Virtual Methods Object
561**
574** [sqlite3_vfs | OS interface layer]. Individual OS interface
575** implementations will
576** want to subclass this object by appending additional fields
577** for their own use. The pMethods entry is a pointer to an
578** [sqlite3_io_methods] object that defines methods for performing
579** I/O operations on the open file.
580*/
581typedef struct sqlite3_file sqlite3_file;
582struct sqlite3_file {
583 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
584};
585
586/*
587** CAPI3REF: OS Interface File Virtual Methods Object
588**
562** Every file opened by the [sqlite3_vfs] xOpen method populates an
589** Every file opened by the [sqlite3_vfs.xOpen] method populates an
563** [sqlite3_file] object (or, more commonly, a subclass of the
564** [sqlite3_file] object) with a pointer to an instance of this object.
565** This object defines the methods used to perform various operations
566** against the open file represented by the [sqlite3_file] object.
567**
590** [sqlite3_file] object (or, more commonly, a subclass of the
591** [sqlite3_file] object) with a pointer to an instance of this object.
592** This object defines the methods used to perform various operations
593** against the open file represented by the [sqlite3_file] object.
594**
568** If the xOpen method sets the sqlite3_file.pMethods element
595** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
569** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
596** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
570** may be invoked even if the xOpen reported that it failed. The
571** only way to prevent a call to xClose following a failed xOpen
572** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
597** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
598** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
599** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
600** to NULL.
573**
574** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
575** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
576** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
577** flag may be ORed in to indicate that only the data of the file
578** and not its inode needs to be synced.
579**
580** The integer values to xLock() and xUnlock() are one of

--- 17 unchanged lines hidden (view full) ---

598** point to a structure that may contain arguments or space in which to
599** write return values. Potential uses for xFileControl() might be
600** functions to enable blocking locks with timeouts, to change the
601** locking strategy (for example to use dot-file locks), to inquire
602** about the status of a lock, or to break stale locks. The SQLite
603** core reserves all opcodes less than 100 for its own use.
604** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
605** Applications that define a custom xFileControl method should use opcodes
601**
602** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
603** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
604** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
605** flag may be ORed in to indicate that only the data of the file
606** and not its inode needs to be synced.
607**
608** The integer values to xLock() and xUnlock() are one of

--- 17 unchanged lines hidden (view full) ---

626** point to a structure that may contain arguments or space in which to
627** write return values. Potential uses for xFileControl() might be
628** functions to enable blocking locks with timeouts, to change the
629** locking strategy (for example to use dot-file locks), to inquire
630** about the status of a lock, or to break stale locks. The SQLite
631** core reserves all opcodes less than 100 for its own use.
632** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
633** Applications that define a custom xFileControl method should use opcodes
606** greater than 100 to avoid conflicts.
634** greater than 100 to avoid conflicts. VFS implementations should
635** return [SQLITE_NOTFOUND] for file control opcodes that they do not
636** recognize.
607**
608** The xSectorSize() method returns the sector size of the
609** device that underlies the file. The sector size is the
610** minimum write that can be performed without disturbing
611** other bytes in the file. The xDeviceCharacteristics()
612** method returns a bit vector describing behaviors of the
613** underlying device:
614**

--- 38 unchanged lines hidden (view full) ---

653 int (*xSync)(sqlite3_file*, int flags);
654 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
655 int (*xLock)(sqlite3_file*, int);
656 int (*xUnlock)(sqlite3_file*, int);
657 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
658 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
659 int (*xSectorSize)(sqlite3_file*);
660 int (*xDeviceCharacteristics)(sqlite3_file*);
637**
638** The xSectorSize() method returns the sector size of the
639** device that underlies the file. The sector size is the
640** minimum write that can be performed without disturbing
641** other bytes in the file. The xDeviceCharacteristics()
642** method returns a bit vector describing behaviors of the
643** underlying device:
644**

--- 38 unchanged lines hidden (view full) ---

683 int (*xSync)(sqlite3_file*, int flags);
684 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
685 int (*xLock)(sqlite3_file*, int);
686 int (*xUnlock)(sqlite3_file*, int);
687 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
688 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
689 int (*xSectorSize)(sqlite3_file*);
690 int (*xDeviceCharacteristics)(sqlite3_file*);
691 /* Methods above are valid for version 1 */
692 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
693 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
694 void (*xShmBarrier)(sqlite3_file*);
695 int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
696 /* Methods above are valid for version 2 */
661 /* Additional methods may be added in future releases */
662};
663
664/*
665** CAPI3REF: Standard File Control Opcodes
666**
667** These integer constants are opcodes for the xFileControl method
668** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
669** interface.
670**
671** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
672** opcode causes the xFileControl method to write the current state of
673** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
674** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
675** into an integer that the pArg argument points to. This capability
676** is used during testing and only needs to be supported when SQLITE_TEST
677** is defined.
697 /* Additional methods may be added in future releases */
698};
699
700/*
701** CAPI3REF: Standard File Control Opcodes
702**
703** These integer constants are opcodes for the xFileControl method
704** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
705** interface.
706**
707** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
708** opcode causes the xFileControl method to write the current state of
709** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
710** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
711** into an integer that the pArg argument points to. This capability
712** is used during testing and only needs to be supported when SQLITE_TEST
713** is defined.
714**
715** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
716** layer a hint of how large the database file will grow to be during the
717** current transaction. This hint is not guaranteed to be accurate but it
718** is often close. The underlying VFS might choose to preallocate database
719** file space based on this hint in order to help writes to the database
720** file run faster.
721**
722** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
723** extends and truncates the database file in chunks of a size specified
724** by the user. The fourth argument to [sqlite3_file_control()] should
725** point to an integer (type int) containing the new chunk-size to use
726** for the nominated database. Allocating database file space in large
727** chunks (say 1MB at a time), may reduce file-system fragmentation and
728** improve performance on some systems.
729**
730** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
731** to the [sqlite3_file] object associated with a particular database
732** connection. See the [sqlite3_file_control()] documentation for
733** additional information.
734**
735** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
736** SQLite and sent to all VFSes in place of a call to the xSync method
737** when the database connection has [PRAGMA synchronous] set to OFF.)^
738** Some specialized VFSes need this signal in order to operate correctly
739** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most
740** VFSes do not need this signal and should silently ignore this opcode.
741** Applications should not call [sqlite3_file_control()] with this
742** opcode as doing so may disrupt the operation of the specialized VFSes
743** that do require it.
744**
745** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
746** retry counts and intervals for certain disk I/O operations for the
747** windows [VFS] in order to work to provide robustness against
748** anti-virus programs. By default, the windows VFS will retry file read,
749** file write, and file delete opertions up to 10 times, with a delay
750** of 25 milliseconds before the first retry and with the delay increasing
751** by an additional 25 milliseconds with each subsequent retry. This
752** opcode allows those to values (10 retries and 25 milliseconds of delay)
753** to be adjusted. The values are changed for all database connections
754** within the same process. The argument is a pointer to an array of two
755** integers where the first integer i the new retry count and the second
756** integer is the delay. If either integer is negative, then the setting
757** is not changed but instead the prior value of that setting is written
758** into the array entry, allowing the current retry settings to be
759** interrogated. The zDbName parameter is ignored.
760**
761** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
762** persistent [WAL | Write AHead Log] setting. By default, the auxiliary
763** write ahead log and shared memory files used for transaction control
764** are automatically deleted when the latest connection to the database
765** closes. Setting persistent WAL mode causes those files to persist after
766** close. Persisting the files is useful when other processes that do not
767** have write permission on the directory containing the database file want
768** to read the database file, as the WAL and shared memory files must exist
769** in order for the database to be readable. The fourth parameter to
770** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
771** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
772** WAL mode. If the integer is -1, then it is overwritten with the current
773** WAL persistence setting.
774**
678*/
679#define SQLITE_FCNTL_LOCKSTATE 1
680#define SQLITE_GET_LOCKPROXYFILE 2
681#define SQLITE_SET_LOCKPROXYFILE 3
682#define SQLITE_LAST_ERRNO 4
775*/
776#define SQLITE_FCNTL_LOCKSTATE 1
777#define SQLITE_GET_LOCKPROXYFILE 2
778#define SQLITE_SET_LOCKPROXYFILE 3
779#define SQLITE_LAST_ERRNO 4
780#define SQLITE_FCNTL_SIZE_HINT 5
781#define SQLITE_FCNTL_CHUNK_SIZE 6
782#define SQLITE_FCNTL_FILE_POINTER 7
783#define SQLITE_FCNTL_SYNC_OMITTED 8
784#define SQLITE_FCNTL_WIN32_AV_RETRY 9
785#define SQLITE_FCNTL_PERSIST_WAL 10
683
684/*
685** CAPI3REF: Mutex Handle
686**
687** The mutex module within SQLite defines [sqlite3_mutex] to be an
688** abstract type for a mutex object. The SQLite core never looks
689** at the internal representation of an [sqlite3_mutex]. It only
690** deals with pointers to the [sqlite3_mutex] object.
691**
692** Mutexes are created using [sqlite3_mutex_alloc()].
693*/
694typedef struct sqlite3_mutex sqlite3_mutex;
695
696/*
697** CAPI3REF: OS Interface Object
698**
699** An instance of the sqlite3_vfs object defines the interface between
700** the SQLite core and the underlying operating system. The "vfs"
786
787/*
788** CAPI3REF: Mutex Handle
789**
790** The mutex module within SQLite defines [sqlite3_mutex] to be an
791** abstract type for a mutex object. The SQLite core never looks
792** at the internal representation of an [sqlite3_mutex]. It only
793** deals with pointers to the [sqlite3_mutex] object.
794**
795** Mutexes are created using [sqlite3_mutex_alloc()].
796*/
797typedef struct sqlite3_mutex sqlite3_mutex;
798
799/*
800** CAPI3REF: OS Interface Object
801**
802** An instance of the sqlite3_vfs object defines the interface between
803** the SQLite core and the underlying operating system. The "vfs"
701** in the name of the object stands for "virtual file system".
804** in the name of the object stands for "virtual file system". See
805** the [VFS | VFS documentation] for further information.
702**
703** The value of the iVersion field is initially 1 but may be larger in
704** future versions of SQLite. Additional fields may be appended to this
705** object when the iVersion value is increased. Note that the structure
706** of the sqlite3_vfs object changes in the transaction between
707** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
708** modified.
709**

--- 12 unchanged lines hidden (view full) ---

722** structure that SQLite will ever modify. SQLite will only access
723** or modify this field while holding a particular static mutex.
724** The application should never modify anything within the sqlite3_vfs
725** object once the object has been registered.
726**
727** The zName field holds the name of the VFS module. The name must
728** be unique across all VFS modules.
729**
806**
807** The value of the iVersion field is initially 1 but may be larger in
808** future versions of SQLite. Additional fields may be appended to this
809** object when the iVersion value is increased. Note that the structure
810** of the sqlite3_vfs object changes in the transaction between
811** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
812** modified.
813**

--- 12 unchanged lines hidden (view full) ---

826** structure that SQLite will ever modify. SQLite will only access
827** or modify this field while holding a particular static mutex.
828** The application should never modify anything within the sqlite3_vfs
829** object once the object has been registered.
830**
831** The zName field holds the name of the VFS module. The name must
832** be unique across all VFS modules.
833**
730** SQLite will guarantee that the zFilename parameter to xOpen
834** [[sqlite3_vfs.xOpen]]
835** ^SQLite guarantees that the zFilename parameter to xOpen
731** is either a NULL pointer or string obtained
836** is either a NULL pointer or string obtained
732** from xFullPathname(). SQLite further guarantees that
837** from xFullPathname() with an optional suffix added.
838** ^If a suffix is added to the zFilename parameter, it will
839** consist of a single "-" character followed by no more than
840** 10 alphanumeric and/or "-" characters.
841** ^SQLite further guarantees that
733** the string will be valid and unchanged until xClose() is
734** called. Because of the previous sentence,
735** the [sqlite3_file] can safely store a pointer to the
736** filename if it needs to remember the filename for some reason.
842** the string will be valid and unchanged until xClose() is
843** called. Because of the previous sentence,
844** the [sqlite3_file] can safely store a pointer to the
845** filename if it needs to remember the filename for some reason.
737** If the zFilename parameter is xOpen is a NULL pointer then xOpen
738** must invent its own temporary name for the file. Whenever the
846** If the zFilename parameter to xOpen is a NULL pointer then xOpen
847** must invent its own temporary name for the file. ^Whenever the
739** xFilename parameter is NULL it will also be the case that the
740** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
741**
742** The flags argument to xOpen() includes all bits set in
743** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
744** or [sqlite3_open16()] is used, then flags includes at least
848** xFilename parameter is NULL it will also be the case that the
849** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
850**
851** The flags argument to xOpen() includes all bits set in
852** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
853** or [sqlite3_open16()] is used, then flags includes at least
745** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
854** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
746** If xOpen() opens a file read-only then it sets *pOutFlags to
747** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
748**
855** If xOpen() opens a file read-only then it sets *pOutFlags to
856** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
857**
749** SQLite will also add one of the following flags to the xOpen()
858** ^(SQLite will also add one of the following flags to the xOpen()
750** call, depending on the object being opened:
751**
752** <ul>
753** <li> [SQLITE_OPEN_MAIN_DB]
754** <li> [SQLITE_OPEN_MAIN_JOURNAL]
755** <li> [SQLITE_OPEN_TEMP_DB]
756** <li> [SQLITE_OPEN_TEMP_JOURNAL]
757** <li> [SQLITE_OPEN_TRANSIENT_DB]
758** <li> [SQLITE_OPEN_SUBJOURNAL]
759** <li> [SQLITE_OPEN_MASTER_JOURNAL]
859** call, depending on the object being opened:
860**
861** <ul>
862** <li> [SQLITE_OPEN_MAIN_DB]
863** <li> [SQLITE_OPEN_MAIN_JOURNAL]
864** <li> [SQLITE_OPEN_TEMP_DB]
865** <li> [SQLITE_OPEN_TEMP_JOURNAL]
866** <li> [SQLITE_OPEN_TRANSIENT_DB]
867** <li> [SQLITE_OPEN_SUBJOURNAL]
868** <li> [SQLITE_OPEN_MASTER_JOURNAL]
760** </ul>
869** <li> [SQLITE_OPEN_WAL]
870** </ul>)^
761**
762** The file I/O implementation can use the object type flags to
763** change the way it deals with files. For example, an application
764** that does not care about crash recovery or rollback might make
765** the open of a journal file a no-op. Writes to this journal would
766** also be no-ops, and any attempt to read the journal would return
767** SQLITE_IOERR. Or the implementation might recognize that a database
768** file will be doing page-aligned sector reads and writes in a random
769** order and set up its I/O subsystem accordingly.
770**
771** SQLite might also add one of the following flags to the xOpen method:
772**
773** <ul>
774** <li> [SQLITE_OPEN_DELETEONCLOSE]
775** <li> [SQLITE_OPEN_EXCLUSIVE]
776** </ul>
777**
778** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
871**
872** The file I/O implementation can use the object type flags to
873** change the way it deals with files. For example, an application
874** that does not care about crash recovery or rollback might make
875** the open of a journal file a no-op. Writes to this journal would
876** also be no-ops, and any attempt to read the journal would return
877** SQLITE_IOERR. Or the implementation might recognize that a database
878** file will be doing page-aligned sector reads and writes in a random
879** order and set up its I/O subsystem accordingly.
880**
881** SQLite might also add one of the following flags to the xOpen method:
882**
883** <ul>
884** <li> [SQLITE_OPEN_DELETEONCLOSE]
885** <li> [SQLITE_OPEN_EXCLUSIVE]
886** </ul>
887**
888** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
779** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE]
780** will be set for TEMP databases, journals and for subjournals.
889** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
890** will be set for TEMP databases and their journals, transient
891** databases, and subjournals.
781**
892**
782** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
893** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
783** with the [SQLITE_OPEN_CREATE] flag, which are both directly
784** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
894** with the [SQLITE_OPEN_CREATE] flag, which are both directly
895** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
785** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
896** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
786** SQLITE_OPEN_CREATE, is used to indicate that file should always
787** be created, and that it is an error if it already exists.
897** SQLITE_OPEN_CREATE, is used to indicate that file should always
898** be created, and that it is an error if it already exists.
788** It is not used to indicate the file should be opened
899** It is <i>not</i> used to indicate the file should be opened
789** for exclusive access.
790**
900** for exclusive access.
901**
791** At least szOsFile bytes of memory are allocated by SQLite
902** ^At least szOsFile bytes of memory are allocated by SQLite
792** to hold the [sqlite3_file] structure passed as the third
793** argument to xOpen. The xOpen method does not have to
794** allocate the structure; it should just fill it in. Note that
795** the xOpen method must set the sqlite3_file.pMethods to either
796** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
797** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
798** element will be valid after xOpen returns regardless of the success
799** or failure of the xOpen call.
800**
903** to hold the [sqlite3_file] structure passed as the third
904** argument to xOpen. The xOpen method does not have to
905** allocate the structure; it should just fill it in. Note that
906** the xOpen method must set the sqlite3_file.pMethods to either
907** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
908** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
909** element will be valid after xOpen returns regardless of the success
910** or failure of the xOpen call.
911**
801** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
912** [[sqlite3_vfs.xAccess]]
913** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
802** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
803** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
804** to test whether a file is at least readable. The file can be a
805** directory.
806**
914** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
915** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
916** to test whether a file is at least readable. The file can be a
917** directory.
918**
807** SQLite will always allocate at least mxPathname+1 bytes for the
919** ^SQLite will always allocate at least mxPathname+1 bytes for the
808** output buffer xFullPathname. The exact size of the output buffer
809** is also passed as a parameter to both methods. If the output buffer
810** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
811** handled as a fatal error by SQLite, vfs implementations should endeavor
812** to prevent this by setting mxPathname to a sufficiently large value.
813**
920** output buffer xFullPathname. The exact size of the output buffer
921** is also passed as a parameter to both methods. If the output buffer
922** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
923** handled as a fatal error by SQLite, vfs implementations should endeavor
924** to prevent this by setting mxPathname to a sufficiently large value.
925**
814** The xRandomness(), xSleep(), and xCurrentTime() interfaces
815** are not strictly a part of the filesystem, but they are
926** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
927** interfaces are not strictly a part of the filesystem, but they are
816** included in the VFS structure for completeness.
817** The xRandomness() function attempts to return nBytes bytes
818** of good-quality randomness into zOut. The return value is
819** the actual number of bytes of randomness obtained.
820** The xSleep() method causes the calling thread to sleep for at
928** included in the VFS structure for completeness.
929** The xRandomness() function attempts to return nBytes bytes
930** of good-quality randomness into zOut. The return value is
931** the actual number of bytes of randomness obtained.
932** The xSleep() method causes the calling thread to sleep for at
821** least the number of microseconds given. The xCurrentTime()
822** method returns a Julian Day Number for the current date and time.
933** least the number of microseconds given. ^The xCurrentTime()
934** method returns a Julian Day Number for the current date and time as
935** a floating point value.
936** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
937** Day Number multiplied by 86400000 (the number of milliseconds in
938** a 24-hour day).
939** ^SQLite will use the xCurrentTimeInt64() method to get the current
940** date and time if that method is available (if iVersion is 2 or
941** greater and the function pointer is not NULL) and will fall back
942** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
823**
943**
944** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
945** are not used by the SQLite core. These optional interfaces are provided
946** by some VFSes to facilitate testing of the VFS code. By overriding
947** system calls with functions under its control, a test program can
948** simulate faults and error conditions that would otherwise be difficult
949** or impossible to induce. The set of system calls that can be overridden
950** varies from one VFS to another, and from one version of the same VFS to the
951** next. Applications that use these interfaces must be prepared for any
952** or all of these interfaces to be NULL or for their behavior to change
953** from one release to the next. Applications must not attempt to access
954** any of these methods if the iVersion of the VFS is less than 3.
824*/
825typedef struct sqlite3_vfs sqlite3_vfs;
955*/
956typedef struct sqlite3_vfs sqlite3_vfs;
957typedef void (*sqlite3_syscall_ptr)(void);
826struct sqlite3_vfs {
958struct sqlite3_vfs {
827 int iVersion; /* Structure version number */
959 int iVersion; /* Structure version number (currently 3) */
828 int szOsFile; /* Size of subclassed sqlite3_file */
829 int mxPathname; /* Maximum file pathname length */
830 sqlite3_vfs *pNext; /* Next registered VFS */
831 const char *zName; /* Name of this virtual file system */
832 void *pAppData; /* Pointer to application-specific data */
833 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
834 int flags, int *pOutFlags);
835 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
836 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
837 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
838 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
839 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
840 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
841 void (*xDlClose)(sqlite3_vfs*, void*);
842 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
843 int (*xSleep)(sqlite3_vfs*, int microseconds);
844 int (*xCurrentTime)(sqlite3_vfs*, double*);
845 int (*xGetLastError)(sqlite3_vfs*, int, char *);
960 int szOsFile; /* Size of subclassed sqlite3_file */
961 int mxPathname; /* Maximum file pathname length */
962 sqlite3_vfs *pNext; /* Next registered VFS */
963 const char *zName; /* Name of this virtual file system */
964 void *pAppData; /* Pointer to application-specific data */
965 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
966 int flags, int *pOutFlags);
967 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
968 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
969 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
970 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
971 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
972 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
973 void (*xDlClose)(sqlite3_vfs*, void*);
974 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
975 int (*xSleep)(sqlite3_vfs*, int microseconds);
976 int (*xCurrentTime)(sqlite3_vfs*, double*);
977 int (*xGetLastError)(sqlite3_vfs*, int, char *);
846 /* New fields may be appended in figure versions. The iVersion
847 ** value will increment whenever this happens. */
978 /*
979 ** The methods above are in version 1 of the sqlite_vfs object
980 ** definition. Those that follow are added in version 2 or later
981 */
982 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
983 /*
984 ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
985 ** Those below are for version 3 and greater.
986 */
987 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
988 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
989 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
990 /*
991 ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
992 ** New fields may be appended in figure versions. The iVersion
993 ** value will increment whenever this happens.
994 */
848};
849
850/*
851** CAPI3REF: Flags for the xAccess VFS method
852**
853** These integer constants can be used as the third parameter to
854** the xAccess method of an [sqlite3_vfs] object. They determine
855** what kind of permissions the xAccess method is looking for.
856** With SQLITE_ACCESS_EXISTS, the xAccess method
857** simply checks whether the file exists.
858** With SQLITE_ACCESS_READWRITE, the xAccess method
995};
996
997/*
998** CAPI3REF: Flags for the xAccess VFS method
999**
1000** These integer constants can be used as the third parameter to
1001** the xAccess method of an [sqlite3_vfs] object. They determine
1002** what kind of permissions the xAccess method is looking for.
1003** With SQLITE_ACCESS_EXISTS, the xAccess method
1004** simply checks whether the file exists.
1005** With SQLITE_ACCESS_READWRITE, the xAccess method
859** checks whether the file is both readable and writable.
1006** checks whether the named directory is both readable and writable
1007** (in other words, if files can be added, removed, and renamed within
1008** the directory).
1009** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1010** [temp_store_directory pragma], though this could change in a future
1011** release of SQLite.
860** With SQLITE_ACCESS_READ, the xAccess method
1012** With SQLITE_ACCESS_READ, the xAccess method
861** checks whether the file is readable.
1013** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1014** currently unused, though it might be used in a future release of
1015** SQLite.
862*/
863#define SQLITE_ACCESS_EXISTS 0
1016*/
1017#define SQLITE_ACCESS_EXISTS 0
864#define SQLITE_ACCESS_READWRITE 1
865#define SQLITE_ACCESS_READ 2
1018#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1019#define SQLITE_ACCESS_READ 2 /* Unused */
866
867/*
1020
1021/*
1022** CAPI3REF: Flags for the xShmLock VFS method
1023**
1024** These integer constants define the various locking operations
1025** allowed by the xShmLock method of [sqlite3_io_methods]. The
1026** following are the only legal combinations of flags to the
1027** xShmLock method:
1028**
1029** <ul>
1030** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1031** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1032** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1033** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1034** </ul>
1035**
1036** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1037** was given no the corresponding lock.
1038**
1039** The xShmLock method can transition between unlocked and SHARED or
1040** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1041** and EXCLUSIVE.
1042*/
1043#define SQLITE_SHM_UNLOCK 1
1044#define SQLITE_SHM_LOCK 2
1045#define SQLITE_SHM_SHARED 4
1046#define SQLITE_SHM_EXCLUSIVE 8
1047
1048/*
1049** CAPI3REF: Maximum xShmLock index
1050**
1051** The xShmLock method on [sqlite3_io_methods] may use values
1052** between 0 and this upper bound as its "offset" argument.
1053** The SQLite core will never attempt to acquire or release a
1054** lock outside of this range
1055*/
1056#define SQLITE_SHM_NLOCK 8
1057
1058
1059/*
868** CAPI3REF: Initialize The SQLite Library
869**
870** ^The sqlite3_initialize() routine initializes the
871** SQLite library. ^The sqlite3_shutdown() routine
872** deallocates any resources that were allocated by sqlite3_initialize().
873** These routines are designed to aid in process initialization and
874** shutdown on embedded systems. Workstation applications using
875** SQLite normally do not need to invoke either of these routines.

--- 83 unchanged lines hidden (view full) ---

959** may only be invoked prior to library initialization using
960** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
961** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
962** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
963** Note, however, that ^sqlite3_config() can be called as part of the
964** implementation of an application-defined [sqlite3_os_init()].
965**
966** The first argument to sqlite3_config() is an integer
1060** CAPI3REF: Initialize The SQLite Library
1061**
1062** ^The sqlite3_initialize() routine initializes the
1063** SQLite library. ^The sqlite3_shutdown() routine
1064** deallocates any resources that were allocated by sqlite3_initialize().
1065** These routines are designed to aid in process initialization and
1066** shutdown on embedded systems. Workstation applications using
1067** SQLite normally do not need to invoke either of these routines.

--- 83 unchanged lines hidden (view full) ---

1151** may only be invoked prior to library initialization using
1152** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1153** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1154** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1155** Note, however, that ^sqlite3_config() can be called as part of the
1156** implementation of an application-defined [sqlite3_os_init()].
1157**
1158** The first argument to sqlite3_config() is an integer
967** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
1159** [configuration option] that determines
968** what property of SQLite is to be configured. Subsequent arguments
1160** what property of SQLite is to be configured. Subsequent arguments
969** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
1161** vary depending on the [configuration option]
970** in the first argument.
971**
972** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
973** ^If the option is unknown or SQLite is unable to set the option
974** then this routine returns a non-zero [error code].
975*/
1162** in the first argument.
1163**
1164** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1165** ^If the option is unknown or SQLite is unable to set the option
1166** then this routine returns a non-zero [error code].
1167*/
976SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
1168SQLITE_API int sqlite3_config(int, ...);
977
978/*
979** CAPI3REF: Configure database connections
1169
1170/*
1171** CAPI3REF: Configure database connections
980** EXPERIMENTAL
981**
982** The sqlite3_db_config() interface is used to make configuration
983** changes to a [database connection]. The interface is similar to
984** [sqlite3_config()] except that the changes apply to a single
1172**
1173** The sqlite3_db_config() interface is used to make configuration
1174** changes to a [database connection]. The interface is similar to
1175** [sqlite3_config()] except that the changes apply to a single
985** [database connection] (specified in the first argument). The
986** sqlite3_db_config() interface should only be used immediately after
987** the database connection is created using [sqlite3_open()],
988** [sqlite3_open16()], or [sqlite3_open_v2()].
1176** [database connection] (specified in the first argument).
989**
990** The second argument to sqlite3_db_config(D,V,...) is the
1177**
1178** The second argument to sqlite3_db_config(D,V,...) is the
991** configuration verb - an integer code that indicates what
992** aspect of the [database connection] is being configured.
993** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
994** New verbs are likely to be added in future releases of SQLite.
995** Additional arguments depend on the verb.
1179** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1180** that indicates what aspect of the [database connection] is being configured.
1181** Subsequent arguments vary depending on the configuration verb.
996**
997** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
998** the call is considered successful.
999*/
1182**
1183** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1184** the call is considered successful.
1185*/
1000SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
1186SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1001
1002/*
1003** CAPI3REF: Memory Allocation Routines
1187
1188/*
1189** CAPI3REF: Memory Allocation Routines
1004** EXPERIMENTAL
1005**
1006** An instance of this object defines the interface between SQLite
1007** and low-level memory allocation routines.
1008**
1009** This object is used in only one place in the SQLite interface.
1010** A pointer to an instance of this object is the argument to
1011** [sqlite3_config()] when the configuration option is
1190**
1191** An instance of this object defines the interface between SQLite
1192** and low-level memory allocation routines.
1193**
1194** This object is used in only one place in the SQLite interface.
1195** A pointer to an instance of this object is the argument to
1196** [sqlite3_config()] when the configuration option is
1012** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1197** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1013** By creating an instance of this object
1014** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1015** during configuration, an application can specify an alternative
1016** memory allocation subsystem for SQLite to use for all of its
1017** dynamic memory needs.
1018**
1019** Note that SQLite comes with several [built-in memory allocators]
1020** that are perfectly adequate for the overwhelming majority of applications
1021** and that this object is only useful to a tiny minority of applications
1022** with specialized memory allocation requirements. This object is
1023** also used during testing of SQLite in order to specify an alternative
1024** memory allocator that simulates memory out-of-memory conditions in
1025** order to verify that SQLite recovers gracefully from such
1026** conditions.
1027**
1198** By creating an instance of this object
1199** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1200** during configuration, an application can specify an alternative
1201** memory allocation subsystem for SQLite to use for all of its
1202** dynamic memory needs.
1203**
1204** Note that SQLite comes with several [built-in memory allocators]
1205** that are perfectly adequate for the overwhelming majority of applications
1206** and that this object is only useful to a tiny minority of applications
1207** with specialized memory allocation requirements. This object is
1208** also used during testing of SQLite in order to specify an alternative
1209** memory allocator that simulates memory out-of-memory conditions in
1210** order to verify that SQLite recovers gracefully from such
1211** conditions.
1212**
1028** The xMalloc and xFree methods must work like the
1029** malloc() and free() functions from the standard C library.
1030** The xRealloc method must work like realloc() from the standard C library
1031** with the exception that if the second argument to xRealloc is zero,
1032** xRealloc must be a no-op - it must not perform any allocation or
1033** deallocation. ^SQLite guarantees that the second argument to
1213** The xMalloc, xRealloc, and xFree methods must work like the
1214** malloc(), realloc() and free() functions from the standard C library.
1215** ^SQLite guarantees that the second argument to
1034** xRealloc is always a value returned by a prior call to xRoundup.
1216** xRealloc is always a value returned by a prior call to xRoundup.
1035** And so in cases where xRoundup always returns a positive number,
1036** xRealloc can perform exactly as the standard library realloc() and
1037** still be in compliance with this specification.
1038**
1039** xSize should return the allocated size of a memory allocation
1040** previously obtained from xMalloc or xRealloc. The allocated size
1041** is always at least as big as the requested size but may be larger.
1042**
1043** The xRoundup method returns what would be the allocated size of
1044** a memory allocation given a particular requested size. Most memory
1045** allocators round up memory allocations at least to the next multiple
1046** of 8. Some allocators round up to a larger multiple or to a power of 2.
1047** Every memory allocation request coming in through [sqlite3_malloc()]
1217**
1218** xSize should return the allocated size of a memory allocation
1219** previously obtained from xMalloc or xRealloc. The allocated size
1220** is always at least as big as the requested size but may be larger.
1221**
1222** The xRoundup method returns what would be the allocated size of
1223** a memory allocation given a particular requested size. Most memory
1224** allocators round up memory allocations at least to the next multiple
1225** of 8. Some allocators round up to a larger multiple or to a power of 2.
1226** Every memory allocation request coming in through [sqlite3_malloc()]
1048** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1227** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1049** that causes the corresponding memory allocation to fail.
1050**
1051** The xInit method initializes the memory allocator. (For example,
1052** it might allocate any require mutexes or initialize internal data
1053** structures. The xShutdown method is invoked (indirectly) by
1054** [sqlite3_shutdown()] and should deallocate any resources acquired
1055** by xInit. The pAppData pointer is used as the only parameter to
1056** xInit and xShutdown.

--- 21 unchanged lines hidden (view full) ---

1078 int (*xRoundup)(int); /* Round up request size to allocation size */
1079 int (*xInit)(void*); /* Initialize the memory allocator */
1080 void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1081 void *pAppData; /* Argument to xInit() and xShutdown() */
1082};
1083
1084/*
1085** CAPI3REF: Configuration Options
1228** that causes the corresponding memory allocation to fail.
1229**
1230** The xInit method initializes the memory allocator. (For example,
1231** it might allocate any require mutexes or initialize internal data
1232** structures. The xShutdown method is invoked (indirectly) by
1233** [sqlite3_shutdown()] and should deallocate any resources acquired
1234** by xInit. The pAppData pointer is used as the only parameter to
1235** xInit and xShutdown.

--- 21 unchanged lines hidden (view full) ---

1257 int (*xRoundup)(int); /* Round up request size to allocation size */
1258 int (*xInit)(void*); /* Initialize the memory allocator */
1259 void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1260 void *pAppData; /* Argument to xInit() and xShutdown() */
1261};
1262
1263/*
1264** CAPI3REF: Configuration Options
1086** EXPERIMENTAL
1265** KEYWORDS: {configuration option}
1087**
1088** These constants are the available integer configuration options that
1089** can be passed as the first argument to the [sqlite3_config()] interface.
1090**
1091** New configuration options may be added in future releases of SQLite.
1092** Existing configuration options might be discontinued. Applications
1093** should check the return code from [sqlite3_config()] to make sure that
1094** the call worked. The [sqlite3_config()] interface will return a
1095** non-zero [error code] if a discontinued or unsupported configuration option
1096** is invoked.
1097**
1098** <dl>
1266**
1267** These constants are the available integer configuration options that
1268** can be passed as the first argument to the [sqlite3_config()] interface.
1269**
1270** New configuration options may be added in future releases of SQLite.
1271** Existing configuration options might be discontinued. Applications
1272** should check the return code from [sqlite3_config()] to make sure that
1273** the call worked. The [sqlite3_config()] interface will return a
1274** non-zero [error code] if a discontinued or unsupported configuration option
1275** is invoked.
1276**
1277** <dl>
1099**
SQLITE_CONFIG_SINGLETHREAD

1278** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1100** <dd>There are no arguments to this option. ^This option sets the
1101** [threading mode] to Single-thread. In other words, it disables
1102** all mutexing and puts SQLite into a mode where it can only be used
1103** by a single thread. ^If SQLite is compiled with
1104** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1105** it is not possible to change the [threading mode] from its default
1279** <dd>There are no arguments to this option. ^This option sets the
1280** [threading mode] to Single-thread. In other words, it disables
1281** all mutexing and puts SQLite into a mode where it can only be used
1282** by a single thread. ^If SQLite is compiled with
1283** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1284** it is not possible to change the [threading mode] from its default
1106** value of Single-thread and so [sqlite3_config()] will return
1285** value of Single-thread and so [sqlite3_config()] will return
1107** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1108** configuration option.</dd>
1109**
1286** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1287** configuration option.</dd>
1288**
1110**
SQLITE_CONFIG_MULTITHREAD

1289** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1111** <dd>There are no arguments to this option. ^This option sets the
1112** [threading mode] to Multi-thread. In other words, it disables
1113** mutexing on [database connection] and [prepared statement] objects.
1114** The application is responsible for serializing access to
1115** [database connections] and [prepared statements]. But other mutexes
1116** are enabled so that SQLite will be safe to use in a multi-threaded
1117** environment as long as no two threads attempt to use the same
1118** [database connection] at the same time. ^If SQLite is compiled with
1119** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1120** it is not possible to set the Multi-thread [threading mode] and
1121** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1122** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1123**
1290** <dd>There are no arguments to this option. ^This option sets the
1291** [threading mode] to Multi-thread. In other words, it disables
1292** mutexing on [database connection] and [prepared statement] objects.
1293** The application is responsible for serializing access to
1294** [database connections] and [prepared statements]. But other mutexes
1295** are enabled so that SQLite will be safe to use in a multi-threaded
1296** environment as long as no two threads attempt to use the same
1297** [database connection] at the same time. ^If SQLite is compiled with
1298** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1299** it is not possible to set the Multi-thread [threading mode] and
1300** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1301** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1302**
1124**
SQLITE_CONFIG_SERIALIZED

1303** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1125** <dd>There are no arguments to this option. ^This option sets the
1126** [threading mode] to Serialized. In other words, this option enables
1127** all mutexes including the recursive
1128** mutexes on [database connection] and [prepared statement] objects.
1129** In this mode (which is the default when SQLite is compiled with
1130** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1131** to [database connections] and [prepared statements] so that the
1132** application is free to use the same [database connection] or the
1133** same [prepared statement] in different threads at the same time.
1134** ^If SQLite is compiled with
1135** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1136** it is not possible to set the Serialized [threading mode] and
1137** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1138** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1139**
1304** <dd>There are no arguments to this option. ^This option sets the
1305** [threading mode] to Serialized. In other words, this option enables
1306** all mutexes including the recursive
1307** mutexes on [database connection] and [prepared statement] objects.
1308** In this mode (which is the default when SQLite is compiled with
1309** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1310** to [database connections] and [prepared statements] so that the
1311** application is free to use the same [database connection] or the
1312** same [prepared statement] in different threads at the same time.
1313** ^If SQLite is compiled with
1314** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1315** it is not possible to set the Serialized [threading mode] and
1316** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1317** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1318**
1140**
SQLITE_CONFIG_MALLOC

1319** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1141** <dd> ^(This option takes a single argument which is a pointer to an
1142** instance of the [sqlite3_mem_methods] structure. The argument specifies
1143** alternative low-level memory allocation routines to be used in place of
1144** the memory allocation routines built into SQLite.)^ ^SQLite makes
1145** its own private copy of the content of the [sqlite3_mem_methods] structure
1146** before the [sqlite3_config()] call returns.</dd>
1147**
1320** <dd> ^(This option takes a single argument which is a pointer to an
1321** instance of the [sqlite3_mem_methods] structure. The argument specifies
1322** alternative low-level memory allocation routines to be used in place of
1323** the memory allocation routines built into SQLite.)^ ^SQLite makes
1324** its own private copy of the content of the [sqlite3_mem_methods] structure
1325** before the [sqlite3_config()] call returns.</dd>
1326**
1148**
SQLITE_CONFIG_GETMALLOC

1327** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1149** <dd> ^(This option takes a single argument which is a pointer to an
1150** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
1151** structure is filled with the currently defined memory allocation routines.)^
1152** This option can be used to overload the default memory allocation
1153** routines with a wrapper that simulations memory allocation failure or
1154** tracks memory usage, for example. </dd>
1155**
1328** <dd> ^(This option takes a single argument which is a pointer to an
1329** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
1330** structure is filled with the currently defined memory allocation routines.)^
1331** This option can be used to overload the default memory allocation
1332** routines with a wrapper that simulations memory allocation failure or
1333** tracks memory usage, for example. </dd>
1334**
1156**
SQLITE_CONFIG_MEMSTATUS

1157**
^This option takes single argument of type int, interpreted as a
1158** boolean, which enables or disables the collection of memory allocation
1159** statistics. ^(When memory allocation statistics are disabled, the
1335** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1336** <dd> ^This option takes single argument of type int, interpreted as a
1337** boolean, which enables or disables the collection of memory allocation
1338** statistics. ^(When memory allocation statistics are disabled, the
1160** following SQLite interfaces become non-operational:
1161** <ul>
1162** <li> [sqlite3_memory_used()]
1163** <li> [sqlite3_memory_highwater()]
1339** following SQLite interfaces become non-operational:
1340** <ul>
1341** <li> [sqlite3_memory_used()]
1342** <li> [sqlite3_memory_highwater()]
1164**
  • [sqlite3_soft_heap_limit()]
    		• 1343** <li> [sqlite3_soft_heap_limit64()]
    1165** <li> [sqlite3_status()]
    1166** </ul>)^
    1167** ^Memory allocation statistics are enabled by default unless SQLite is
    1168** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
    1169** allocation statistics are disabled by default.
    1170** </dd>
    1171**
    		1344** <li> [sqlite3_status()]
    1345** </ul>)^
    1346** ^Memory allocation statistics are enabled by default unless SQLite is
    1347** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
    1348** allocation statistics are disabled by default.
    1349** </dd>
    1350**
    1172**
    SQLITE_CONFIG_SCRATCH

    		1351** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
    1173** <dd> ^This option specifies a static memory buffer that SQLite can use for
    1174** scratch memory. There are three arguments: A pointer an 8-byte
    		1352** <dd> ^This option specifies a static memory buffer that SQLite can use for
    1353** scratch memory. There are three arguments: A pointer an 8-byte
    1175** aligned memory buffer from which the scrach allocations will be
    		1354** aligned memory buffer from which the scratch allocations will be
    1176** drawn, the size of each scratch allocation (sz),
    1177** and the maximum number of scratch allocations (N). The sz
    		1355** drawn, the size of each scratch allocation (sz),
    1356** and the maximum number of scratch allocations (N). The sz
    1178** argument must be a multiple of 16. The sz parameter should be a few bytes
    1179** larger than the actual scratch space required due to internal overhead.
    		1357** argument must be a multiple of 16.
    1180** The first argument must be a pointer to an 8-byte aligned buffer
    1181** of at least sz*N bytes of memory.
    		1358** The first argument must be a pointer to an 8-byte aligned buffer
    1359** of at least sz*N bytes of memory.
    1182** ^SQLite will use no more than one scratch buffer per thread. So
    1183** N should be set to the expected maximum number of threads. ^SQLite will
    1184** never require a scratch buffer that is more than 6 times the database
    1185** page size. ^If SQLite needs needs additional scratch memory beyond
    1186** what is provided by this configuration option, then
    		1360** ^SQLite will use no more than two scratch buffers per thread. So
    1361** N should be set to twice the expected maximum number of threads.
    1362** ^SQLite will never require a scratch buffer that is more than 6
    1363** times the database page size. ^If SQLite needs needs additional
    1364** scratch memory beyond what is provided by this configuration option, then
    1187** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
    1188**
    		1365** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
    1366**
    1189**
    SQLITE_CONFIG_PAGECACHE

    		1367** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
    1190** <dd> ^This option specifies a static memory buffer that SQLite can use for
    		1368** <dd> ^This option specifies a static memory buffer that SQLite can use for
    1191** the database page cache with the default page cache implemenation.
    		1369** the database page cache with the default page cache implementation.
    1192** This configuration should not be used if an application-define page
    1193** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
    1194** There are three arguments to this option: A pointer to 8-byte aligned
    1195** memory, the size of each page buffer (sz), and the number of pages (N).
    1196** The sz argument should be the size of the largest database page
    1197** (a power of two between 512 and 32768) plus a little extra for each
    1198** page header. ^The page header size is 20 to 40 bytes depending on
    1199** the host architecture. ^It is harmless, apart from the wasted memory,
    1200** to make sz a little too large. The first
    1201** argument should point to an allocation of at least sz*N bytes of memory.
    1202** ^SQLite will use the memory provided by the first argument to satisfy its
    1203** memory needs for the first N pages that it adds to cache. ^If additional
    1204** page cache memory is needed beyond what is provided by this option, then
    1205** SQLite goes to [sqlite3_malloc()] for the additional storage space.
    		1370** This configuration should not be used if an application-define page
    1371** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
    1372** There are three arguments to this option: A pointer to 8-byte aligned
    1373** memory, the size of each page buffer (sz), and the number of pages (N).
    1374** The sz argument should be the size of the largest database page
    1375** (a power of two between 512 and 32768) plus a little extra for each
    1376** page header. ^The page header size is 20 to 40 bytes depending on
    1377** the host architecture. ^It is harmless, apart from the wasted memory,
    1378** to make sz a little too large. The first
    1379** argument should point to an allocation of at least sz*N bytes of memory.
    1380** ^SQLite will use the memory provided by the first argument to satisfy its
    1381** memory needs for the first N pages that it adds to cache. ^If additional
    1382** page cache memory is needed beyond what is provided by this option, then
    1383** SQLite goes to [sqlite3_malloc()] for the additional storage space.
    1206** ^The implementation might use one or more of the N buffers to hold
    1207** memory accounting information. The pointer in the first argument must
    		1384** The pointer in the first argument must
    1208** be aligned to an 8-byte boundary or subsequent behavior of SQLite
    1209** will be undefined.</dd>
    1210**
    		1385** be aligned to an 8-byte boundary or subsequent behavior of SQLite
    1386** will be undefined.</dd>
    1387**
    1211**
    SQLITE_CONFIG_HEAP

    		1388** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
    1212** <dd> ^This option specifies a static memory buffer that SQLite will use
    1213** for all of its dynamic memory allocation needs beyond those provided
    1214** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
    1215** There are three arguments: An 8-byte aligned pointer to the memory,
    1216** the number of bytes in the memory buffer, and the minimum allocation size.
    1217** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
    1218** to using its default memory allocator (the system malloc() implementation),
    1219** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
    1220** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
    1221** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
    1222** allocator is engaged to handle all of SQLites memory allocation needs.
    1223** The first pointer (the memory pointer) must be aligned to an 8-byte
    		1389** <dd> ^This option specifies a static memory buffer that SQLite will use
    1390** for all of its dynamic memory allocation needs beyond those provided
    1391** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
    1392** There are three arguments: An 8-byte aligned pointer to the memory,
    1393** the number of bytes in the memory buffer, and the minimum allocation size.
    1394** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
    1395** to using its default memory allocator (the system malloc() implementation),
    1396** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
    1397** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
    1398** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
    1399** allocator is engaged to handle all of SQLites memory allocation needs.
    1400** The first pointer (the memory pointer) must be aligned to an 8-byte
    1224** boundary or subsequent behavior of SQLite will be undefined.</dd>
    		1401** boundary or subsequent behavior of SQLite will be undefined.
    1402** The minimum allocation size is capped at 2^12. Reasonable values
    1403** for the minimum allocation size are 2^5 through 2^8.</dd>
    1225**
    		1404**
    1226**
    SQLITE_CONFIG_MUTEX

    		1405** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
    1227** <dd> ^(This option takes a single argument which is a pointer to an
    1228** instance of the [sqlite3_mutex_methods] structure. The argument specifies
    1229** alternative low-level mutex routines to be used in place
    1230** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
    1231** content of the [sqlite3_mutex_methods] structure before the call to
    1232** [sqlite3_config()] returns. ^If SQLite is compiled with
    1233** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
    1234** the entire mutexing subsystem is omitted from the build and hence calls to
    1235** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
    1236** return [SQLITE_ERROR].</dd>
    1237**
    		1406** <dd> ^(This option takes a single argument which is a pointer to an
    1407** instance of the [sqlite3_mutex_methods] structure. The argument specifies
    1408** alternative low-level mutex routines to be used in place
    1409** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
    1410** content of the [sqlite3_mutex_methods] structure before the call to
    1411** [sqlite3_config()] returns. ^If SQLite is compiled with
    1412** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
    1413** the entire mutexing subsystem is omitted from the build and hence calls to
    1414** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
    1415** return [SQLITE_ERROR].</dd>
    1416**
    1238**
    SQLITE_CONFIG_GETMUTEX

    		1417** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
    1239** <dd> ^(This option takes a single argument which is a pointer to an
    1240** instance of the [sqlite3_mutex_methods] structure. The
    1241** [sqlite3_mutex_methods]
    1242** structure is filled with the currently defined mutex routines.)^
    1243** This option can be used to overload the default mutex allocation
    1244** routines with a wrapper used to track mutex usage for performance
    1245** profiling or testing, for example. ^If SQLite is compiled with
    1246** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
    1247** the entire mutexing subsystem is omitted from the build and hence calls to
    1248** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
    1249** return [SQLITE_ERROR].</dd>
    1250**
    		1418** <dd> ^(This option takes a single argument which is a pointer to an
    1419** instance of the [sqlite3_mutex_methods] structure. The
    1420** [sqlite3_mutex_methods]
    1421** structure is filled with the currently defined mutex routines.)^
    1422** This option can be used to overload the default mutex allocation
    1423** routines with a wrapper used to track mutex usage for performance
    1424** profiling or testing, for example. ^If SQLite is compiled with
    1425** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
    1426** the entire mutexing subsystem is omitted from the build and hence calls to
    1427** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
    1428** return [SQLITE_ERROR].</dd>
    1429**
    1251**
    SQLITE_CONFIG_LOOKASIDE

    		1430** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
    1252** <dd> ^(This option takes two arguments that determine the default
    1253** memory allocation for the lookaside memory allocator on each
    1254** [database connection]. The first argument is the
    1255** size of each lookaside buffer slot and the second is the number of
    1256** slots allocated to each database connection.)^ ^(This option sets the
    1257** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
    1258** verb to [sqlite3_db_config()] can be used to change the lookaside
    1259** configuration on individual connections.)^ </dd>
    1260**
    		1431** <dd> ^(This option takes two arguments that determine the default
    1432** memory allocation for the lookaside memory allocator on each
    1433** [database connection]. The first argument is the
    1434** size of each lookaside buffer slot and the second is the number of
    1435** slots allocated to each database connection.)^ ^(This option sets the
    1436** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
    1437** verb to [sqlite3_db_config()] can be used to change the lookaside
    1438** configuration on individual connections.)^ </dd>
    1439**
    1261**
    SQLITE_CONFIG_PCACHE

    		1440** [[SQLITE_CONFIG_PCACHE]] <dt>SQLITE_CONFIG_PCACHE</dt>
    1262** <dd> ^(This option takes a single argument which is a pointer to
    1263** an [sqlite3_pcache_methods] object. This object specifies the interface
    1264** to a custom page cache implementation.)^ ^SQLite makes a copy of the
    1265** object and uses it for page cache memory allocations.</dd>
    1266**
    		1441** <dd> ^(This option takes a single argument which is a pointer to
    1442** an [sqlite3_pcache_methods] object. This object specifies the interface
    1443** to a custom page cache implementation.)^ ^SQLite makes a copy of the
    1444** object and uses it for page cache memory allocations.</dd>
    1445**
    1267**
    SQLITE_CONFIG_GETPCACHE

    		1446** [[SQLITE_CONFIG_GETPCACHE]] <dt>SQLITE_CONFIG_GETPCACHE</dt>
    1268** <dd> ^(This option takes a single argument which is a pointer to an
    1269** [sqlite3_pcache_methods] object. SQLite copies of the current
    1270** page cache implementation into that object.)^ </dd>
    1271**
    		1447** <dd> ^(This option takes a single argument which is a pointer to an
    1448** [sqlite3_pcache_methods] object. SQLite copies of the current
    1449** page cache implementation into that object.)^ </dd>
    1450**
    1451** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
    1452** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
    1453** function with a call signature of void(*)(void*,int,const char*),
    1454** and a pointer to void. ^If the function pointer is not NULL, it is
    1455** invoked by [sqlite3_log()] to process each logging event. ^If the
    1456** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
    1457** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
    1458** passed through as the first parameter to the application-defined logger
    1459** function whenever that function is invoked. ^The second parameter to
    1460** the logger function is a copy of the first parameter to the corresponding
    1461** [sqlite3_log()] call and is intended to be a [result code] or an
    1462** [extended result code]. ^The third parameter passed to the logger is
    1463** log message after formatting via [sqlite3_snprintf()].
    1464** The SQLite logging interface is not reentrant; the logger function
    1465** supplied by the application must not invoke any SQLite interface.
    1466** In a multi-threaded application, the application-defined logger
    1467** function must be threadsafe. </dd>
    1468**
    1469** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
    1470** <dd> This option takes a single argument of type int. If non-zero, then
    1471** URI handling is globally enabled. If the parameter is zero, then URI handling
    1472** is globally disabled. If URI handling is globally enabled, all filenames
    1473** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
    1474** specified as part of [ATTACH] commands are interpreted as URIs, regardless
    1475** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
    1476** connection is opened. If it is globally disabled, filenames are
    1477** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
    1478** database connection is opened. By default, URI handling is globally
    1479** disabled. The default value may be changed by compiling with the
    1480** [SQLITE_USE_URI] symbol defined.
    1272** </dl>
    1273*/
    1274#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
    1275#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
    1276#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
    1277#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
    1278#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
    1279#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
    1280#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
    1281#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
    1282#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
    1283#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
    1284#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
    		1481** </dl>
    1482*/
    1483#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
    1484#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
    1485#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
    1486#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
    1487#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
    1488#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
    1489#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
    1490#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
    1491#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
    1492#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
    1493#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
    1285/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
    		1494/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
    1286#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
    1287#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */
    1288#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */
    1289#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
    		1495#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
    1496#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */
    1497#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */
    1498#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
    1499#define SQLITE_CONFIG_URI 17 /* int */
    1290
    1291/*
    		1500
    1501/*
    1292** CAPI3REF: Configuration Options
    1293** EXPERIMENTAL
    		1502** CAPI3REF: Database Connection Configuration Options
    1294**
    1295** These constants are the available integer configuration options that
    1296** can be passed as the second argument to the [sqlite3_db_config()] interface.
    1297**
    1298** New configuration options may be added in future releases of SQLite.
    1299** Existing configuration options might be discontinued. Applications
    1300** should check the return code from [sqlite3_db_config()] to make sure that
    1301** the call worked. ^The [sqlite3_db_config()] interface will return a
    1302** non-zero [error code] if a discontinued or unsupported configuration option
    1303** is invoked.
    1304**
    1305** <dl>
    1306** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
    		1503**
    1504** These constants are the available integer configuration options that
    1505** can be passed as the second argument to the [sqlite3_db_config()] interface.
    1506**
    1507** New configuration options may be added in future releases of SQLite.
    1508** Existing configuration options might be discontinued. Applications
    1509** should check the return code from [sqlite3_db_config()] to make sure that
    1510** the call worked. ^The [sqlite3_db_config()] interface will return a
    1511** non-zero [error code] if a discontinued or unsupported configuration option
    1512** is invoked.
    1513**
    1514** <dl>
    1515** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
    1307**
    ^This option takes three additional arguments that determine the
    		1516** <dd> ^This option takes three additional arguments that determine the
    1308** [lookaside memory allocator] configuration for the [database connection].
    1309** ^The first argument (the third parameter to [sqlite3_db_config()] is a
    		1517** [lookaside memory allocator] configuration for the [database connection].
    1518** ^The first argument (the third parameter to [sqlite3_db_config()] is a
    1310** pointer to an memory buffer to use for lookaside memory.
    		1519** pointer to a memory buffer to use for lookaside memory.
    1311** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
    1312** may be NULL in which case SQLite will allocate the
    1313** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
    1314** size of each lookaside buffer slot. ^The third argument is the number of
    1315** slots. The size of the buffer in the first argument must be greater than
    1316** or equal to the product of the second and third arguments. The buffer
    1317** must be aligned to an 8-byte boundary. ^If the second argument to
    1318** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
    		1520** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
    1521** may be NULL in which case SQLite will allocate the
    1522** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
    1523** size of each lookaside buffer slot. ^The third argument is the number of
    1524** slots. The size of the buffer in the first argument must be greater than
    1525** or equal to the product of the second and third arguments. The buffer
    1526** must be aligned to an 8-byte boundary. ^If the second argument to
    1527** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
    1319** rounded down to the next smaller
    1320** multiple of 8. See also: [SQLITE_CONFIG_LOOKASIDE]</dd>
    		1528** rounded down to the next smaller multiple of 8. ^(The lookaside memory
    1529** configuration for a database connection can only be changed when that
    1530** connection is not currently using lookaside memory, or in other words
    1531** when the "current value" returned by
    1532** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
    1533** Any attempt to change the lookaside memory configuration when lookaside
    1534** memory is in use leaves the configuration unchanged and returns
    1535** [SQLITE_BUSY].)^</dd>
    1321**
    		1536**
    1537** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
    1538** <dd> ^This option is used to enable or disable the enforcement of
    1539** [foreign key constraints]. There should be two additional arguments.
    1540** The first argument is an integer which is 0 to disable FK enforcement,
    1541** positive to enable FK enforcement or negative to leave FK enforcement
    1542** unchanged. The second parameter is a pointer to an integer into which
    1543** is written 0 or 1 to indicate whether FK enforcement is off or on
    1544** following this call. The second parameter may be a NULL pointer, in
    1545** which case the FK enforcement setting is not reported back. </dd>
    1546**
    1547** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
    1548** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
    1549** There should be two additional arguments.
    1550** The first argument is an integer which is 0 to disable triggers,
    1551** positive to enable triggers or negative to leave the setting unchanged.
    1552** The second parameter is a pointer to an integer into which
    1553** is written 0 or 1 to indicate whether triggers are disabled or enabled
    1554** following this call. The second parameter may be a NULL pointer, in
    1555** which case the trigger setting is not reported back. </dd>
    1556**
    1322** </dl>
    1323*/
    		1557** </dl>
    1558*/
    1324#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
    		1559#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
    1560#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
    1561#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
    1325
    1326
    1327/*
    1328** CAPI3REF: Enable Or Disable Extended Result Codes
    1329**
    1330** ^The sqlite3_extended_result_codes() routine enables or disables the
    1331** [extended result codes] feature of SQLite. ^The extended result
    1332** codes are disabled by default for historical compatibility.

    --- 7 unchanged lines hidden (view full) ---

    1340** integer key called the [ROWID | "rowid"]. ^The rowid is always available
    1341** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
    1342** names are not also used by explicitly declared columns. ^If
    1343** the table has a column of type [INTEGER PRIMARY KEY] then that column
    1344** is another alias for the rowid.
    1345**
    1346** ^This routine returns the [rowid] of the most recent
    1347** successful [INSERT] into the database from the [database connection]
    		1562
    1563
    1564/*
    1565** CAPI3REF: Enable Or Disable Extended Result Codes
    1566**
    1567** ^The sqlite3_extended_result_codes() routine enables or disables the
    1568** [extended result codes] feature of SQLite. ^The extended result
    1569** codes are disabled by default for historical compatibility.

    --- 7 unchanged lines hidden (view full) ---

    1577** integer key called the [ROWID | "rowid"]. ^The rowid is always available
    1578** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
    1579** names are not also used by explicitly declared columns. ^If
    1580** the table has a column of type [INTEGER PRIMARY KEY] then that column
    1581** is another alias for the rowid.
    1582**
    1583** ^This routine returns the [rowid] of the most recent
    1584** successful [INSERT] into the database from the [database connection]
    1348** in the first argument. ^If no successful [INSERT]s
    		1585** in the first argument. ^As of SQLite version 3.7.7, this routines
    1586** records the last insert rowid of both ordinary tables and [virtual tables].
    1587** ^If no successful [INSERT]s
    1349** have ever occurred on that database connection, zero is returned.
    1350**
    		1588** have ever occurred on that database connection, zero is returned.
    1589**
    1351** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
    1352** row is returned by this routine as long as the trigger is running.
    1353** But once the trigger terminates, the value returned by this routine
    1354** reverts to the last value inserted before the trigger fired.)^
    		1590** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
    1591** method, then this routine will return the [rowid] of the inserted
    1592** row as long as the trigger or virtual table method is running.
    1593** But once the trigger or virtual table method ends, the value returned
    1594** by this routine reverts to what it was before the trigger or virtual
    1595** table method began.)^
    1355**
    1356** ^An [INSERT] that fails due to a constraint violation is not a
    1357** successful [INSERT] and does not change the value returned by this
    1358** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
    1359** and INSERT OR ABORT make no changes to the return value of this
    1360** routine when their insertion fails. ^(When INSERT OR REPLACE
    1361** encounters a constraint violation, it does not fail. The
    1362** INSERT continues to completion after deleting rows that caused

    --- 32 unchanged lines hidden (view full) ---

    1395**
    1396** ^(A "row change" is a change to a single row of a single table
    1397** caused by an INSERT, DELETE, or UPDATE statement. Rows that
    1398** are changed as side effects of [REPLACE] constraint resolution,
    1399** rollback, ABORT processing, [DROP TABLE], or by any other
    1400** mechanisms do not count as direct row changes.)^
    1401**
    1402** A "trigger context" is a scope of execution that begins and
    		1596**
    1597** ^An [INSERT] that fails due to a constraint violation is not a
    1598** successful [INSERT] and does not change the value returned by this
    1599** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
    1600** and INSERT OR ABORT make no changes to the return value of this
    1601** routine when their insertion fails. ^(When INSERT OR REPLACE
    1602** encounters a constraint violation, it does not fail. The
    1603** INSERT continues to completion after deleting rows that caused

    --- 32 unchanged lines hidden (view full) ---

    1636**
    1637** ^(A "row change" is a change to a single row of a single table
    1638** caused by an INSERT, DELETE, or UPDATE statement. Rows that
    1639** are changed as side effects of [REPLACE] constraint resolution,
    1640** rollback, ABORT processing, [DROP TABLE], or by any other
    1641** mechanisms do not count as direct row changes.)^
    1642**
    1643** A "trigger context" is a scope of execution that begins and
    1403** ends with the script of a [CREATE TRIGGER | trigger].
    		1644** ends with the script of a [CREATE TRIGGER | trigger].
    1404** Most SQL statements are
    1405** evaluated outside of any trigger. This is the "top level"
    1406** trigger context. If a trigger fires from the top level, a
    1407** new trigger context is entered for the duration of that one
    1408** trigger. Subtriggers create subcontexts for their duration.
    1409**
    1410** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
    1411** not create a new trigger context.

    --- 26 unchanged lines hidden (view full) ---

    1438** ^This function returns the number of row changes caused by [INSERT],
    1439** [UPDATE] or [DELETE] statements since the [database connection] was opened.
    1440** ^(The count returned by sqlite3_total_changes() includes all changes
    1441** from all [CREATE TRIGGER | trigger] contexts and changes made by
    1442** [foreign key actions]. However,
    1443** the count does not include changes used to implement [REPLACE] constraints,
    1444** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
    1445** count does not include rows of views that fire an [INSTEAD OF trigger],
    		1645** Most SQL statements are
    1646** evaluated outside of any trigger. This is the "top level"
    1647** trigger context. If a trigger fires from the top level, a
    1648** new trigger context is entered for the duration of that one
    1649** trigger. Subtriggers create subcontexts for their duration.
    1650**
    1651** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
    1652** not create a new trigger context.

    --- 26 unchanged lines hidden (view full) ---

    1679** ^This function returns the number of row changes caused by [INSERT],
    1680** [UPDATE] or [DELETE] statements since the [database connection] was opened.
    1681** ^(The count returned by sqlite3_total_changes() includes all changes
    1682** from all [CREATE TRIGGER | trigger] contexts and changes made by
    1683** [foreign key actions]. However,
    1684** the count does not include changes used to implement [REPLACE] constraints,
    1685** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
    1686** count does not include rows of views that fire an [INSTEAD OF trigger],
    1446** though if the INSTEAD OF trigger makes changes of its own, those changes
    		1687** though if the INSTEAD OF trigger makes changes of its own, those changes
    1447** are counted.)^
    1448** ^The sqlite3_total_changes() function counts the changes as soon as
    1449** the statement that makes them is completed (when the statement handle
    1450** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
    1451**
    1452** See also the [sqlite3_changes()] interface, the
    1453** [count_changes pragma], and the [total_changes() SQL function].
    1454**

    --- 23 unchanged lines hidden (view full) ---

    1478**
    1479** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
    1480** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
    1481** that is inside an explicit transaction, then the entire transaction
    1482** will be rolled back automatically.
    1483**
    1484** ^The sqlite3_interrupt(D) call is in effect until all currently running
    1485** SQL statements on [database connection] D complete. ^Any new SQL statements
    		1688** are counted.)^
    1689** ^The sqlite3_total_changes() function counts the changes as soon as
    1690** the statement that makes them is completed (when the statement handle
    1691** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
    1692**
    1693** See also the [sqlite3_changes()] interface, the
    1694** [count_changes pragma], and the [total_changes() SQL function].
    1695**

    --- 23 unchanged lines hidden (view full) ---

    1719**
    1720** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
    1721** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
    1722** that is inside an explicit transaction, then the entire transaction
    1723** will be rolled back automatically.
    1724**
    1725** ^The sqlite3_interrupt(D) call is in effect until all currently running
    1726** SQL statements on [database connection] D complete. ^Any new SQL statements
    1486** that are started after the sqlite3_interrupt() call and before the
    		1727** that are started after the sqlite3_interrupt() call and before the
    1487** running statements reaches zero are interrupted as if they had been
    1488** running prior to the sqlite3_interrupt() call. ^New SQL statements
    1489** that are started after the running statement count reaches zero are
    1490** not effected by the sqlite3_interrupt().
    1491** ^A call to sqlite3_interrupt(D) that occurs when there are no running
    1492** SQL statements is a no-op and has no effect on SQL statements
    1493** that are started after the sqlite3_interrupt() call returns.
    1494**

    --- 18 unchanged lines hidden (view full) ---

    1513** and comments that follow the final semicolon are ignored.
    1514**
    1515** ^These routines return 0 if the statement is incomplete. ^If a
    1516** memory allocation fails, then SQLITE_NOMEM is returned.
    1517**
    1518** ^These routines do not parse the SQL statements thus
    1519** will not detect syntactically incorrect SQL.
    1520**
    		1728** running statements reaches zero are interrupted as if they had been
    1729** running prior to the sqlite3_interrupt() call. ^New SQL statements
    1730** that are started after the running statement count reaches zero are
    1731** not effected by the sqlite3_interrupt().
    1732** ^A call to sqlite3_interrupt(D) that occurs when there are no running
    1733** SQL statements is a no-op and has no effect on SQL statements
    1734** that are started after the sqlite3_interrupt() call returns.
    1735**

    --- 18 unchanged lines hidden (view full) ---

    1754** and comments that follow the final semicolon are ignored.
    1755**
    1756** ^These routines return 0 if the statement is incomplete. ^If a
    1757** memory allocation fails, then SQLITE_NOMEM is returned.
    1758**
    1759** ^These routines do not parse the SQL statements thus
    1760** will not detect syntactically incorrect SQL.
    1761**
    1521** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
    		1762** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
    1522** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
    1523** automatically by sqlite3_complete16(). If that initialization fails,
    1524** then the return value from sqlite3_complete16() will be non-zero
    1525** regardless of whether or not the input SQL is complete.)^
    1526**
    1527** The input to [sqlite3_complete()] must be a zero-terminated
    1528** UTF-8 string.
    1529**

    --- 58 unchanged lines hidden (view full) ---

    1588** ^(There can only be a single busy handler defined for each
    1589** [database connection]. Setting a new busy handler clears any
    1590** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
    1591** will also set or clear the busy handler.
    1592**
    1593** The busy callback should not take any actions which modify the
    1594** database connection that invoked the busy handler. Any such actions
    1595** result in undefined behavior.
    		1763** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
    1764** automatically by sqlite3_complete16(). If that initialization fails,
    1765** then the return value from sqlite3_complete16() will be non-zero
    1766** regardless of whether or not the input SQL is complete.)^
    1767**
    1768** The input to [sqlite3_complete()] must be a zero-terminated
    1769** UTF-8 string.
    1770**

    --- 58 unchanged lines hidden (view full) ---

    1829** ^(There can only be a single busy handler defined for each
    1830** [database connection]. Setting a new busy handler clears any
    1831** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
    1832** will also set or clear the busy handler.
    1833**
    1834** The busy callback should not take any actions which modify the
    1835** database connection that invoked the busy handler. Any such actions
    1836** result in undefined behavior.
    1596**
    		1837**
    1597** A busy handler must not close the database connection
    1598** or [prepared statement] that invoked the busy handler.
    1599*/
    1600SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
    1601
    1602/*
    1603** CAPI3REF: Set A Busy Timeout
    1604**

    --- 12 unchanged lines hidden (view full) ---

    1617** was defined (using [sqlite3_busy_handler()]) prior to calling
    1618** this routine, that other busy handler is cleared.)^
    1619*/
    1620SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
    1621
    1622/*
    1623** CAPI3REF: Convenience Routines For Running Queries
    1624**
    		1838** A busy handler must not close the database connection
    1839** or [prepared statement] that invoked the busy handler.
    1840*/
    1841SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
    1842
    1843/*
    1844** CAPI3REF: Set A Busy Timeout
    1845**

    --- 12 unchanged lines hidden (view full) ---

    1858** was defined (using [sqlite3_busy_handler()]) prior to calling
    1859** this routine, that other busy handler is cleared.)^
    1860*/
    1861SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
    1862
    1863/*
    1864** CAPI3REF: Convenience Routines For Running Queries
    1865**
    1866** This is a legacy interface that is preserved for backwards compatibility.
    1867** Use of this interface is not recommended.
    1868**
    1625** Definition: A <b>result table</b> is memory data structure created by the
    1626** [sqlite3_get_table()] interface. A result table records the
    1627** complete query results from one or more queries.
    1628**
    1629** The table conceptually has a number of rows and columns. But
    1630** these numbers are not part of the result table itself. These
    1631** numbers are obtained separately. Let N be the number of rows
    1632** and M be the number of columns.

    --- 4 unchanged lines hidden (view full) ---

    1637** The remaining entries all point to query results. NULL values result
    1638** in NULL pointers. All other values are in their UTF-8 zero-terminated
    1639** string representation as returned by [sqlite3_column_text()].
    1640**
    1641** A result table might consist of one or more memory allocations.
    1642** It is not safe to pass a result table directly to [sqlite3_free()].
    1643** A result table should be deallocated using [sqlite3_free_table()].
    1644**
    		1869** Definition: A <b>result table</b> is memory data structure created by the
    1870** [sqlite3_get_table()] interface. A result table records the
    1871** complete query results from one or more queries.
    1872**
    1873** The table conceptually has a number of rows and columns. But
    1874** these numbers are not part of the result table itself. These
    1875** numbers are obtained separately. Let N be the number of rows
    1876** and M be the number of columns.

    --- 4 unchanged lines hidden (view full) ---

    1881** The remaining entries all point to query results. NULL values result
    1882** in NULL pointers. All other values are in their UTF-8 zero-terminated
    1883** string representation as returned by [sqlite3_column_text()].
    1884**
    1885** A result table might consist of one or more memory allocations.
    1886** It is not safe to pass a result table directly to [sqlite3_free()].
    1887** A result table should be deallocated using [sqlite3_free_table()].
    1888**
    1645** As an example of the result table format, suppose a query result
    		1889** ^(As an example of the result table format, suppose a query result
    1646** is as follows:
    1647**
    1648** <blockquote><pre>
    1649** Name | Age
    1650** -----------------------
    1651** Alice | 43
    1652** Bob | 28
    1653** Cindy | 21

    --- 7 unchanged lines hidden (view full) ---

    1661** azResult&#91;0] = "Name";
    1662** azResult&#91;1] = "Age";
    1663** azResult&#91;2] = "Alice";
    1664** azResult&#91;3] = "43";
    1665** azResult&#91;4] = "Bob";
    1666** azResult&#91;5] = "28";
    1667** azResult&#91;6] = "Cindy";
    1668** azResult&#91;7] = "21";
    		1890** is as follows:
    1891**
    1892** <blockquote><pre>
    1893** Name | Age
    1894** -----------------------
    1895** Alice | 43
    1896** Bob | 28
    1897** Cindy | 21

    --- 7 unchanged lines hidden (view full) ---

    1905** azResult&#91;0] = "Name";
    1906** azResult&#91;1] = "Age";
    1907** azResult&#91;2] = "Alice";
    1908** azResult&#91;3] = "43";
    1909** azResult&#91;4] = "Bob";
    1910** azResult&#91;5] = "28";
    1911** azResult&#91;6] = "Cindy";
    1912** azResult&#91;7] = "21";
    1669**
    		1913** </pre></blockquote>)^
    1670**
    1671** ^The sqlite3_get_table() function evaluates one or more
    1672** semicolon-separated SQL statements in the zero-terminated UTF-8
    1673** string of its 2nd parameter and returns a result table to the
    1674** pointer given in its 3rd parameter.
    1675**
    1676** After the application has finished with the result from sqlite3_get_table(),
    		1914**
    1915** ^The sqlite3_get_table() function evaluates one or more
    1916** semicolon-separated SQL statements in the zero-terminated UTF-8
    1917** string of its 2nd parameter and returns a result table to the
    1918** pointer given in its 3rd parameter.
    1919**
    1920** After the application has finished with the result from sqlite3_get_table(),
    1677** it should pass the result table pointer to sqlite3_free_table() in order to
    		1921** it must pass the result table pointer to sqlite3_free_table() in order to
    1678** release the memory that was malloced. Because of the way the
    1679** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
    1680** function must not try to call [sqlite3_free()] directly. Only
    1681** [sqlite3_free_table()] is able to release the memory properly and safely.
    1682**
    		1922** release the memory that was malloced. Because of the way the
    1923** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
    1924** function must not try to call [sqlite3_free()] directly. Only
    1925** [sqlite3_free_table()] is able to release the memory properly and safely.
    1926**
    1683** ^(The sqlite3_get_table() interface is implemented as a wrapper around
    		1927** The sqlite3_get_table() interface is implemented as a wrapper around
    1684** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
    1685** to any internal data structures of SQLite. It uses only the public
    1686** interface defined here. As a consequence, errors that occur in the
    1687** wrapper layer outside of the internal [sqlite3_exec()] call are not
    1688** reflected in subsequent calls to [sqlite3_errcode()] or
    		1928** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
    1929** to any internal data structures of SQLite. It uses only the public
    1930** interface defined here. As a consequence, errors that occur in the
    1931** wrapper layer outside of the internal [sqlite3_exec()] call are not
    1932** reflected in subsequent calls to [sqlite3_errcode()] or
    1689** [sqlite3_errmsg()].)^
    		1933** [sqlite3_errmsg()].
    1690*/
    1691SQLITE_API int sqlite3_get_table(
    1692 sqlite3 *db, /* An open database */
    1693 const char *zSql, /* SQL to be evaluated */
    1694 char ***pazResult, /* Results of the query */
    1695 int *pnRow, /* Number of result rows written here */
    1696 int *pnColumn, /* Number of result columns written here */
    1697 char **pzErrmsg /* Error msg written here */

    --- 8 unchanged lines hidden (view full) ---

    1706**
    1707** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
    1708** results into memory obtained from [sqlite3_malloc()].
    1709** The strings returned by these two routines should be
    1710** released by [sqlite3_free()]. ^Both routines return a
    1711** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
    1712** memory to hold the resulting string.
    1713**
    		1934*/
    1935SQLITE_API int sqlite3_get_table(
    1936 sqlite3 *db, /* An open database */
    1937 const char *zSql, /* SQL to be evaluated */
    1938 char ***pazResult, /* Results of the query */
    1939 int *pnRow, /* Number of result rows written here */
    1940 int *pnColumn, /* Number of result columns written here */
    1941 char **pzErrmsg /* Error msg written here */

    --- 8 unchanged lines hidden (view full) ---

    1950**
    1951** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
    1952** results into memory obtained from [sqlite3_malloc()].
    1953** The strings returned by these two routines should be
    1954** released by [sqlite3_free()]. ^Both routines return a
    1955** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
    1956** memory to hold the resulting string.
    1957**
    1714** ^(In sqlite3_snprintf() routine is similar to "snprintf()" from
    		1958** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
    1715** the standard C library. The result is written into the
    1716** buffer supplied as the second parameter whose size is given by
    1717** the first parameter. Note that the order of the
    1718** first two parameters is reversed from snprintf().)^ This is an
    1719** historical accident that cannot be fixed without breaking
    1720** backwards compatibility. ^(Note also that sqlite3_snprintf()
    1721** returns a pointer to its buffer instead of the number of
    1722** characters actually written into the buffer.)^ We admit that
    1723** the number of characters written would be a more useful return
    1724** value but we cannot change the implementation of sqlite3_snprintf()
    1725** now without breaking compatibility.
    1726**
    1727** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
    1728** guarantees that the buffer is always zero-terminated. ^The first
    1729** parameter "n" is the total size of the buffer, including space for
    1730** the zero terminator. So the longest string that can be completely
    1731** written will be n-1 characters.
    1732**
    		1959** the standard C library. The result is written into the
    1960** buffer supplied as the second parameter whose size is given by
    1961** the first parameter. Note that the order of the
    1962** first two parameters is reversed from snprintf().)^ This is an
    1963** historical accident that cannot be fixed without breaking
    1964** backwards compatibility. ^(Note also that sqlite3_snprintf()
    1965** returns a pointer to its buffer instead of the number of
    1966** characters actually written into the buffer.)^ We admit that
    1967** the number of characters written would be a more useful return
    1968** value but we cannot change the implementation of sqlite3_snprintf()
    1969** now without breaking compatibility.
    1970**
    1971** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
    1972** guarantees that the buffer is always zero-terminated. ^The first
    1973** parameter "n" is the total size of the buffer, including space for
    1974** the zero terminator. So the longest string that can be completely
    1975** written will be n-1 characters.
    1976**
    1977** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
    1978**
    1733** These routines all implement some additional formatting
    1734** options that are useful for constructing SQL statements.
    1735** All of the usual printf() formatting options apply. In addition, there
    1736** is are "%q", "%Q", and "%z" options.
    1737**
    1738** ^(The %q option works like %s in that it substitutes a null-terminated
    1739** string from the argument list. But %q also doubles every '\'' character.
    1740** %q is designed for use inside a string literal.)^ By doubling each '\''

    --- 47 unchanged lines hidden (view full) ---

    1788**
    1789** ^(The "%z" formatting option works like "%s" but with the
    1790** addition that after the string has been read and copied into
    1791** the result, [sqlite3_free()] is called on the input string.)^
    1792*/
    1793SQLITE_API char *sqlite3_mprintf(const char*,...);
    1794SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
    1795SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
    		1979** These routines all implement some additional formatting
    1980** options that are useful for constructing SQL statements.
    1981** All of the usual printf() formatting options apply. In addition, there
    1982** is are "%q", "%Q", and "%z" options.
    1983**
    1984** ^(The %q option works like %s in that it substitutes a null-terminated
    1985** string from the argument list. But %q also doubles every '\'' character.
    1986** %q is designed for use inside a string literal.)^ By doubling each '\''

    --- 47 unchanged lines hidden (view full) ---

    2034**
    2035** ^(The "%z" formatting option works like "%s" but with the
    2036** addition that after the string has been read and copied into
    2037** the result, [sqlite3_free()] is called on the input string.)^
    2038*/
    2039SQLITE_API char *sqlite3_mprintf(const char*,...);
    2040SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
    2041SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
    2042SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
    1796
    1797/*
    1798** CAPI3REF: Memory Allocation Subsystem
    1799**
    1800** The SQLite core uses these three routines for all of its own
    1801** internal memory allocation needs. "Core" in the previous sentence
    1802** does not include operating-system specific VFS implementation. The
    1803** Windows VFS uses native malloc() and free() for some operations.

    --- 29 unchanged lines hidden (view full) ---

    1833** of at least N bytes in size or NULL if sufficient memory is unavailable.
    1834** ^If M is the size of the prior allocation, then min(N,M) bytes
    1835** of the prior allocation are copied into the beginning of buffer returned
    1836** by sqlite3_realloc() and the prior allocation is freed.
    1837** ^If sqlite3_realloc() returns NULL, then the prior allocation
    1838** is not freed.
    1839**
    1840** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
    		2043
    2044/*
    2045** CAPI3REF: Memory Allocation Subsystem
    2046**
    2047** The SQLite core uses these three routines for all of its own
    2048** internal memory allocation needs. "Core" in the previous sentence
    2049** does not include operating-system specific VFS implementation. The
    2050** Windows VFS uses native malloc() and free() for some operations.

    --- 29 unchanged lines hidden (view full) ---

    2080** of at least N bytes in size or NULL if sufficient memory is unavailable.
    2081** ^If M is the size of the prior allocation, then min(N,M) bytes
    2082** of the prior allocation are copied into the beginning of buffer returned
    2083** by sqlite3_realloc() and the prior allocation is freed.
    2084** ^If sqlite3_realloc() returns NULL, then the prior allocation
    2085** is not freed.
    2086**
    2087** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
    1841** is always aligned to at least an 8 byte boundary.
    		2088** is always aligned to at least an 8 byte boundary, or to a
    2089** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
    2090** option is used.
    1842**
    1843** In SQLite version 3.5.0 and 3.5.1, it was possible to define
    1844** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
    1845** implementation of these routines to be omitted. That capability
    1846** is no longer provided. Only built-in memory allocators can be used.
    1847**
    1848** The Windows OS interface layer calls
    1849** the system malloc() and free() directly when converting

    --- 60 unchanged lines hidden (view full) ---

    1910** internally and without recourse to the [sqlite3_vfs] xRandomness
    1911** method.
    1912*/
    1913SQLITE_API void sqlite3_randomness(int N, void *P);
    1914
    1915/*
    1916** CAPI3REF: Compile-Time Authorization Callbacks
    1917**
    		2091**
    2092** In SQLite version 3.5.0 and 3.5.1, it was possible to define
    2093** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
    2094** implementation of these routines to be omitted. That capability
    2095** is no longer provided. Only built-in memory allocators can be used.
    2096**
    2097** The Windows OS interface layer calls
    2098** the system malloc() and free() directly when converting

    --- 60 unchanged lines hidden (view full) ---

    2159** internally and without recourse to the [sqlite3_vfs] xRandomness
    2160** method.
    2161*/
    2162SQLITE_API void sqlite3_randomness(int N, void *P);
    2163
    2164/*
    2165** CAPI3REF: Compile-Time Authorization Callbacks
    2166**
    1918** ^This routine registers a authorizer callback with a particular
    		2167** ^This routine registers an authorizer callback with a particular
    1919** [database connection], supplied in the first argument.
    1920** ^The authorizer callback is invoked as SQL statements are being compiled
    1921** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
    1922** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
    1923** points during the compilation process, as logic is being created
    1924** to perform various actions, the authorizer callback is invoked to
    1925** see if those actions are allowed. ^The authorizer callback should
    1926** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
    1927** specific action but allow the SQL statement to continue to be
    1928** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
    1929** rejected with an error. ^If the authorizer callback returns
    1930** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
    1931** then the [sqlite3_prepare_v2()] or equivalent call that triggered
    1932** the authorizer will fail with an error message.
    1933**
    1934** When the callback returns [SQLITE_OK], that means the operation
    1935** requested is ok. ^When the callback returns [SQLITE_DENY], the
    1936** [sqlite3_prepare_v2()] or equivalent call that triggered the
    1937** authorizer will fail with an error message explaining that
    		2168** [database connection], supplied in the first argument.
    2169** ^The authorizer callback is invoked as SQL statements are being compiled
    2170** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
    2171** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
    2172** points during the compilation process, as logic is being created
    2173** to perform various actions, the authorizer callback is invoked to
    2174** see if those actions are allowed. ^The authorizer callback should
    2175** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
    2176** specific action but allow the SQL statement to continue to be
    2177** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
    2178** rejected with an error. ^If the authorizer callback returns
    2179** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
    2180** then the [sqlite3_prepare_v2()] or equivalent call that triggered
    2181** the authorizer will fail with an error message.
    2182**
    2183** When the callback returns [SQLITE_OK], that means the operation
    2184** requested is ok. ^When the callback returns [SQLITE_DENY], the
    2185** [sqlite3_prepare_v2()] or equivalent call that triggered the
    2186** authorizer will fail with an error message explaining that
    1938** access is denied.
    		2187** access is denied.
    1939**
    1940** ^The first parameter to the authorizer callback is a copy of the third
    1941** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
    1942** to the callback is an integer [SQLITE_COPY | action code] that specifies
    1943** the particular action to be authorized. ^The third through sixth parameters
    1944** to the callback are zero-terminated strings that contain additional
    1945** details about the action to be authorized.
    1946**

    --- 30 unchanged lines hidden (view full) ---

    1977** The authorizer is disabled by default.
    1978**
    1979** The authorizer callback must not do anything that will modify
    1980** the database connection that invoked the authorizer callback.
    1981** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
    1982** database connections for the meaning of "modify" in this paragraph.
    1983**
    1984** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
    		2188**
    2189** ^The first parameter to the authorizer callback is a copy of the third
    2190** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
    2191** to the callback is an integer [SQLITE_COPY | action code] that specifies
    2192** the particular action to be authorized. ^The third through sixth parameters
    2193** to the callback are zero-terminated strings that contain additional
    2194** details about the action to be authorized.
    2195**

    --- 30 unchanged lines hidden (view full) ---

    2226** The authorizer is disabled by default.
    2227**
    2228** The authorizer callback must not do anything that will modify
    2229** the database connection that invoked the authorizer callback.
    2230** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
    2231** database connections for the meaning of "modify" in this paragraph.
    2232**
    2233** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
    1985** statement might be re-prepared during [sqlite3_step()] due to a
    		2234** statement might be re-prepared during [sqlite3_step()] due to a
    1986** schema change. Hence, the application should ensure that the
    1987** correct authorizer callback remains in place during the [sqlite3_step()].
    1988**
    1989** ^Note that the authorizer callback is invoked only during
    1990** [sqlite3_prepare()] or its variants. Authorization is not
    1991** performed during statement evaluation in [sqlite3_step()], unless
    1992** as stated in the previous paragraph, sqlite3_step() invokes
    1993** sqlite3_prepare_v2() to reprepare a statement after a schema change.

    --- 7 unchanged lines hidden (view full) ---

    2001/*
    2002** CAPI3REF: Authorizer Return Codes
    2003**
    2004** The [sqlite3_set_authorizer | authorizer callback function] must
    2005** return either [SQLITE_OK] or one of these two constants in order
    2006** to signal SQLite whether or not the action is permitted. See the
    2007** [sqlite3_set_authorizer | authorizer documentation] for additional
    2008** information.
    		2235** schema change. Hence, the application should ensure that the
    2236** correct authorizer callback remains in place during the [sqlite3_step()].
    2237**
    2238** ^Note that the authorizer callback is invoked only during
    2239** [sqlite3_prepare()] or its variants. Authorization is not
    2240** performed during statement evaluation in [sqlite3_step()], unless
    2241** as stated in the previous paragraph, sqlite3_step() invokes
    2242** sqlite3_prepare_v2() to reprepare a statement after a schema change.

    --- 7 unchanged lines hidden (view full) ---

    2250/*
    2251** CAPI3REF: Authorizer Return Codes
    2252**
    2253** The [sqlite3_set_authorizer | authorizer callback function] must
    2254** return either [SQLITE_OK] or one of these two constants in order
    2255** to signal SQLite whether or not the action is permitted. See the
    2256** [sqlite3_set_authorizer | authorizer documentation] for additional
    2257** information.
    2258**
    2259** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
    2260** from the [sqlite3_vtab_on_conflict()] interface.
    2009*/
    2010#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
    2011#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
    2012
    2013/*
    2014** CAPI3REF: Authorizer Action Codes
    2015**
    2016** The [sqlite3_set_authorizer()] interface registers a callback function

    --- 44 unchanged lines hidden (view full) ---

    2061#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
    2062#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
    2063#define SQLITE_FUNCTION 31 /* NULL Function Name */
    2064#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
    2065#define SQLITE_COPY 0 /* No longer used */
    2066
    2067/*
    2068** CAPI3REF: Tracing And Profiling Functions
    		2261*/
    2262#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
    2263#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
    2264
    2265/*
    2266** CAPI3REF: Authorizer Action Codes
    2267**
    2268** The [sqlite3_set_authorizer()] interface registers a callback function

    --- 44 unchanged lines hidden (view full) ---

    2313#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
    2314#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
    2315#define SQLITE_FUNCTION 31 /* NULL Function Name */
    2316#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
    2317#define SQLITE_COPY 0 /* No longer used */
    2318
    2319/*
    2320** CAPI3REF: Tracing And Profiling Functions
    2069** EXPERIMENTAL
    2070**
    2071** These routines register callback functions that can be used for
    2072** tracing and profiling the execution of SQL statements.
    2073**
    2074** ^The callback function registered by sqlite3_trace() is invoked at
    2075** various times when an SQL statement is being run by [sqlite3_step()].
    2076** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
    2077** SQL statement text as the statement first begins executing.
    2078** ^(Additional sqlite3_trace() callbacks might occur
    2079** as each triggered subprogram is entered. The callbacks for triggers
    2080** contain a UTF-8 SQL comment that identifies the trigger.)^
    2081**
    2082** ^The callback function registered by sqlite3_profile() is invoked
    2083** as each SQL statement finishes. ^The profile callback contains
    2084** the original statement text and an estimate of wall-clock time
    		2321**
    2322** These routines register callback functions that can be used for
    2323** tracing and profiling the execution of SQL statements.
    2324**
    2325** ^The callback function registered by sqlite3_trace() is invoked at
    2326** various times when an SQL statement is being run by [sqlite3_step()].
    2327** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
    2328** SQL statement text as the statement first begins executing.
    2329** ^(Additional sqlite3_trace() callbacks might occur
    2330** as each triggered subprogram is entered. The callbacks for triggers
    2331** contain a UTF-8 SQL comment that identifies the trigger.)^
    2332**
    2333** ^The callback function registered by sqlite3_profile() is invoked
    2334** as each SQL statement finishes. ^The profile callback contains
    2335** the original statement text and an estimate of wall-clock time
    2085** of how long that statement took to run.
    		2336** of how long that statement took to run. ^The profile callback
    2337** time is in units of nanoseconds, however the current implementation
    2338** is only capable of millisecond resolution so the six least significant
    2339** digits in the time are meaningless. Future versions of SQLite
    2340** might provide greater resolution on the profiler callback. The
    2341** sqlite3_profile() function is considered experimental and is
    2342** subject to change in future versions of SQLite.
    2086*/
    		2343*/
    2087SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
    		2344SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
    2088SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
    2089 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
    2090
    2091/*
    2092** CAPI3REF: Query Progress Callbacks
    2093**
    		2345SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
    2346 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
    2347
    2348/*
    2349** CAPI3REF: Query Progress Callbacks
    2350**
    2094** ^This routine configures a callback function - the
    2095** progress callback - that is invoked periodically during long
    2096** running calls to [sqlite3_exec()], [sqlite3_step()] and
    2097** [sqlite3_get_table()]. An example use for this
    		2351** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
    2352** function X to be invoked periodically during long running calls to
    2353** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
    2354** database connection D. An example use for this
    2098** interface is to keep a GUI updated during a large query.
    2099**
    		2355** interface is to keep a GUI updated during a large query.
    2356**
    2357** ^The parameter P is passed through as the only parameter to the
    2358** callback function X. ^The parameter N is the number of
    2359** [virtual machine instructions] that are evaluated between successive
    2360** invocations of the callback X.
    2361**
    2362** ^Only a single progress handler may be defined at one time per
    2363** [database connection]; setting a new progress handler cancels the
    2364** old one. ^Setting parameter X to NULL disables the progress handler.
    2365** ^The progress handler is also disabled by setting N to a value less
    2366** than 1.
    2367**
    2100** ^If the progress callback returns non-zero, the operation is
    2101** interrupted. This feature can be used to implement a
    2102** "Cancel" button on a GUI progress dialog box.
    2103**
    		2368** ^If the progress callback returns non-zero, the operation is
    2369** interrupted. This feature can be used to implement a
    2370** "Cancel" button on a GUI progress dialog box.
    2371**
    2104** The progress handler must not do anything that will modify
    		2372** The progress handler callback must not do anything that will modify
    2105** the database connection that invoked the progress handler.
    2106** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
    2107** database connections for the meaning of "modify" in this paragraph.
    2108**
    2109*/
    2110SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
    2111
    2112/*
    2113** CAPI3REF: Opening A New Database Connection
    2114**
    		2373** the database connection that invoked the progress handler.
    2374** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
    2375** database connections for the meaning of "modify" in this paragraph.
    2376**
    2377*/
    2378SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
    2379
    2380/*
    2381** CAPI3REF: Opening A New Database Connection
    2382**
    2115** ^These routines open an SQLite database file whose name is given by the
    		2383** ^These routines open an SQLite database file as specified by the
    2116** filename argument. ^The filename argument is interpreted as UTF-8 for
    2117** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
    2118** order for sqlite3_open16(). ^(A [database connection] handle is usually
    2119** returned in *ppDb, even if an error occurs. The only exception is that
    2120** if SQLite is unable to allocate memory to hold the [sqlite3] object,
    2121** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
    2122** object.)^ ^(If the database is opened (and/or created) successfully, then
    2123** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The

    --- 8 unchanged lines hidden (view full) ---

    2132** Whether or not an error occurs when it is opened, resources
    2133** associated with the [database connection] handle should be released by
    2134** passing it to [sqlite3_close()] when it is no longer required.
    2135**
    2136** The sqlite3_open_v2() interface works like sqlite3_open()
    2137** except that it accepts two additional parameters for additional control
    2138** over the new database connection. ^(The flags parameter to
    2139** sqlite3_open_v2() can take one of
    		2384** filename argument. ^The filename argument is interpreted as UTF-8 for
    2385** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
    2386** order for sqlite3_open16(). ^(A [database connection] handle is usually
    2387** returned in *ppDb, even if an error occurs. The only exception is that
    2388** if SQLite is unable to allocate memory to hold the [sqlite3] object,
    2389** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
    2390** object.)^ ^(If the database is opened (and/or created) successfully, then
    2391** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The

    --- 8 unchanged lines hidden (view full) ---

    2400** Whether or not an error occurs when it is opened, resources
    2401** associated with the [database connection] handle should be released by
    2402** passing it to [sqlite3_close()] when it is no longer required.
    2403**
    2404** The sqlite3_open_v2() interface works like sqlite3_open()
    2405** except that it accepts two additional parameters for additional control
    2406** over the new database connection. ^(The flags parameter to
    2407** sqlite3_open_v2() can take one of
    2140** the following three values, optionally combined with the
    		2408** the following three values, optionally combined with the
    2141** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
    		2409** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
    2142** and/or [SQLITE_OPEN_PRIVATECACHE] flags:)^
    		2410** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
    2143**
    2144** <dl>
    2145** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
    2146** <dd>The database is opened in read-only mode. If the database does not
    2147** already exist, an error is returned.</dd>)^
    2148**
    2149** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
    2150** <dd>The database is opened for reading and writing if possible, or reading
    2151** only if the file is write protected by the operating system. In either
    2152** case the database must already exist, otherwise an error is returned.</dd>)^
    2153**
    2154** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
    		2411**
    2412** <dl>
    2413** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
    2414** <dd>The database is opened in read-only mode. If the database does not
    2415** already exist, an error is returned.</dd>)^
    2416**
    2417** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
    2418** <dd>The database is opened for reading and writing if possible, or reading
    2419** only if the file is write protected by the operating system. In either
    2420** case the database must already exist, otherwise an error is returned.</dd>)^
    2421**
    2422** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
    2155** <dd>The database is opened for reading and writing, and is creates it if
    		2423** <dd>The database is opened for reading and writing, and is created if
    2156** it does not already exist. This is the behavior that is always used for
    2157** sqlite3_open() and sqlite3_open16().</dd>)^
    2158** </dl>
    2159**
    2160** If the 3rd parameter to sqlite3_open_v2() is not one of the
    		2424** it does not already exist. This is the behavior that is always used for
    2425** sqlite3_open() and sqlite3_open16().</dd>)^
    2426** </dl>
    2427**
    2428** If the 3rd parameter to sqlite3_open_v2() is not one of the
    2161** combinations shown above or one of the combinations shown above combined
    2162** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX],
    2163** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags,
    		2429** combinations shown above optionally combined with other
    2430** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
    2164** then the behavior is undefined.
    2165**
    2166** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
    2167** opens in the multi-thread [threading mode] as long as the single-thread
    2168** mode has not been set at compile-time or start-time. ^If the
    2169** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
    2170** in the serialized [threading mode] unless single-thread was
    2171** previously selected at compile-time or start-time.
    2172** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
    2173** eligible to use [shared cache mode], regardless of whether or not shared
    2174** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
    2175** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
    2176** participate in [shared cache mode] even if it is enabled.
    2177**
    		2431** then the behavior is undefined.
    2432**
    2433** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
    2434** opens in the multi-thread [threading mode] as long as the single-thread
    2435** mode has not been set at compile-time or start-time. ^If the
    2436** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
    2437** in the serialized [threading mode] unless single-thread was
    2438** previously selected at compile-time or start-time.
    2439** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
    2440** eligible to use [shared cache mode], regardless of whether or not shared
    2441** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
    2442** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
    2443** participate in [shared cache mode] even if it is enabled.
    2444**
    2445** ^The fourth parameter to sqlite3_open_v2() is the name of the
    2446** [sqlite3_vfs] object that defines the operating system interface that
    2447** the new database connection should use. ^If the fourth parameter is
    2448** a NULL pointer then the default [sqlite3_vfs] object is used.
    2449**
    2178** ^If the filename is ":memory:", then a private, temporary in-memory database
    2179** is created for the connection. ^This in-memory database will vanish when
    2180** the database connection is closed. Future versions of SQLite might
    2181** make use of additional special filenames that begin with the ":" character.
    2182** It is recommended that when a database filename actually does begin with
    2183** a ":" character you should prefix the filename with a pathname such as
    2184** "./" to avoid ambiguity.
    2185**
    2186** ^If the filename is an empty string, then a private, temporary
    2187** on-disk database will be created. ^This private database will be
    2188** automatically deleted as soon as the database connection is closed.
    2189**
    		2450** ^If the filename is ":memory:", then a private, temporary in-memory database
    2451** is created for the connection. ^This in-memory database will vanish when
    2452** the database connection is closed. Future versions of SQLite might
    2453** make use of additional special filenames that begin with the ":" character.
    2454** It is recommended that when a database filename actually does begin with
    2455** a ":" character you should prefix the filename with a pathname such as
    2456** "./" to avoid ambiguity.
    2457**
    2458** ^If the filename is an empty string, then a private, temporary
    2459** on-disk database will be created. ^This private database will be
    2460** automatically deleted as soon as the database connection is closed.
    2461**
    2190** ^The fourth parameter to sqlite3_open_v2() is the name of the
    2191** [sqlite3_vfs] object that defines the operating system interface that
    2192** the new database connection should use. ^If the fourth parameter is
    2193** a NULL pointer then the default [sqlite3_vfs] object is used.
    		2462** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
    2194**
    		2463**
    2464** ^If [URI filename] interpretation is enabled, and the filename argument
    2465** begins with "file:", then the filename is interpreted as a URI. ^URI
    2466** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
    2467** set in the fourth argument to sqlite3_open_v2(), or if it has
    2468** been enabled globally using the [SQLITE_CONFIG_URI] option with the
    2469** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
    2470** As of SQLite version 3.7.7, URI filename interpretation is turned off
    2471** by default, but future releases of SQLite might enable URI filename
    2472** interpretation by default. See "[URI filenames]" for additional
    2473** information.
    2474**
    2475** URI filenames are parsed according to RFC 3986. ^If the URI contains an
    2476** authority, then it must be either an empty string or the string
    2477** "localhost". ^If the authority is not an empty string or "localhost", an
    2478** error is returned to the caller. ^The fragment component of a URI, if
    2479** present, is ignored.
    2480**
    2481** ^SQLite uses the path component of the URI as the name of the disk file
    2482** which contains the database. ^If the path begins with a '/' character,
    2483** then it is interpreted as an absolute path. ^If the path does not begin
    2484** with a '/' (meaning that the authority section is omitted from the URI)
    2485** then the path is interpreted as a relative path.
    2486** ^On windows, the first component of an absolute path
    2487** is a drive specification (e.g. "C:").
    2488**
    2489** [[core URI query parameters]]
    2490** The query component of a URI may contain parameters that are interpreted
    2491** either by SQLite itself, or by a [VFS | custom VFS implementation].
    2492** SQLite interprets the following three query parameters:
    2493**
    2494** <ul>
    2495** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
    2496** a VFS object that provides the operating system interface that should
    2497** be used to access the database file on disk. ^If this option is set to
    2498** an empty string the default VFS object is used. ^Specifying an unknown
    2499** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
    2500** present, then the VFS specified by the option takes precedence over
    2501** the value passed as the fourth parameter to sqlite3_open_v2().
    2502**
    2503** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw" or
    2504** "rwc". Attempting to set it to any other value is an error)^.
    2505** ^If "ro" is specified, then the database is opened for read-only
    2506** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
    2507** third argument to sqlite3_prepare_v2(). ^If the mode option is set to
    2508** "rw", then the database is opened for read-write (but not create)
    2509** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
    2510** been set. ^Value "rwc" is equivalent to setting both
    2511** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If sqlite3_open_v2() is
    2512** used, it is an error to specify a value for the mode parameter that is
    2513** less restrictive than that specified by the flags passed as the third
    2514** parameter.
    2515**
    2516** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
    2517** "private". ^Setting it to "shared" is equivalent to setting the
    2518** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
    2519** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
    2520** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
    2521** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
    2522** a URI filename, its value overrides any behaviour requested by setting
    2523** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
    2524** </ul>
    2525**
    2526** ^Specifying an unknown parameter in the query component of a URI is not an
    2527** error. Future versions of SQLite might understand additional query
    2528** parameters. See "[query parameters with special meaning to SQLite]" for
    2529** additional information.
    2530**
    2531** [[URI filename examples]] <h3>URI filename examples</h3>
    2532**
    2533** <table border="1" align=center cellpadding=5>
    2534** <tr><th> URI filenames <th> Results
    2535** <tr><td> file:data.db <td>
    2536** Open the file "data.db" in the current directory.
    2537** <tr><td> file:/home/fred/data.db<br>
    2538** file:///home/fred/data.db <br>
    2539** file://localhost/home/fred/data.db <br> <td>
    2540** Open the database file "/home/fred/data.db".
    2541** <tr><td> file://darkstar/home/fred/data.db <td>
    2542** An error. "darkstar" is not a recognized authority.
    2543** <tr><td style="white-space:nowrap">
    2544** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
    2545** <td> Windows only: Open the file "data.db" on fred's desktop on drive
    2546** C:. Note that the %20 escaping in this example is not strictly
    2547** necessary - space characters can be used literally
    2548** in URI filenames.
    2549** <tr><td> file:data.db?mode=ro&cache=private <td>
    2550** Open file "data.db" in the current directory for read-only access.
    2551** Regardless of whether or not shared-cache mode is enabled by
    2552** default, use a private cache.
    2553** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>
    2554** Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
    2555** <tr><td> file:data.db?mode=readonly <td>
    2556** An error. "readonly" is not a valid option for the "mode" parameter.
    2557** </table>
    2558**
    2559** ^URI hexadecimal escape sequences (%HH) are supported within the path and
    2560** query components of a URI. A hexadecimal escape sequence consists of a
    2561** percent sign - "%" - followed by exactly two hexadecimal digits
    2562** specifying an octet value. ^Before the path or query components of a
    2563** URI filename are interpreted, they are encoded using UTF-8 and all
    2564** hexadecimal escape sequences replaced by a single byte containing the
    2565** corresponding octet. If this process generates an invalid UTF-8 encoding,
    2566** the results are undefined.
    2567**
    2195** <b>Note to Windows users:</b> The encoding used for the filename argument
    2196** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
    2197** codepage is currently defined. Filenames containing international
    2198** characters must be converted to UTF-8 prior to passing them into
    2199** sqlite3_open() or sqlite3_open_v2().
    2200*/
    2201SQLITE_API int sqlite3_open(
    2202 const char *filename, /* Database filename (UTF-8) */

    --- 6 unchanged lines hidden (view full) ---

    2209SQLITE_API int sqlite3_open_v2(
    2210 const char *filename, /* Database filename (UTF-8) */
    2211 sqlite3 **ppDb, /* OUT: SQLite db handle */
    2212 int flags, /* Flags */
    2213 const char *zVfs /* Name of VFS module to use */
    2214);
    2215
    2216/*
    		2568** <b>Note to Windows users:</b> The encoding used for the filename argument
    2569** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
    2570** codepage is currently defined. Filenames containing international
    2571** characters must be converted to UTF-8 prior to passing them into
    2572** sqlite3_open() or sqlite3_open_v2().
    2573*/
    2574SQLITE_API int sqlite3_open(
    2575 const char *filename, /* Database filename (UTF-8) */

    --- 6 unchanged lines hidden (view full) ---

    2582SQLITE_API int sqlite3_open_v2(
    2583 const char *filename, /* Database filename (UTF-8) */
    2584 sqlite3 **ppDb, /* OUT: SQLite db handle */
    2585 int flags, /* Flags */
    2586 const char *zVfs /* Name of VFS module to use */
    2587);
    2588
    2589/*
    2590** CAPI3REF: Obtain Values For URI Parameters
    2591**
    2592** This is a utility routine, useful to VFS implementations, that checks
    2593** to see if a database file was a URI that contained a specific query
    2594** parameter, and if so obtains the value of the query parameter.
    2595**
    2596** The zFilename argument is the filename pointer passed into the xOpen()
    2597** method of a VFS implementation. The zParam argument is the name of the
    2598** query parameter we seek. This routine returns the value of the zParam
    2599** parameter if it exists. If the parameter does not exist, this routine
    2600** returns a NULL pointer.
    2601**
    2602** If the zFilename argument to this function is not a pointer that SQLite
    2603** passed into the xOpen VFS method, then the behavior of this routine
    2604** is undefined and probably undesirable.
    2605*/
    2606SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
    2607
    2608
    2609/*
    2217** CAPI3REF: Error Codes And Messages
    2218**
    2219** ^The sqlite3_errcode() interface returns the numeric [result code] or
    2220** [extended result code] for the most recent failed sqlite3_* API call
    2221** associated with a [database connection]. If a prior API call failed
    2222** but the most recent API call succeeded, the return value from
    2223** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
    		2610** CAPI3REF: Error Codes And Messages
    2611**
    2612** ^The sqlite3_errcode() interface returns the numeric [result code] or
    2613** [extended result code] for the most recent failed sqlite3_* API call
    2614** associated with a [database connection]. If a prior API call failed
    2615** but the most recent API call succeeded, the return value from
    2616** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
    2224** interface is the same except that it always returns the
    		2617** interface is the same except that it always returns the
    2225** [extended result code] even when extended result codes are
    2226** disabled.
    2227**
    2228** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
    2229** text that describes the error, as either UTF-8 or UTF-16 respectively.
    2230** ^(Memory to hold the error message string is managed internally.
    2231** The application does not need to worry about freeing the result.
    2232** However, the error string might be overwritten or deallocated by

    --- 47 unchanged lines hidden (view full) ---

    2280/*
    2281** CAPI3REF: Run-time Limits
    2282**
    2283** ^(This interface allows the size of various constructs to be limited
    2284** on a connection by connection basis. The first parameter is the
    2285** [database connection] whose limit is to be set or queried. The
    2286** second parameter is one of the [limit categories] that define a
    2287** class of constructs to be size limited. The third parameter is the
    		2618** [extended result code] even when extended result codes are
    2619** disabled.
    2620**
    2621** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
    2622** text that describes the error, as either UTF-8 or UTF-16 respectively.
    2623** ^(Memory to hold the error message string is managed internally.
    2624** The application does not need to worry about freeing the result.
    2625** However, the error string might be overwritten or deallocated by

    --- 47 unchanged lines hidden (view full) ---

    2673/*
    2674** CAPI3REF: Run-time Limits
    2675**
    2676** ^(This interface allows the size of various constructs to be limited
    2677** on a connection by connection basis. The first parameter is the
    2678** [database connection] whose limit is to be set or queried. The
    2679** second parameter is one of the [limit categories] that define a
    2680** class of constructs to be size limited. The third parameter is the
    2288** new limit for that construct. The function returns the old limit.)^
    		2681** new limit for that construct.)^
    2289**
    2290** ^If the new limit is a negative number, the limit is unchanged.
    		2682**
    2683** ^If the new limit is a negative number, the limit is unchanged.
    2291** ^(For the limit category of SQLITE_LIMIT_XYZ there is a
    		2684** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
    2292** [limits | hard upper bound]
    		2685** [limits | hard upper bound]
    2293** set by a compile-time C preprocessor macro named
    2294** [limits | SQLITE_MAX_XYZ].
    		2686** set at compile-time by a C preprocessor macro called
    2687** [limits | SQLITE_MAX_<i>NAME</i>].
    2295** (The "_LIMIT_" in the name is changed to "_MAX_".))^
    2296** ^Attempts to increase a limit above its hard upper bound are
    2297** silently truncated to the hard upper bound.
    2298**
    		2688** (The "_LIMIT_" in the name is changed to "_MAX_".))^
    2689** ^Attempts to increase a limit above its hard upper bound are
    2690** silently truncated to the hard upper bound.
    2691**
    2692** ^Regardless of whether or not the limit was changed, the
    2693** [sqlite3_limit()] interface returns the prior value of the limit.
    2694** ^Hence, to find the current value of a limit without changing it,
    2695** simply invoke this interface with the third parameter set to -1.
    2696**
    2299** Run-time limits are intended for use in applications that manage
    2300** both their own internal database and also databases that are controlled
    2301** by untrusted external sources. An example application might be a
    2302** web browser that has its own databases for storing history and
    2303** separate databases controlled by JavaScript applications downloaded
    2304** off the Internet. The internal databases can be given the
    2305** large, default limits. Databases managed by external sources can
    2306** be given much smaller limits designed to prevent a denial of service

    --- 11 unchanged lines hidden (view full) ---

    2318** KEYWORDS: {limit category} {*limit categories}
    2319**
    2320** These constants define various performance limits
    2321** that can be lowered at run-time using [sqlite3_limit()].
    2322** The synopsis of the meanings of the various limits is shown below.
    2323** Additional information is available at [limits | Limits in SQLite].
    2324**
    2325** <dl>
    		2697** Run-time limits are intended for use in applications that manage
    2698** both their own internal database and also databases that are controlled
    2699** by untrusted external sources. An example application might be a
    2700** web browser that has its own databases for storing history and
    2701** separate databases controlled by JavaScript applications downloaded
    2702** off the Internet. The internal databases can be given the
    2703** large, default limits. Databases managed by external sources can
    2704** be given much smaller limits designed to prevent a denial of service

    --- 11 unchanged lines hidden (view full) ---

    2716** KEYWORDS: {limit category} {*limit categories}
    2717**
    2718** These constants define various performance limits
    2719** that can be lowered at run-time using [sqlite3_limit()].
    2720** The synopsis of the meanings of the various limits is shown below.
    2721** Additional information is available at [limits | Limits in SQLite].
    2722**
    2723** <dl>
    2326** ^(
    SQLITE_LIMIT_LENGTH

    2327**
    The maximum size of any string or BLOB or table row.
    )^
    		2724** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
    2725** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
    2328**
    		2726**
    2329** ^(
    SQLITE_LIMIT_SQL_LENGTH

    		2727** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
    2330** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
    2331**
    		2728** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
    2729**
    2332** ^(
    SQLITE_LIMIT_COLUMN

    		2730** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
    2333** <dd>The maximum number of columns in a table definition or in the
    2334** result set of a [SELECT] or the maximum number of columns in an index
    2335** or in an ORDER BY or GROUP BY clause.</dd>)^
    2336**
    		2731** <dd>The maximum number of columns in a table definition or in the
    2732** result set of a [SELECT] or the maximum number of columns in an index
    2733** or in an ORDER BY or GROUP BY clause.</dd>)^
    2734**
    2337** ^(
    SQLITE_LIMIT_EXPR_DEPTH

    		2735** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
    2338** <dd>The maximum depth of the parse tree on any expression.</dd>)^
    2339**
    		2736** <dd>The maximum depth of the parse tree on any expression.</dd>)^
    2737**
    2340** ^(
    SQLITE_LIMIT_COMPOUND_SELECT

    		2738** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
    2341** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
    2342**
    		2739** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
    2740**
    2343** ^(
    SQLITE_LIMIT_VDBE_OP

    		2741** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
    2344** <dd>The maximum number of instructions in a virtual machine program
    		2742** <dd>The maximum number of instructions in a virtual machine program
    2345** used to implement an SQL statement.</dd>)^
    		2743** used to implement an SQL statement. This limit is not currently
    2744** enforced, though that might be added in some future release of
    2745** SQLite.</dd>)^
    2346**
    		2746**
    2347** ^(
    SQLITE_LIMIT_FUNCTION_ARG

    		2747** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
    2348** <dd>The maximum number of arguments on a function.</dd>)^
    2349**
    		2748** <dd>The maximum number of arguments on a function.</dd>)^
    2749**
    2350** ^(
    SQLITE_LIMIT_ATTACHED

    		2750** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
    2351** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
    2352**
    		2751** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
    2752**
    2753** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
    2353** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
    2354** <dd>The maximum length of the pattern argument to the [LIKE] or
    2355** [GLOB] operators.</dd>)^
    2356**
    		2754** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
    2755** <dd>The maximum length of the pattern argument to the [LIKE] or
    2756** [GLOB] operators.</dd>)^
    2757**
    2758** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
    2357** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
    		2759** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
    2358** <dd>The maximum number of variables in an SQL statement that can
    2359** be bound.</dd>)^
    		2760** <dd>The maximum index number of any [parameter] in an SQL statement.)^
    2360**
    		2761**
    2361** ^(
    SQLITE_LIMIT_TRIGGER_DEPTH

    		2762** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
    2362** <dd>The maximum depth of recursion for triggers.</dd>)^
    2363** </dl>
    2364*/
    2365#define SQLITE_LIMIT_LENGTH 0
    2366#define SQLITE_LIMIT_SQL_LENGTH 1
    2367#define SQLITE_LIMIT_COLUMN 2
    2368#define SQLITE_LIMIT_EXPR_DEPTH 3
    2369#define SQLITE_LIMIT_COMPOUND_SELECT 4

    --- 53 unchanged lines hidden (view full) ---

    2423** that is returned (the [sqlite3_stmt] object) contains a copy of the
    2424** original SQL text. This causes the [sqlite3_step()] interface to
    2425** behave differently in three ways:
    2426**
    2427** <ol>
    2428** <li>
    2429** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
    2430** always used to do, [sqlite3_step()] will automatically recompile the SQL
    		2763** <dd>The maximum depth of recursion for triggers.</dd>)^
    2764** </dl>
    2765*/
    2766#define SQLITE_LIMIT_LENGTH 0
    2767#define SQLITE_LIMIT_SQL_LENGTH 1
    2768#define SQLITE_LIMIT_COLUMN 2
    2769#define SQLITE_LIMIT_EXPR_DEPTH 3
    2770#define SQLITE_LIMIT_COMPOUND_SELECT 4

    --- 53 unchanged lines hidden (view full) ---

    2824** that is returned (the [sqlite3_stmt] object) contains a copy of the
    2825** original SQL text. This causes the [sqlite3_step()] interface to
    2826** behave differently in three ways:
    2827**
    2828** <ol>
    2829** <li>
    2830** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
    2831** always used to do, [sqlite3_step()] will automatically recompile the SQL
    2431** statement and try to run it again. ^If the schema has changed in
    2432** a way that makes the statement no longer valid, [sqlite3_step()] will still
    2433** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
    2434** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
    2435** error go away. Note: use [sqlite3_errmsg()] to find the text
    2436** of the parsing error that results in an [SQLITE_SCHEMA] return.
    		2832** statement and try to run it again.
    2437** </li>
    2438**
    2439** <li>
    2440** ^When an error occurs, [sqlite3_step()] will return one of the detailed
    2441** [error codes] or [extended error codes]. ^The legacy behavior was that
    2442** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
    2443** and the application would have to make a second call to [sqlite3_reset()]
    2444** in order to find the underlying cause of the problem. With the "v2" prepare
    2445** interfaces, the underlying reason for the error is returned immediately.
    2446** </li>
    2447**
    2448** <li>
    		2833** </li>
    2834**
    2835** <li>
    2836** ^When an error occurs, [sqlite3_step()] will return one of the detailed
    2837** [error codes] or [extended error codes]. ^The legacy behavior was that
    2838** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
    2839** and the application would have to make a second call to [sqlite3_reset()]
    2840** in order to find the underlying cause of the problem. With the "v2" prepare
    2841** interfaces, the underlying reason for the error is returned immediately.
    2842** </li>
    2843**
    2844** <li>
    2449** ^If the value of a [parameter | host parameter] in the WHERE clause might
    2450** change the query plan for a statement, then the statement may be
    2451** automatically recompiled (as if there had been a schema change) on the first
    2452** [sqlite3_step()] call following any change to the
    2453** [sqlite3_bind_text | bindings] of the [parameter].
    		2845** ^If the specific value bound to [parameter | host parameter] in the
    2846** WHERE clause might influence the choice of query plan for a statement,
    2847** then the statement will be automatically recompiled, as if there had been
    2848** a schema change, on the first [sqlite3_step()] call following any change
    2849** to the [sqlite3_bind_text | bindings] of that [parameter].
    2850** ^The specific value of WHERE-clause [parameter] might influence the
    2851** choice of query plan if the parameter is the left-hand side of a [LIKE]
    2852** or [GLOB] operator or if the parameter is compared to an indexed column
    2853** and the [SQLITE_ENABLE_STAT2] compile-time option is enabled.
    2854** the
    2454** </li>
    2455** </ol>
    2456*/
    2457SQLITE_API int sqlite3_prepare(
    2458 sqlite3 *db, /* Database handle */
    2459 const char *zSql, /* SQL statement, UTF-8 encoded */
    2460 int nByte, /* Maximum length of zSql in bytes. */
    2461 sqlite3_stmt **ppStmt, /* OUT: Statement handle */

    --- 26 unchanged lines hidden (view full) ---

    2488**
    2489** ^This interface can be used to retrieve a saved copy of the original
    2490** SQL text used to create a [prepared statement] if that statement was
    2491** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
    2492*/
    2493SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
    2494
    2495/*
    		2855** </li>
    2856** </ol>
    2857*/
    2858SQLITE_API int sqlite3_prepare(
    2859 sqlite3 *db, /* Database handle */
    2860 const char *zSql, /* SQL statement, UTF-8 encoded */
    2861 int nByte, /* Maximum length of zSql in bytes. */
    2862 sqlite3_stmt **ppStmt, /* OUT: Statement handle */

    --- 26 unchanged lines hidden (view full) ---

    2889**
    2890** ^This interface can be used to retrieve a saved copy of the original
    2891** SQL text used to create a [prepared statement] if that statement was
    2892** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
    2893*/
    2894SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
    2895
    2896/*
    2897** CAPI3REF: Determine If An SQL Statement Writes The Database
    2898**
    2899** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
    2900** and only if the [prepared statement] X makes no direct changes to
    2901** the content of the database file.
    2902**
    2903** Note that [application-defined SQL functions] or
    2904** [virtual tables] might change the database indirectly as a side effect.
    2905** ^(For example, if an application defines a function "eval()" that
    2906** calls [sqlite3_exec()], then the following SQL statement would
    2907** change the database file through side-effects:
    2908**
    2909** <blockquote><pre>
    2910** SELECT eval('DELETE FROM t1') FROM t2;
    2911** </pre></blockquote>
    2912**
    2913** But because the [SELECT] statement does not change the database file
    2914** directly, sqlite3_stmt_readonly() would still return true.)^
    2915**
    2916** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
    2917** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
    2918** since the statements themselves do not actually modify the database but
    2919** rather they control the timing of when other statements modify the
    2920** database. ^The [ATTACH] and [DETACH] statements also cause
    2921** sqlite3_stmt_readonly() to return true since, while those statements
    2922** change the configuration of a database connection, they do not make
    2923** changes to the content of the database files on disk.
    2924*/
    2925SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
    2926
    2927/*
    2496** CAPI3REF: Dynamically Typed Value Object
    2497** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
    2498**
    2499** SQLite uses the sqlite3_value object to represent all values
    2500** that can be stored in a database table. SQLite uses dynamic typing
    2501** for the values it stores. ^Values stored in sqlite3_value objects
    2502** can be integers, floating point values, strings, BLOBs, or NULL.
    2503**
    2504** An sqlite3_value object may be either "protected" or "unprotected".
    2505** Some interfaces require a protected sqlite3_value. Other interfaces
    2506** will accept either a protected or an unprotected sqlite3_value.
    2507** Every interface that accepts sqlite3_value arguments specifies
    2508** whether or not it requires a protected sqlite3_value.
    2509**
    2510** The terms "protected" and "unprotected" refer to whether or not
    		2928** CAPI3REF: Dynamically Typed Value Object
    2929** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
    2930**
    2931** SQLite uses the sqlite3_value object to represent all values
    2932** that can be stored in a database table. SQLite uses dynamic typing
    2933** for the values it stores. ^Values stored in sqlite3_value objects
    2934** can be integers, floating point values, strings, BLOBs, or NULL.
    2935**
    2936** An sqlite3_value object may be either "protected" or "unprotected".
    2937** Some interfaces require a protected sqlite3_value. Other interfaces
    2938** will accept either a protected or an unprotected sqlite3_value.
    2939** Every interface that accepts sqlite3_value arguments specifies
    2940** whether or not it requires a protected sqlite3_value.
    2941**
    2942** The terms "protected" and "unprotected" refer to whether or not
    2511** a mutex is held. A internal mutex is held for a protected
    		2943** a mutex is held. An internal mutex is held for a protected
    2512** sqlite3_value object but no mutex is held for an unprotected
    2513** sqlite3_value object. If SQLite is compiled to be single-threaded
    2514** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
    		2944** sqlite3_value object but no mutex is held for an unprotected
    2945** sqlite3_value object. If SQLite is compiled to be single-threaded
    2946** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
    2515** or if SQLite is run in one of reduced mutex modes
    		2947** or if SQLite is run in one of reduced mutex modes
    2516** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
    2517** then there is no distinction between protected and unprotected
    2518** sqlite3_value objects and they can be used interchangeably. However,
    2519** for maximum code portability it is recommended that applications
    		2948** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
    2949** then there is no distinction between protected and unprotected
    2950** sqlite3_value objects and they can be used interchangeably. However,
    2951** for maximum code portability it is recommended that applications
    2520** still make the distinction between between protected and unprotected
    		2952** still make the distinction between protected and unprotected
    2521** sqlite3_value objects even when not strictly required.
    2522**
    2523** ^The sqlite3_value objects that are passed as parameters into the
    2524** implementation of [application-defined SQL functions] are protected.
    2525** ^The sqlite3_value object returned by
    2526** [sqlite3_column_value()] is unprotected.
    2527** Unprotected sqlite3_value objects may only be used with
    2528** [sqlite3_result_value()] and [sqlite3_bind_value()].

    --- 29 unchanged lines hidden (view full) ---

    2558** <li> ?
    2559** <li> ?NNN
    2560** <li> :VVV
    2561** <li> @VVV
    2562** <li> $VVV
    2563** </ul>
    2564**
    2565** In the templates above, NNN represents an integer literal,
    		2953** sqlite3_value objects even when not strictly required.
    2954**
    2955** ^The sqlite3_value objects that are passed as parameters into the
    2956** implementation of [application-defined SQL functions] are protected.
    2957** ^The sqlite3_value object returned by
    2958** [sqlite3_column_value()] is unprotected.
    2959** Unprotected sqlite3_value objects may only be used with
    2960** [sqlite3_result_value()] and [sqlite3_bind_value()].

    --- 29 unchanged lines hidden (view full) ---

    2990** <li> ?
    2991** <li> ?NNN
    2992** <li> :VVV
    2993** <li> @VVV
    2994** <li> $VVV
    2995** </ul>
    2996**
    2997** In the templates above, NNN represents an integer literal,
    2566** and VVV represents an alphanumeric identifer.)^ ^The values of these
    		2998** and VVV represents an alphanumeric identifier.)^ ^The values of these
    2567** parameters (also called "host parameter names" or "SQL parameters")
    2568** can be set using the sqlite3_bind_*() routines defined here.
    2569**
    2570** ^The first argument to the sqlite3_bind_*() routines is always
    2571** a pointer to the [sqlite3_stmt] object returned from
    2572** [sqlite3_prepare_v2()] or its variants.
    2573**
    2574** ^The second argument is the index of the SQL parameter to be set.

    --- 11 unchanged lines hidden (view full) ---

    2586** ^(In those routines that have a fourth argument, its value is the
    2587** number of bytes in the parameter. To be clear: the value is the
    2588** number of <u>bytes</u> in the value, not the number of characters.)^
    2589** ^If the fourth parameter is negative, the length of the string is
    2590** the number of bytes up to the first zero terminator.
    2591**
    2592** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
    2593** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
    		2999** parameters (also called "host parameter names" or "SQL parameters")
    3000** can be set using the sqlite3_bind_*() routines defined here.
    3001**
    3002** ^The first argument to the sqlite3_bind_*() routines is always
    3003** a pointer to the [sqlite3_stmt] object returned from
    3004** [sqlite3_prepare_v2()] or its variants.
    3005**
    3006** ^The second argument is the index of the SQL parameter to be set.

    --- 11 unchanged lines hidden (view full) ---

    3018** ^(In those routines that have a fourth argument, its value is the
    3019** number of bytes in the parameter. To be clear: the value is the
    3020** number of <u>bytes</u> in the value, not the number of characters.)^
    3021** ^If the fourth parameter is negative, the length of the string is
    3022** the number of bytes up to the first zero terminator.
    3023**
    3024** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
    3025** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
    2594** string after SQLite has finished with it. ^If the fifth argument is
    		3026** string after SQLite has finished with it. ^The destructor is called
    3027** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
    3028** sqlite3_bind_text(), or sqlite3_bind_text16() fails.
    3029** ^If the fifth argument is
    2595** the special value [SQLITE_STATIC], then SQLite assumes that the
    2596** information is in static, unmanaged space and does not need to be freed.
    2597** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
    2598** SQLite makes its own private copy of the data immediately, before
    2599** the sqlite3_bind_*() routine returns.
    2600**
    2601** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
    2602** is filled with zeroes. ^A zeroblob uses a fixed amount of memory

    --- 104 unchanged lines hidden (view full) ---

    2707SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
    2708
    2709/*
    2710** CAPI3REF: Number Of Columns In A Result Set
    2711**
    2712** ^Return the number of columns in the result set returned by the
    2713** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
    2714** statement that does not return data (for example an [UPDATE]).
    		3030** the special value [SQLITE_STATIC], then SQLite assumes that the
    3031** information is in static, unmanaged space and does not need to be freed.
    3032** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
    3033** SQLite makes its own private copy of the data immediately, before
    3034** the sqlite3_bind_*() routine returns.
    3035**
    3036** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
    3037** is filled with zeroes. ^A zeroblob uses a fixed amount of memory

    --- 104 unchanged lines hidden (view full) ---

    3142SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
    3143
    3144/*
    3145** CAPI3REF: Number Of Columns In A Result Set
    3146**
    3147** ^Return the number of columns in the result set returned by the
    3148** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
    3149** statement that does not return data (for example an [UPDATE]).
    3150**
    3151** See also: [sqlite3_data_count()]
    2715*/
    2716SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
    2717
    2718/*
    2719** CAPI3REF: Column Names In A Result Set
    2720**
    2721** ^These routines return the name assigned to a particular column
    2722** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
    2723** interface returns a pointer to a zero-terminated UTF-8 string
    2724** and sqlite3_column_name16() returns a pointer to a zero-terminated
    2725** UTF-16 string. ^The first parameter is the [prepared statement]
    2726** that implements the [SELECT] statement. ^The second parameter is the
    2727** column number. ^The leftmost column is number 0.
    2728**
    2729** ^The returned string pointer is valid until either the [prepared statement]
    		3152*/
    3153SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
    3154
    3155/*
    3156** CAPI3REF: Column Names In A Result Set
    3157**
    3158** ^These routines return the name assigned to a particular column
    3159** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
    3160** interface returns a pointer to a zero-terminated UTF-8 string
    3161** and sqlite3_column_name16() returns a pointer to a zero-terminated
    3162** UTF-16 string. ^The first parameter is the [prepared statement]
    3163** that implements the [SELECT] statement. ^The second parameter is the
    3164** column number. ^The leftmost column is number 0.
    3165**
    3166** ^The returned string pointer is valid until either the [prepared statement]
    2730** is destroyed by [sqlite3_finalize()] or until the next call to
    		3167** is destroyed by [sqlite3_finalize()] or until the statement is automatically
    3168** reprepared by the first call to [sqlite3_step()] for a particular run
    3169** or until the next call to
    2731** sqlite3_column_name() or sqlite3_column_name16() on the same column.
    2732**
    2733** ^If sqlite3_malloc() fails during the processing of either routine
    2734** (for example during a conversion from UTF-8 to UTF-16) then a
    2735** NULL pointer is returned.
    2736**
    2737** ^The name of a result column is the value of the "AS" clause for
    2738** that column, if there is an AS clause. If there is no AS clause

    --- 9 unchanged lines hidden (view full) ---

    2748** ^These routines provide a means to determine the database, table, and
    2749** table column that is the origin of a particular result column in
    2750** [SELECT] statement.
    2751** ^The name of the database or table or column can be returned as
    2752** either a UTF-8 or UTF-16 string. ^The _database_ routines return
    2753** the database name, the _table_ routines return the table name, and
    2754** the origin_ routines return the column name.
    2755** ^The returned string is valid until the [prepared statement] is destroyed
    		3170** sqlite3_column_name() or sqlite3_column_name16() on the same column.
    3171**
    3172** ^If sqlite3_malloc() fails during the processing of either routine
    3173** (for example during a conversion from UTF-8 to UTF-16) then a
    3174** NULL pointer is returned.
    3175**
    3176** ^The name of a result column is the value of the "AS" clause for
    3177** that column, if there is an AS clause. If there is no AS clause

    --- 9 unchanged lines hidden (view full) ---

    3187** ^These routines provide a means to determine the database, table, and
    3188** table column that is the origin of a particular result column in
    3189** [SELECT] statement.
    3190** ^The name of the database or table or column can be returned as
    3191** either a UTF-8 or UTF-16 string. ^The _database_ routines return
    3192** the database name, the _table_ routines return the table name, and
    3193** the origin_ routines return the column name.
    3194** ^The returned string is valid until the [prepared statement] is destroyed
    2756** using [sqlite3_finalize()] or until the same information is requested
    		3195** using [sqlite3_finalize()] or until the statement is automatically
    3196** reprepared by the first call to [sqlite3_step()] for a particular run
    3197** or until the same information is requested
    2757** again in a different encoding.
    2758**
    2759** ^The names returned are the original un-aliased names of the
    2760** database, table, and column.
    2761**
    2762** ^The first argument to these interfaces is a [prepared statement].
    2763** ^These functions return information about the Nth result column returned by
    2764** the statement, where N is the second function argument.

    --- 77 unchanged lines hidden (view full) ---

    2842** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
    2843** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
    2844** ^With the "v2" interface, any of the other [result codes] or
    2845** [extended result codes] might be returned as well.
    2846**
    2847** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
    2848** database locks it needs to do its job. ^If the statement is a [COMMIT]
    2849** or occurs outside of an explicit transaction, then you can retry the
    		3198** again in a different encoding.
    3199**
    3200** ^The names returned are the original un-aliased names of the
    3201** database, table, and column.
    3202**
    3203** ^The first argument to these interfaces is a [prepared statement].
    3204** ^These functions return information about the Nth result column returned by
    3205** the statement, where N is the second function argument.

    --- 77 unchanged lines hidden (view full) ---

    3283** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
    3284** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
    3285** ^With the "v2" interface, any of the other [result codes] or
    3286** [extended result codes] might be returned as well.
    3287**
    3288** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
    3289** database locks it needs to do its job. ^If the statement is a [COMMIT]
    3290** or occurs outside of an explicit transaction, then you can retry the
    2850** statement. If the statement is not a [COMMIT] and occurs within a
    		3291** statement. If the statement is not a [COMMIT] and occurs within an
    2851** explicit transaction then you should rollback the transaction before
    2852** continuing.
    2853**
    2854** ^[SQLITE_DONE] means that the statement has finished executing
    2855** successfully. sqlite3_step() should not be called again on this virtual
    2856** machine without first calling [sqlite3_reset()] to reset the virtual
    2857** machine back to its initial state.
    2858**

    --- 13 unchanged lines hidden (view full) ---

    2872**
    2873** [SQLITE_MISUSE] means that the this routine was called inappropriately.
    2874** Perhaps it was called on a [prepared statement] that has
    2875** already been [sqlite3_finalize | finalized] or on one that had
    2876** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
    2877** be the case that the same database connection is being used by two or
    2878** more threads at the same moment in time.
    2879**
    		3292** explicit transaction then you should rollback the transaction before
    3293** continuing.
    3294**
    3295** ^[SQLITE_DONE] means that the statement has finished executing
    3296** successfully. sqlite3_step() should not be called again on this virtual
    3297** machine without first calling [sqlite3_reset()] to reset the virtual
    3298** machine back to its initial state.
    3299**

    --- 13 unchanged lines hidden (view full) ---

    3313**
    3314** [SQLITE_MISUSE] means that the this routine was called inappropriately.
    3315** Perhaps it was called on a [prepared statement] that has
    3316** already been [sqlite3_finalize | finalized] or on one that had
    3317** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
    3318** be the case that the same database connection is being used by two or
    3319** more threads at the same moment in time.
    3320**
    3321** For all versions of SQLite up to and including 3.6.23.1, a call to
    3322** [sqlite3_reset()] was required after sqlite3_step() returned anything
    3323** other than [SQLITE_ROW] before any subsequent invocation of
    3324** sqlite3_step(). Failure to reset the prepared statement using
    3325** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
    3326** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began
    3327** calling [sqlite3_reset()] automatically in this circumstance rather
    3328** than returning [SQLITE_MISUSE]. This is not considered a compatibility
    3329** break because any application that ever receives an SQLITE_MISUSE error
    3330** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
    3331** can be used to restore the legacy behavior.
    3332**
    2880** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
    2881** API always returns a generic error code, [SQLITE_ERROR], following any
    2882** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
    2883** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
    2884** specific [error codes] that better describes the error.
    2885** We admit that this is a goofy design. The problem has been fixed
    2886** with the "v2" interface. If you prepare all of your SQL statements
    2887** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
    2888** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
    2889** then the more specific [error codes] are returned directly
    2890** by sqlite3_step(). The use of the "v2" interface is recommended.
    2891*/
    2892SQLITE_API int sqlite3_step(sqlite3_stmt*);
    2893
    2894/*
    2895** CAPI3REF: Number of columns in a result set
    2896**
    		3333** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
    3334** API always returns a generic error code, [SQLITE_ERROR], following any
    3335** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
    3336** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
    3337** specific [error codes] that better describes the error.
    3338** We admit that this is a goofy design. The problem has been fixed
    3339** with the "v2" interface. If you prepare all of your SQL statements
    3340** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
    3341** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
    3342** then the more specific [error codes] are returned directly
    3343** by sqlite3_step(). The use of the "v2" interface is recommended.
    3344*/
    3345SQLITE_API int sqlite3_step(sqlite3_stmt*);
    3346
    3347/*
    3348** CAPI3REF: Number of columns in a result set
    3349**
    2897** ^The sqlite3_data_count(P) the number of columns in the
    2898** of the result set of [prepared statement] P.
    		3350** ^The sqlite3_data_count(P) interface returns the number of columns in the
    3351** current row of the result set of [prepared statement] P.
    3352** ^If prepared statement P does not have results ready to return
    3353** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
    3354** interfaces) then sqlite3_data_count(P) returns 0.
    3355** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
    3356**
    3357** See also: [sqlite3_column_count()]
    2899*/
    2900SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
    2901
    2902/*
    2903** CAPI3REF: Fundamental Datatypes
    2904** KEYWORDS: SQLITE_TEXT
    2905**
    2906** ^(Every value in SQLite has one of five fundamental datatypes:

    --- 63 unchanged lines hidden (view full) ---

    2970**
    2971** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
    2972** routine returns the number of bytes in that BLOB or string.
    2973** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
    2974** the string to UTF-8 and then returns the number of bytes.
    2975** ^If the result is a numeric value then sqlite3_column_bytes() uses
    2976** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
    2977** the number of bytes in that string.
    		3358*/
    3359SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
    3360
    3361/*
    3362** CAPI3REF: Fundamental Datatypes
    3363** KEYWORDS: SQLITE_TEXT
    3364**
    3365** ^(Every value in SQLite has one of five fundamental datatypes:

    --- 63 unchanged lines hidden (view full) ---

    3429**
    3430** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
    3431** routine returns the number of bytes in that BLOB or string.
    3432** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
    3433** the string to UTF-8 and then returns the number of bytes.
    3434** ^If the result is a numeric value then sqlite3_column_bytes() uses
    3435** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
    3436** the number of bytes in that string.
    2978** ^The value returned does not include the zero terminator at the end
    2979** of the string. ^For clarity: the value returned is the number of
    		3437** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
    3438**
    3439** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
    3440** routine returns the number of bytes in that BLOB or string.
    3441** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
    3442** the string to UTF-16 and then returns the number of bytes.
    3443** ^If the result is a numeric value then sqlite3_column_bytes16() uses
    3444** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
    3445** the number of bytes in that string.
    3446** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
    3447**
    3448** ^The values returned by [sqlite3_column_bytes()] and
    3449** [sqlite3_column_bytes16()] do not include the zero terminators at the end
    3450** of the string. ^For clarity: the values returned by
    3451** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
    2980** bytes in the string, not the number of characters.
    2981**
    2982** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
    2983** even empty strings, are always zero terminated. ^The return
    		3452** bytes in the string, not the number of characters.
    3453**
    3454** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
    3455** even empty strings, are always zero terminated. ^The return
    2984** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
    2985** pointer, possibly even a NULL pointer.
    		3456** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
    2986**
    		3457**
    2987** ^The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
    2988** but leaves the result in UTF-16 in native byte order instead of UTF-8.
    2989** ^The zero terminator is not included in this count.
    2990**
    2991** ^The object returned by [sqlite3_column_value()] is an
    2992** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
    2993** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
    2994** If the [unprotected sqlite3_value] object returned by
    2995** [sqlite3_column_value()] is used in any other way, including calls
    2996** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
    2997** or [sqlite3_value_bytes()], then the behavior is undefined.
    2998**

    --- 27 unchanged lines hidden (view full) ---

    3026** </blockquote>)^
    3027**
    3028** The table above makes reference to standard C library functions atoi()
    3029** and atof(). SQLite does not really use these functions. It has its
    3030** own equivalent internal routines. The atoi() and atof() names are
    3031** used in the table for brevity and because they are familiar to most
    3032** C programmers.
    3033**
    		3458** ^The object returned by [sqlite3_column_value()] is an
    3459** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
    3460** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
    3461** If the [unprotected sqlite3_value] object returned by
    3462** [sqlite3_column_value()] is used in any other way, including calls
    3463** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
    3464** or [sqlite3_value_bytes()], then the behavior is undefined.
    3465**

    --- 27 unchanged lines hidden (view full) ---

    3493** </blockquote>)^
    3494**
    3495** The table above makes reference to standard C library functions atoi()
    3496** and atof(). SQLite does not really use these functions. It has its
    3497** own equivalent internal routines. The atoi() and atof() names are
    3498** used in the table for brevity and because they are familiar to most
    3499** C programmers.
    3500**
    3034** ^Note that when type conversions occur, pointers returned by prior
    		3501** Note that when type conversions occur, pointers returned by prior
    3035** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
    3036** sqlite3_column_text16() may be invalidated.
    		3502** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
    3503** sqlite3_column_text16() may be invalidated.
    3037** ^(Type conversions and pointer invalidations might occur
    		3504** Type conversions and pointer invalidations might occur
    3038** in the following cases:
    3039**
    3040** <ul>
    3041** <li> The initial content is a BLOB and sqlite3_column_text() or
    3042** sqlite3_column_text16() is called. A zero-terminator might
    3043** need to be added to the string.</li>
    3044** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
    3045** sqlite3_column_text16() is called. The content must be converted
    3046** to UTF-16.</li>
    3047** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
    3048** sqlite3_column_text() is called. The content must be converted
    3049** to UTF-8.</li>
    		3505** in the following cases:
    3506**
    3507** <ul>
    3508** <li> The initial content is a BLOB and sqlite3_column_text() or
    3509** sqlite3_column_text16() is called. A zero-terminator might
    3510** need to be added to the string.</li>
    3511** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
    3512** sqlite3_column_text16() is called. The content must be converted
    3513** to UTF-16.</li>
    3514** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
    3515** sqlite3_column_text() is called. The content must be converted
    3516** to UTF-8.</li>
    3050** </ul>)^
    		3517**
    3051**
    3052** ^Conversions between UTF-16be and UTF-16le are always done in place and do
    3053** not invalidate a prior pointer, though of course the content of the buffer
    		3518**
    3519** ^Conversions between UTF-16be and UTF-16le are always done in place and do
    3520** not invalidate a prior pointer, though of course the content of the buffer
    3054** that the prior pointer points to will have been modified. Other kinds
    		3521** that the prior pointer references will have been modified. Other kinds
    3055** of conversion are done in place when it is possible, but sometimes they
    3056** are not possible and in those cases prior pointers are invalidated.
    3057**
    		3522** of conversion are done in place when it is possible, but sometimes they
    3523** are not possible and in those cases prior pointers are invalidated.
    3524**
    3058** ^(The safest and easiest to remember policy is to invoke these routines
    		3525** The safest and easiest to remember policy is to invoke these routines
    3059** in one of the following ways:
    3060**
    3061** <ul>
    3062** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
    3063** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
    3064** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
    		3526** in one of the following ways:
    3527**
    3528** <ul>
    3529** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
    3530** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
    3531** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
    3065** </ul>)^
    		3532**
    3066**
    3067** In other words, you should call sqlite3_column_text(),
    3068** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
    3069** into the desired format, then invoke sqlite3_column_bytes() or
    3070** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
    3071** to sqlite3_column_text() or sqlite3_column_blob() with calls to
    3072** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
    3073** with calls to sqlite3_column_bytes().

    --- 21 unchanged lines hidden (view full) ---

    3095SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
    3096SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
    3097SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
    3098
    3099/*
    3100** CAPI3REF: Destroy A Prepared Statement Object
    3101**
    3102** ^The sqlite3_finalize() function is called to delete a [prepared statement].
    		3533**
    3534** In other words, you should call sqlite3_column_text(),
    3535** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
    3536** into the desired format, then invoke sqlite3_column_bytes() or
    3537** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
    3538** to sqlite3_column_text() or sqlite3_column_blob() with calls to
    3539** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
    3540** with calls to sqlite3_column_bytes().

    --- 21 unchanged lines hidden (view full) ---

    3562SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
    3563SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
    3564SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
    3565
    3566/*
    3567** CAPI3REF: Destroy A Prepared Statement Object
    3568**
    3569** ^The sqlite3_finalize() function is called to delete a [prepared statement].
    3103** ^If the statement was executed successfully or not executed at all, then
    3104** SQLITE_OK is returned. ^If execution of the statement failed then an
    3105** [error code] or [extended error code] is returned.
    		3570** ^If the most recent evaluation of the statement encountered no errors
    3571** or if the statement is never been evaluated, then sqlite3_finalize() returns
    3572** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
    3573** sqlite3_finalize(S) returns the appropriate [error code] or
    3574** [extended error code].
    3106**
    		3575**
    3107** ^This routine can be called at any point during the execution of the
    3108** [prepared statement]. ^If the virtual machine has not
    3109** completed execution when this routine is called, that is like
    3110** encountering an error or an [sqlite3_interrupt | interrupt].
    3111** ^Incomplete updates may be rolled back and transactions canceled,
    3112** depending on the circumstances, and the
    3113** [error code] returned will be [SQLITE_ABORT].
    		3576** ^The sqlite3_finalize(S) routine can be called at any point during
    3577** the life cycle of [prepared statement] S:
    3578** before statement S is ever evaluated, after
    3579** one or more calls to [sqlite3_reset()], or after any call
    3580** to [sqlite3_step()] regardless of whether or not the statement has
    3581** completed execution.
    3582**
    3583** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
    3584**
    3585** The application must finalize every [prepared statement] in order to avoid
    3586** resource leaks. It is a grievous error for the application to try to use
    3587** a prepared statement after it has been finalized. Any use of a prepared
    3588** statement after it has been finalized can result in undefined and
    3589** undesirable behavior such as segfaults and heap corruption.
    3114*/
    3115SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
    3116
    3117/*
    3118** CAPI3REF: Reset A Prepared Statement Object
    3119**
    3120** The sqlite3_reset() function is called to reset a [prepared statement]
    3121** object back to its initial state, ready to be re-executed.

    --- 19 unchanged lines hidden (view full) ---

    3141SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
    3142
    3143/*
    3144** CAPI3REF: Create Or Redefine SQL Functions
    3145** KEYWORDS: {function creation routines}
    3146** KEYWORDS: {application-defined SQL function}
    3147** KEYWORDS: {application-defined SQL functions}
    3148**
    		3590*/
    3591SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
    3592
    3593/*
    3594** CAPI3REF: Reset A Prepared Statement Object
    3595**
    3596** The sqlite3_reset() function is called to reset a [prepared statement]
    3597** object back to its initial state, ready to be re-executed.

    --- 19 unchanged lines hidden (view full) ---

    3617SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
    3618
    3619/*
    3620** CAPI3REF: Create Or Redefine SQL Functions
    3621** KEYWORDS: {function creation routines}
    3622** KEYWORDS: {application-defined SQL function}
    3623** KEYWORDS: {application-defined SQL functions}
    3624**
    3149** ^These two functions (collectively known as "function creation routines")
    		3625** ^These functions (collectively known as "function creation routines")
    3150** are used to add SQL functions or aggregates or to redefine the behavior
    		3626** are used to add SQL functions or aggregates or to redefine the behavior
    3151** of existing SQL functions or aggregates. The only difference between the
    3152** two is that the second parameter, the name of the (scalar) function or
    3153** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
    3154** for sqlite3_create_function16().
    		3627** of existing SQL functions or aggregates. The only differences between
    3628** these routines are the text encoding expected for
    3629** the second parameter (the name of the function being created)
    3630** and the presence or absence of a destructor callback for
    3631** the application data pointer.
    3155**
    3156** ^The first parameter is the [database connection] to which the SQL
    3157** function is to be added. ^If an application uses more than one database
    3158** connection then application-defined SQL functions must be added
    3159** to each database connection separately.
    3160**
    		3632**
    3633** ^The first parameter is the [database connection] to which the SQL
    3634** function is to be added. ^If an application uses more than one database
    3635** connection then application-defined SQL functions must be added
    3636** to each database connection separately.
    3637**
    3161** The second parameter is the name of the SQL function to be created or
    3162** redefined. ^The length of the name is limited to 255 bytes, exclusive of
    3163** the zero-terminator. Note that the name length limit is in bytes, not
    3164** characters. ^Any attempt to create a function with a longer name
    3165** will result in [SQLITE_ERROR] being returned.
    		3638** ^The second parameter is the name of the SQL function to be created or
    3639** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
    3640** representation, exclusive of the zero-terminator. ^Note that the name
    3641** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
    3642** ^Any attempt to create a function with a longer name
    3643** will result in [SQLITE_MISUSE] being returned.
    3166**
    3167** ^The third parameter (nArg)
    3168** is the number of arguments that the SQL function or
    3169** aggregate takes. ^If this parameter is -1, then the SQL function or
    3170** aggregate may take any number of arguments between 0 and the limit
    3171** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
    3172** parameter is less than -1 or greater than 127 then the behavior is
    3173** undefined.
    3174**
    		3644**
    3645** ^The third parameter (nArg)
    3646** is the number of arguments that the SQL function or
    3647** aggregate takes. ^If this parameter is -1, then the SQL function or
    3648** aggregate may take any number of arguments between 0 and the limit
    3649** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
    3650** parameter is less than -1 or greater than 127 then the behavior is
    3651** undefined.
    3652**
    3175** The fourth parameter, eTextRep, specifies what
    		3653** ^The fourth parameter, eTextRep, specifies what
    3176** [SQLITE_UTF8 | text encoding] this SQL function prefers for
    		3654** [SQLITE_UTF8 | text encoding] this SQL function prefers for
    3177** its parameters. Any SQL function implementation should be able to work
    3178** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
    		3655** its parameters. Every SQL function implementation must be able to work
    3656** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
    3179** more efficient with one encoding than another. ^An application may
    3180** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
    3181** times with the same function but with different values of eTextRep.
    3182** ^When multiple implementations of the same function are available, SQLite
    3183** will pick the one that involves the least amount of data conversion.
    3184** If there is only a single implementation which does not care what text
    3185** encoding is used, then the fourth argument should be [SQLITE_ANY].
    3186**
    3187** ^(The fifth parameter is an arbitrary pointer. The implementation of the
    3188** function can gain access to this pointer using [sqlite3_user_data()].)^
    3189**
    		3657** more efficient with one encoding than another. ^An application may
    3658** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
    3659** times with the same function but with different values of eTextRep.
    3660** ^When multiple implementations of the same function are available, SQLite
    3661** will pick the one that involves the least amount of data conversion.
    3662** If there is only a single implementation which does not care what text
    3663** encoding is used, then the fourth argument should be [SQLITE_ANY].
    3664**
    3665** ^(The fifth parameter is an arbitrary pointer. The implementation of the
    3666** function can gain access to this pointer using [sqlite3_user_data()].)^
    3667**
    3190** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
    		3668** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
    3191** pointers to C-language functions that implement the SQL function or
    3192** aggregate. ^A scalar SQL function requires an implementation of the xFunc
    		3669** pointers to C-language functions that implement the SQL function or
    3670** aggregate. ^A scalar SQL function requires an implementation of the xFunc
    3193** callback only; NULL pointers should be passed as the xStep and xFinal
    		3671** callback only; NULL pointers must be passed as the xStep and xFinal
    3194** parameters. ^An aggregate SQL function requires an implementation of xStep
    		3672** parameters. ^An aggregate SQL function requires an implementation of xStep
    3195** and xFinal and NULL should be passed for xFunc. ^To delete an existing
    3196** SQL function or aggregate, pass NULL for all three function callbacks.
    		3673** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
    3674** SQL function or aggregate, pass NULL pointers for all three function
    3675** callbacks.
    3197**
    		3676**
    3677** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
    3678** then it is destructor for the application data pointer.
    3679** The destructor is invoked when the function is deleted, either by being
    3680** overloaded or when the database connection closes.)^
    3681** ^The destructor is also invoked if the call to
    3682** sqlite3_create_function_v2() fails.
    3683** ^When the destructor callback of the tenth parameter is invoked, it
    3684** is passed a single argument which is a copy of the application data
    3685** pointer which was the fifth parameter to sqlite3_create_function_v2().
    3686**
    3198** ^It is permitted to register multiple implementations of the same
    3199** functions with the same name but with either differing numbers of
    3200** arguments or differing preferred text encodings. ^SQLite will use
    3201** the implementation that most closely matches the way in which the
    3202** SQL function is used. ^A function implementation with a non-negative
    3203** nArg parameter is a better match than a function implementation with
    3204** a negative nArg. ^A function where the preferred text encoding
    3205** matches the database encoding is a better
    		3687** ^It is permitted to register multiple implementations of the same
    3688** functions with the same name but with either differing numbers of
    3689** arguments or differing preferred text encodings. ^SQLite will use
    3690** the implementation that most closely matches the way in which the
    3691** SQL function is used. ^A function implementation with a non-negative
    3692** nArg parameter is a better match than a function implementation with
    3693** a negative nArg. ^A function where the preferred text encoding
    3694** matches the database encoding is a better
    3206** match than a function where the encoding is different.
    		3695** match than a function where the encoding is different.
    3207** ^A function where the encoding difference is between UTF16le and UTF16be
    3208** is a closer match than a function where the encoding difference is
    3209** between UTF8 and UTF16.
    3210**
    3211** ^Built-in functions may be overloaded by new application-defined functions.
    		3696** ^A function where the encoding difference is between UTF16le and UTF16be
    3697** is a closer match than a function where the encoding difference is
    3698** between UTF8 and UTF16.
    3699**
    3700** ^Built-in functions may be overloaded by new application-defined functions.
    3212** ^The first application-defined function with a given name overrides all
    3213** built-in functions in the same [database connection] with the same name.
    3214** ^Subsequent application-defined functions of the same name only override
    3215** prior application-defined functions that are an exact match for the
    3216** number of parameters and preferred encoding.
    3217**
    3218** ^An application-defined function is permitted to call other
    3219** SQLite interfaces. However, such calls must not
    3220** close the database connection nor finalize or reset the prepared
    3221** statement in which the function is running.
    3222*/
    3223SQLITE_API int sqlite3_create_function(
    3224 sqlite3 *db,

    --- 10 unchanged lines hidden (view full) ---

    3235 const void *zFunctionName,
    3236 int nArg,
    3237 int eTextRep,
    3238 void *pApp,
    3239 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
    3240 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
    3241 void (*xFinal)(sqlite3_context*)
    3242);
    		3701**
    3702** ^An application-defined function is permitted to call other
    3703** SQLite interfaces. However, such calls must not
    3704** close the database connection nor finalize or reset the prepared
    3705** statement in which the function is running.
    3706*/
    3707SQLITE_API int sqlite3_create_function(
    3708 sqlite3 *db,

    --- 10 unchanged lines hidden (view full) ---

    3719 const void *zFunctionName,
    3720 int nArg,
    3721 int eTextRep,
    3722 void *pApp,
    3723 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
    3724 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
    3725 void (*xFinal)(sqlite3_context*)
    3726);
    3727SQLITE_API int sqlite3_create_function_v2(
    3728 sqlite3 *db,
    3729 const char *zFunctionName,
    3730 int nArg,
    3731 int eTextRep,
    3732 void *pApp,
    3733 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
    3734 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
    3735 void (*xFinal)(sqlite3_context*),
    3736 void(*xDestroy)(void*)
    3737);
    3243
    3244/*
    3245** CAPI3REF: Text Encodings
    3246**
    3247** These constant define integer codes that represent the various
    3248** text encodings supported by SQLite.
    3249*/
    3250#define SQLITE_UTF8 1
    3251#define SQLITE_UTF16LE 2
    3252#define SQLITE_UTF16BE 3
    3253#define SQLITE_UTF16 4 /* Use native byte order */
    3254#define SQLITE_ANY 5 /* sqlite3_create_function only */
    3255#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
    3256
    3257/*
    3258** CAPI3REF: Deprecated Functions
    3259** DEPRECATED
    3260**
    3261** These functions are [deprecated]. In order to maintain
    		3738
    3739/*
    3740** CAPI3REF: Text Encodings
    3741**
    3742** These constant define integer codes that represent the various
    3743** text encodings supported by SQLite.
    3744*/
    3745#define SQLITE_UTF8 1
    3746#define SQLITE_UTF16LE 2
    3747#define SQLITE_UTF16BE 3
    3748#define SQLITE_UTF16 4 /* Use native byte order */
    3749#define SQLITE_ANY 5 /* sqlite3_create_function only */
    3750#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
    3751
    3752/*
    3753** CAPI3REF: Deprecated Functions
    3754** DEPRECATED
    3755**
    3756** These functions are [deprecated]. In order to maintain
    3262** backwards compatibility with older code, these functions continue
    		3757** backwards compatibility with older code, these functions continue
    3263** to be supported. However, new applications should avoid
    3264** the use of these functions. To help encourage people to avoid
    3265** using these functions, we are not going to tell you what they do.
    3266*/
    3267#ifndef SQLITE_OMIT_DEPRECATED
    3268SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
    3269SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
    3270SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);

    --- 7 unchanged lines hidden (view full) ---

    3278**
    3279** The C-language implementation of SQL functions and aggregates uses
    3280** this set of interface routines to access the parameter values on
    3281** the function or aggregate.
    3282**
    3283** The xFunc (for scalar functions) or xStep (for aggregates) parameters
    3284** to [sqlite3_create_function()] and [sqlite3_create_function16()]
    3285** define callbacks that implement the SQL functions and aggregates.
    		3758** to be supported. However, new applications should avoid
    3759** the use of these functions. To help encourage people to avoid
    3760** using these functions, we are not going to tell you what they do.
    3761*/
    3762#ifndef SQLITE_OMIT_DEPRECATED
    3763SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
    3764SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
    3765SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);

    --- 7 unchanged lines hidden (view full) ---

    3773**
    3774** The C-language implementation of SQL functions and aggregates uses
    3775** this set of interface routines to access the parameter values on
    3776** the function or aggregate.
    3777**
    3778** The xFunc (for scalar functions) or xStep (for aggregates) parameters
    3779** to [sqlite3_create_function()] and [sqlite3_create_function16()]
    3780** define callbacks that implement the SQL functions and aggregates.
    3286** The 4th parameter to these callbacks is an array of pointers to
    		3781** The 3rd parameter to these callbacks is an array of pointers to
    3287** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
    3288** each parameter to the SQL function. These routines are used to
    3289** extract values from the [sqlite3_value] objects.
    3290**
    3291** These routines work only with [protected sqlite3_value] objects.
    3292** Any attempt to use these routines on an [unprotected sqlite3_value]
    3293** object results in undefined behavior.
    3294**

    --- 34 unchanged lines hidden (view full) ---

    3329SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
    3330SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
    3331SQLITE_API int sqlite3_value_type(sqlite3_value*);
    3332SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
    3333
    3334/*
    3335** CAPI3REF: Obtain Aggregate Function Context
    3336**
    		3782** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
    3783** each parameter to the SQL function. These routines are used to
    3784** extract values from the [sqlite3_value] objects.
    3785**
    3786** These routines work only with [protected sqlite3_value] objects.
    3787** Any attempt to use these routines on an [unprotected sqlite3_value]
    3788** object results in undefined behavior.
    3789**

    --- 34 unchanged lines hidden (view full) ---

    3824SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
    3825SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
    3826SQLITE_API int sqlite3_value_type(sqlite3_value*);
    3827SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
    3828
    3829/*
    3830** CAPI3REF: Obtain Aggregate Function Context
    3831**
    3337** Implementions of aggregate SQL functions use this
    		3832** Implementations of aggregate SQL functions use this
    3338** routine to allocate memory for storing their state.
    3339**
    		3833** routine to allocate memory for storing their state.
    3834**
    3340** ^The first time the sqlite3_aggregate_context(C,N) routine is called
    		3835** ^The first time the sqlite3_aggregate_context(C,N) routine is called
    3341** for a particular aggregate function, SQLite
    3342** allocates N of memory, zeroes out that memory, and returns a pointer
    3343** to the new memory. ^On second and subsequent calls to
    3344** sqlite3_aggregate_context() for the same aggregate function instance,
    3345** the same buffer is returned. Sqlite3_aggregate_context() is normally
    3346** called once for each invocation of the xStep callback and then one
    3347** last time when the xFinal callback is invoked. ^(When no rows match
    3348** an aggregate query, the xStep() callback of the aggregate function

    --- 5 unchanged lines hidden (view full) ---

    3354** less than or equal to zero or if a memory allocate error occurs.
    3355**
    3356** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
    3357** determined by the N parameter on first successful call. Changing the
    3358** value of N in subsequent call to sqlite3_aggregate_context() within
    3359** the same aggregate function instance will not resize the memory
    3360** allocation.)^
    3361**
    		3836** for a particular aggregate function, SQLite
    3837** allocates N of memory, zeroes out that memory, and returns a pointer
    3838** to the new memory. ^On second and subsequent calls to
    3839** sqlite3_aggregate_context() for the same aggregate function instance,
    3840** the same buffer is returned. Sqlite3_aggregate_context() is normally
    3841** called once for each invocation of the xStep callback and then one
    3842** last time when the xFinal callback is invoked. ^(When no rows match
    3843** an aggregate query, the xStep() callback of the aggregate function

    --- 5 unchanged lines hidden (view full) ---

    3849** less than or equal to zero or if a memory allocate error occurs.
    3850**
    3851** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
    3852** determined by the N parameter on first successful call. Changing the
    3853** value of N in subsequent call to sqlite3_aggregate_context() within
    3854** the same aggregate function instance will not resize the memory
    3855** allocation.)^
    3856**
    3362** ^SQLite automatically frees the memory allocated by
    		3857** ^SQLite automatically frees the memory allocated by
    3363** sqlite3_aggregate_context() when the aggregate query concludes.
    3364**
    3365** The first parameter must be a copy of the
    3366** [sqlite3_context | SQL function context] that is the first parameter
    3367** to the xStep or xFinal callback routine that implements the aggregate
    3368** function.
    3369**
    3370** This routine must be called from the same thread in which

    --- 210 unchanged lines hidden (view full) ---

    3581SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
    3582SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
    3583SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
    3584SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
    3585
    3586/*
    3587** CAPI3REF: Define New Collating Sequences
    3588**
    		3858** sqlite3_aggregate_context() when the aggregate query concludes.
    3859**
    3860** The first parameter must be a copy of the
    3861** [sqlite3_context | SQL function context] that is the first parameter
    3862** to the xStep or xFinal callback routine that implements the aggregate
    3863** function.
    3864**
    3865** This routine must be called from the same thread in which

    --- 210 unchanged lines hidden (view full) ---

    4076SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
    4077SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
    4078SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
    4079SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
    4080
    4081/*
    4082** CAPI3REF: Define New Collating Sequences
    4083**
    3589** These functions are used to add new collation sequences to the
    3590** [database connection] specified as the first argument.
    		4084** ^These functions add, remove, or modify a [collation] associated
    4085** with the [database connection] specified as the first argument.
    3591**
    		4086**
    3592** ^The name of the new collation sequence is specified as a UTF-8 string
    		4087** ^The name of the collation is a UTF-8 string
    3593** for sqlite3_create_collation() and sqlite3_create_collation_v2()
    		4088** for sqlite3_create_collation() and sqlite3_create_collation_v2()
    3594** and a UTF-16 string for sqlite3_create_collation16(). ^In all cases
    3595** the name is passed as the second function argument.
    		4089** and a UTF-16 string in native byte order for sqlite3_create_collation16().
    4090** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
    4091** considered to be the same name.
    3596**
    		4092**
    3597** ^The third argument may be one of the constants [SQLITE_UTF8],
    3598** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied
    3599** routine expects to be passed pointers to strings encoded using UTF-8,
    3600** UTF-16 little-endian, or UTF-16 big-endian, respectively. ^The
    3601** third argument might also be [SQLITE_UTF16] to indicate that the routine
    3602** expects pointers to be UTF-16 strings in the native byte order, or the
    3603** argument can be [SQLITE_UTF16_ALIGNED] if the
    3604** the routine expects pointers to 16-bit word aligned strings
    3605** of UTF-16 in the native byte order.
    		4093** ^(The third argument (eTextRep) must be one of the constants:
    4094** <ul>
    4095** <li> [SQLITE_UTF8],
    4096** <li> [SQLITE_UTF16LE],
    4097** <li> [SQLITE_UTF16BE],
    4098** <li> [SQLITE_UTF16], or
    4099** <li> [SQLITE_UTF16_ALIGNED].
    4100** </ul>)^
    4101** ^The eTextRep argument determines the encoding of strings passed
    4102** to the collating function callback, xCallback.
    4103** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
    4104** force strings to be UTF16 with native byte order.
    4105** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
    4106** on an even byte address.
    3606**
    		4107**
    3607** A pointer to the user supplied routine must be passed as the fifth
    3608** argument. ^If it is NULL, this is the same as deleting the collation
    3609** sequence (so that SQLite cannot call it anymore).
    3610** ^Each time the application supplied function is invoked, it is passed
    3611** as its first parameter a copy of the void* passed as the fourth argument
    3612** to sqlite3_create_collation() or sqlite3_create_collation16().
    		4108** ^The fourth argument, pArg, is an application data pointer that is passed
    4109** through as the first argument to the collating function callback.
    3613**
    		4110**
    3614** ^The remaining arguments to the application-supplied routine are two strings,
    3615** each represented by a (length, data) pair and encoded in the encoding
    3616** that was passed as the third argument when the collation sequence was
    3617** registered. The application defined collation routine should
    3618** return negative, zero or positive if the first string is less than,
    3619** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
    		4111** ^The fifth argument, xCallback, is a pointer to the collating function.
    4112** ^Multiple collating functions can be registered using the same name but
    4113** with different eTextRep parameters and SQLite will use whichever
    4114** function requires the least amount of data transformation.
    4115** ^If the xCallback argument is NULL then the collating function is
    4116** deleted. ^When all collating functions having the same name are deleted,
    4117** that collation is no longer usable.
    3620**
    		4118**
    4119** ^The collating function callback is invoked with a copy of the pArg
    4120** application data pointer and with two strings in the encoding specified
    4121** by the eTextRep argument. The collating function must return an
    4122** integer that is negative, zero, or positive
    4123** if the first string is less than, equal to, or greater than the second,
    4124** respectively. A collating function must always return the same answer
    4125** given the same inputs. If two or more collating functions are registered
    4126** to the same collation name (using different eTextRep values) then all
    4127** must give an equivalent answer when invoked with equivalent strings.
    4128** The collating function must obey the following properties for all
    4129** strings A, B, and C:
    4130**
    4131** <ol>
    4132** <li> If A==B then B==A.
    4133** <li> If A==B and B==C then A==C.
    4134** <li> If A&lt;B THEN B&gt;A.
    4135** <li> If A&lt;B and B&lt;C then A&lt;C.
    4136** </ol>
    4137**
    4138** If a collating function fails any of the above constraints and that
    4139** collating function is registered and used, then the behavior of SQLite
    4140** is undefined.
    4141**
    3621** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
    		4142** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
    3622** except that it takes an extra argument which is a destructor for
    3623** the collation. ^The destructor is called when the collation is
    3624** destroyed and is passed a copy of the fourth parameter void* pointer
    3625** of the sqlite3_create_collation_v2().
    3626** ^Collations are destroyed when they are overridden by later calls to the
    3627** collation creation functions or when the [database connection] is closed
    3628** using [sqlite3_close()].
    		4143** with the addition that the xDestroy callback is invoked on pArg when
    4144** the collating function is deleted.
    4145** ^Collating functions are deleted when they are overridden by later
    4146** calls to the collation creation functions or when the
    4147** [database connection] is closed using [sqlite3_close()].
    3629**
    		4148**
    4149** ^The xDestroy callback is <u>not</u> called if the
    4150** sqlite3_create_collation_v2() function fails. Applications that invoke
    4151** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
    4152** check the return code and dispose of the application data pointer
    4153** themselves rather than expecting SQLite to deal with it for them.
    4154** This is different from every other SQLite interface. The inconsistency
    4155** is unfortunate but cannot be changed without breaking backwards
    4156** compatibility.
    4157**
    3630** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
    3631*/
    3632SQLITE_API int sqlite3_create_collation(
    		4158** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
    4159*/
    4160SQLITE_API int sqlite3_create_collation(
    3633 sqlite3*,
    3634 const char *zName,
    3635 int eTextRep,
    3636 void*,
    		4161 sqlite3*,
    4162 const char *zName,
    4163 int eTextRep,
    4164 void *pArg,
    3637 int(*xCompare)(void*,int,const void*,int,const void*)
    3638);
    3639SQLITE_API int sqlite3_create_collation_v2(
    		4165 int(*xCompare)(void*,int,const void*,int,const void*)
    4166);
    4167SQLITE_API int sqlite3_create_collation_v2(
    3640 sqlite3*,
    3641 const char *zName,
    3642 int eTextRep,
    3643 void*,
    		4168 sqlite3*,
    4169 const char *zName,
    4170 int eTextRep,
    4171 void *pArg,
    3644 int(*xCompare)(void*,int,const void*,int,const void*),
    3645 void(*xDestroy)(void*)
    3646);
    3647SQLITE_API int sqlite3_create_collation16(
    		4172 int(*xCompare)(void*,int,const void*,int,const void*),
    4173 void(*xDestroy)(void*)
    4174);
    4175SQLITE_API int sqlite3_create_collation16(
    3648 sqlite3*,
    		4176 sqlite3*,
    3649 const void *zName,
    		4177 const void *zName,
    3650 int eTextRep,
    3651 void*,
    		4178 int eTextRep,
    4179 void *pArg,
    3652 int(*xCompare)(void*,int,const void*,int,const void*)
    3653);
    3654
    3655/*
    3656** CAPI3REF: Collation Needed Callbacks
    3657**
    3658** ^To avoid having to register all collation sequences before a database
    3659** can be used, a single callback function may be registered with the

    --- 14 unchanged lines hidden (view full) ---

    3674** sequence function required. The fourth parameter is the name of the
    3675** required collation sequence.)^
    3676**
    3677** The callback function should register the desired collation using
    3678** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
    3679** [sqlite3_create_collation_v2()].
    3680*/
    3681SQLITE_API int sqlite3_collation_needed(
    		4180 int(*xCompare)(void*,int,const void*,int,const void*)
    4181);
    4182
    4183/*
    4184** CAPI3REF: Collation Needed Callbacks
    4185**
    4186** ^To avoid having to register all collation sequences before a database
    4187** can be used, a single callback function may be registered with the

    --- 14 unchanged lines hidden (view full) ---

    4202** sequence function required. The fourth parameter is the name of the
    4203** required collation sequence.)^
    4204**
    4205** The callback function should register the desired collation using
    4206** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
    4207** [sqlite3_create_collation_v2()].
    4208*/
    4209SQLITE_API int sqlite3_collation_needed(
    3682 sqlite3*,
    3683 void*,
    		4210 sqlite3*,
    4211 void*,
    3684 void(*)(void*,sqlite3*,int eTextRep,const char*)
    3685);
    3686SQLITE_API int sqlite3_collation_needed16(
    		4212 void(*)(void*,sqlite3*,int eTextRep,const char*)
    4213);
    4214SQLITE_API int sqlite3_collation_needed16(
    3687 sqlite3*,
    		4215 sqlite3*,
    3688 void*,
    3689 void(*)(void*,sqlite3*,int eTextRep,const void*)
    3690);
    3691
    		4216 void*,
    4217 void(*)(void*,sqlite3*,int eTextRep,const void*)
    4218);
    4219
    3692#if SQLITE_HAS_CODEC
    		4220#ifdef SQLITE_HAS_CODEC
    3693/*
    3694** Specify the key for an encrypted database. This routine should be
    3695** called right after sqlite3_open().
    3696**
    3697** The code to implement this API is not available in the public release
    3698** of SQLite.
    3699*/
    3700SQLITE_API int sqlite3_key(

    --- 10 unchanged lines hidden (view full) ---

    3711** of SQLite.
    3712*/
    3713SQLITE_API int sqlite3_rekey(
    3714 sqlite3 *db, /* Database to be rekeyed */
    3715 const void *pKey, int nKey /* The new key */
    3716);
    3717
    3718/*
    		4221/*
    4222** Specify the key for an encrypted database. This routine should be
    4223** called right after sqlite3_open().
    4224**
    4225** The code to implement this API is not available in the public release
    4226** of SQLite.
    4227*/
    4228SQLITE_API int sqlite3_key(

    --- 10 unchanged lines hidden (view full) ---

    4239** of SQLite.
    4240*/
    4241SQLITE_API int sqlite3_rekey(
    4242 sqlite3 *db, /* Database to be rekeyed */
    4243 const void *pKey, int nKey /* The new key */
    4244);
    4245
    4246/*
    3719** Specify the activation key for a SEE database. Unless
    		4247** Specify the activation key for a SEE database. Unless
    3720** activated, none of the SEE routines will work.
    3721*/
    3722SQLITE_API void sqlite3_activate_see(
    3723 const char *zPassPhrase /* Activation phrase */
    3724);
    3725#endif
    3726
    3727#ifdef SQLITE_ENABLE_CEROD
    3728/*
    		4248** activated, none of the SEE routines will work.
    4249*/
    4250SQLITE_API void sqlite3_activate_see(
    4251 const char *zPassPhrase /* Activation phrase */
    4252);
    4253#endif
    4254
    4255#ifdef SQLITE_ENABLE_CEROD
    4256/*
    3729** Specify the activation key for a CEROD database. Unless
    		4257** Specify the activation key for a CEROD database. Unless
    3730** activated, none of the CEROD routines will work.
    3731*/
    3732SQLITE_API void sqlite3_activate_cerod(
    3733 const char *zPassPhrase /* Activation phrase */
    3734);
    3735#endif
    3736
    3737/*
    3738** CAPI3REF: Suspend Execution For A Short Time
    3739**
    		4258** activated, none of the CEROD routines will work.
    4259*/
    4260SQLITE_API void sqlite3_activate_cerod(
    4261 const char *zPassPhrase /* Activation phrase */
    4262);
    4263#endif
    4264
    4265/*
    4266** CAPI3REF: Suspend Execution For A Short Time
    4267**
    3740** ^The sqlite3_sleep() function causes the current thread to suspend execution
    		4268** The sqlite3_sleep() function causes the current thread to suspend execution
    3741** for at least a number of milliseconds specified in its parameter.
    3742**
    		4269** for at least a number of milliseconds specified in its parameter.
    4270**
    3743** ^If the operating system does not support sleep requests with
    		4271** If the operating system does not support sleep requests with
    3744** millisecond time resolution, then the time will be rounded up to
    		4272** millisecond time resolution, then the time will be rounded up to
    3745** the nearest second. ^The number of milliseconds of sleep actually
    		4273** the nearest second. The number of milliseconds of sleep actually
    3746** requested from the operating system is returned.
    3747**
    3748** ^SQLite implements this interface by calling the xSleep()
    		4274** requested from the operating system is returned.
    4275**
    4276** ^SQLite implements this interface by calling the xSleep()
    3749** method of the default [sqlite3_vfs] object.
    		4277** method of the default [sqlite3_vfs] object. If the xSleep() method
    4278** of the default VFS is not implemented correctly, or not implemented at
    4279** all, then the behavior of sqlite3_sleep() may deviate from the description
    4280** in the previous paragraphs.
    3750*/
    3751SQLITE_API int sqlite3_sleep(int);
    3752
    3753/*
    3754** CAPI3REF: Name Of The Folder Holding Temporary Files
    3755**
    3756** ^(If this global variable is made to point to a string which is
    3757** the name of a folder (a.k.a. directory), then all temporary files

    --- 9 unchanged lines hidden (view full) ---

    3767** It is intended that this variable be set once
    3768** as part of process initialization and before any SQLite interface
    3769** routines have been called and that this variable remain unchanged
    3770** thereafter.
    3771**
    3772** ^The [temp_store_directory pragma] may modify this variable and cause
    3773** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
    3774** the [temp_store_directory pragma] always assumes that any string
    		4281*/
    4282SQLITE_API int sqlite3_sleep(int);
    4283
    4284/*
    4285** CAPI3REF: Name Of The Folder Holding Temporary Files
    4286**
    4287** ^(If this global variable is made to point to a string which is
    4288** the name of a folder (a.k.a. directory), then all temporary files

    --- 9 unchanged lines hidden (view full) ---

    4298** It is intended that this variable be set once
    4299** as part of process initialization and before any SQLite interface
    4300** routines have been called and that this variable remain unchanged
    4301** thereafter.
    4302**
    4303** ^The [temp_store_directory pragma] may modify this variable and cause
    4304** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
    4305** the [temp_store_directory pragma] always assumes that any string
    3775** that this variable points to is held in memory obtained from
    		4306** that this variable points to is held in memory obtained from
    3776** [sqlite3_malloc] and the pragma may attempt to free that memory
    3777** using [sqlite3_free].
    3778** Hence, if this variable is modified directly, either it should be
    3779** made NULL or made to point to memory obtained from [sqlite3_malloc]
    3780** or else the use of the [temp_store_directory pragma] should be avoided.
    3781*/
    3782SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
    3783

    --- 83 unchanged lines hidden (view full) ---

    3867** ^The rollback hook is invoked on a rollback that results from a commit
    3868** hook returning non-zero, just as it would be with any other rollback.
    3869**
    3870** ^For the purposes of this API, a transaction is said to have been
    3871** rolled back if an explicit "ROLLBACK" statement is executed, or
    3872** an error or constraint causes an implicit rollback to occur.
    3873** ^The rollback callback is not invoked if a transaction is
    3874** automatically rolled back because the database connection is closed.
    		4307** [sqlite3_malloc] and the pragma may attempt to free that memory
    4308** using [sqlite3_free].
    4309** Hence, if this variable is modified directly, either it should be
    4310** made NULL or made to point to memory obtained from [sqlite3_malloc]
    4311** or else the use of the [temp_store_directory pragma] should be avoided.
    4312*/
    4313SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
    4314

    --- 83 unchanged lines hidden (view full) ---

    4398** ^The rollback hook is invoked on a rollback that results from a commit
    4399** hook returning non-zero, just as it would be with any other rollback.
    4400**
    4401** ^For the purposes of this API, a transaction is said to have been
    4402** rolled back if an explicit "ROLLBACK" statement is executed, or
    4403** an error or constraint causes an implicit rollback to occur.
    4404** ^The rollback callback is not invoked if a transaction is
    4405** automatically rolled back because the database connection is closed.
    3875** ^The rollback callback is not invoked if a transaction is
    3876** rolled back because a commit callback returned non-zero.
    3877**
    3878** See also the [sqlite3_update_hook()] interface.
    3879*/
    3880SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
    3881SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
    3882
    3883/*
    3884** CAPI3REF: Data Change Notification Callbacks

    --- 37 unchanged lines hidden (view full) ---

    3922** returns the P argument from the previous call
    3923** on the same [database connection] D, or NULL for
    3924** the first call on D.
    3925**
    3926** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
    3927** interfaces.
    3928*/
    3929SQLITE_API void *sqlite3_update_hook(
    		4406**
    4407** See also the [sqlite3_update_hook()] interface.
    4408*/
    4409SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
    4410SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
    4411
    4412/*
    4413** CAPI3REF: Data Change Notification Callbacks

    --- 37 unchanged lines hidden (view full) ---

    4451** returns the P argument from the previous call
    4452** on the same [database connection] D, or NULL for
    4453** the first call on D.
    4454**
    4455** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
    4456** interfaces.
    4457*/
    4458SQLITE_API void *sqlite3_update_hook(
    3930 sqlite3*,
    		4459 sqlite3*,
    3931 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
    3932 void*
    3933);
    3934
    3935/*
    3936** CAPI3REF: Enable Or Disable Shared Pager Cache
    3937** KEYWORDS: {shared cache}
    3938**

    --- 26 unchanged lines hidden (view full) ---

    3965** CAPI3REF: Attempt To Free Heap Memory
    3966**
    3967** ^The sqlite3_release_memory() interface attempts to free N bytes
    3968** of heap memory by deallocating non-essential memory allocations
    3969** held by the database library. Memory used to cache database
    3970** pages to improve performance is an example of non-essential memory.
    3971** ^sqlite3_release_memory() returns the number of bytes actually freed,
    3972** which might be more or less than the amount requested.
    		4460 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
    4461 void*
    4462);
    4463
    4464/*
    4465** CAPI3REF: Enable Or Disable Shared Pager Cache
    4466** KEYWORDS: {shared cache}
    4467**

    --- 26 unchanged lines hidden (view full) ---

    4494** CAPI3REF: Attempt To Free Heap Memory
    4495**
    4496** ^The sqlite3_release_memory() interface attempts to free N bytes
    4497** of heap memory by deallocating non-essential memory allocations
    4498** held by the database library. Memory used to cache database
    4499** pages to improve performance is an example of non-essential memory.
    4500** ^sqlite3_release_memory() returns the number of bytes actually freed,
    4501** which might be more or less than the amount requested.
    4502** ^The sqlite3_release_memory() routine is a no-op returning zero
    4503** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
    3973*/
    3974SQLITE_API int sqlite3_release_memory(int);
    3975
    3976/*
    3977** CAPI3REF: Impose A Limit On Heap Size
    3978**
    		4504*/
    4505SQLITE_API int sqlite3_release_memory(int);
    4506
    4507/*
    4508** CAPI3REF: Impose A Limit On Heap Size
    4509**
    3979** ^The sqlite3_soft_heap_limit() interface places a "soft" limit
    3980** on the amount of heap memory that may be allocated by SQLite.
    3981** ^If an internal allocation is requested that would exceed the
    3982** soft heap limit, [sqlite3_release_memory()] is invoked one or
    3983** more times to free up some space before the allocation is performed.
    		4510** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
    4511** soft limit on the amount of heap memory that may be allocated by SQLite.
    4512** ^SQLite strives to keep heap memory utilization below the soft heap
    4513** limit by reducing the number of pages held in the page cache
    4514** as heap memory usages approaches the limit.
    4515** ^The soft heap limit is "soft" because even though SQLite strives to stay
    4516** below the limit, it will exceed the limit rather than generate
    4517** an [SQLITE_NOMEM] error. In other words, the soft heap limit
    4518** is advisory only.
    3984**
    		4519**
    3985** ^The limit is called "soft" because if [sqlite3_release_memory()]
    3986** cannot free sufficient memory to prevent the limit from being exceeded,
    3987** the memory is allocated anyway and the current operation proceeds.
    		4520** ^The return value from sqlite3_soft_heap_limit64() is the size of
    4521** the soft heap limit prior to the call. ^If the argument N is negative
    4522** then no change is made to the soft heap limit. Hence, the current
    4523** size of the soft heap limit can be determined by invoking
    4524** sqlite3_soft_heap_limit64() with a negative argument.
    3988**
    		4525**
    3989** ^A negative or zero value for N means that there is no soft heap limit and
    3990** [sqlite3_release_memory()] will only be called when memory is exhausted.
    3991** ^The default value for the soft heap limit is zero.
    		4526** ^If the argument N is zero then the soft heap limit is disabled.
    3992**
    		4527**
    3993** ^(SQLite makes a best effort to honor the soft heap limit.
    3994** But if the soft heap limit cannot be honored, execution will
    3995** continue without error or notification.)^ This is why the limit is
    3996** called a "soft" limit. It is advisory only.
    		4528** ^(The soft heap limit is not enforced in the current implementation
    4529** if one or more of following conditions are true:
    3997**
    		4530**
    3998** Prior to SQLite version 3.5.0, this routine only constrained the memory
    3999** allocated by a single thread - the same thread in which this routine
    4000** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
    4001** applied to all threads. The value specified for the soft heap limit
    4002** is an upper bound on the total memory allocation for all threads. In
    4003** version 3.5.0 there is no mechanism for limiting the heap usage for
    4004** individual threads.
    		4531** <ul>
    4532** <li> The soft heap limit is set to zero.
    4533** <li> Memory accounting is disabled using a combination of the
    4534** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
    4535** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
    4536** <li> An alternative page cache implementation is specified using
    4537** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...).
    4538** <li> The page cache allocates from its own memory pool supplied
    4539** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
    4540** from the heap.
    4541** </ul>)^
    4542**
    4543** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
    4544** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
    4545** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
    4546** the soft heap limit is enforced on every memory allocation. Without
    4547** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
    4548** when memory is allocated by the page cache. Testing suggests that because
    4549** the page cache is the predominate memory user in SQLite, most
    4550** applications will achieve adequate soft heap limit enforcement without
    4551** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
    4552**
    4553** The circumstances under which SQLite will enforce the soft heap limit may
    4554** changes in future releases of SQLite.
    4005*/
    		4555*/
    4006SQLITE_API void sqlite3_soft_heap_limit(int);
    		4556SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
    4007
    4008/*
    		4557
    4558/*
    4559** CAPI3REF: Deprecated Soft Heap Limit Interface
    4560** DEPRECATED
    4561**
    4562** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
    4563** interface. This routine is provided for historical compatibility
    4564** only. All new applications should use the
    4565** [sqlite3_soft_heap_limit64()] interface rather than this one.
    4566*/
    4567SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
    4568
    4569
    4570/*
    4009** CAPI3REF: Extract Metadata About A Column Of A Table
    4010**
    4011** ^This routine returns metadata about a specific column of a specific
    4012** database table accessible using the [database connection] handle
    4013** passed as the first function argument.
    4014**
    4015** ^The column is identified by the second, third and fourth parameters to
    4016** this function. ^The second parameter is either the name of the database

    --- 105 unchanged lines hidden (view full) ---

    4122** ^Extension loading is off by default. See ticket #1863.
    4123** ^Call the sqlite3_enable_load_extension() routine with onoff==1
    4124** to turn extension loading on and call it with onoff==0 to turn
    4125** it back off again.
    4126*/
    4127SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
    4128
    4129/*
    		4571** CAPI3REF: Extract Metadata About A Column Of A Table
    4572**
    4573** ^This routine returns metadata about a specific column of a specific
    4574** database table accessible using the [database connection] handle
    4575** passed as the first function argument.
    4576**
    4577** ^The column is identified by the second, third and fourth parameters to
    4578** this function. ^The second parameter is either the name of the database

    --- 105 unchanged lines hidden (view full) ---

    4684** ^Extension loading is off by default. See ticket #1863.
    4685** ^Call the sqlite3_enable_load_extension() routine with onoff==1
    4686** to turn extension loading on and call it with onoff==0 to turn
    4687** it back off again.
    4688*/
    4689SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
    4690
    4691/*
    4130** CAPI3REF: Automatically Load An Extensions
    		4692** CAPI3REF: Automatically Load Statically Linked Extensions
    4131**
    		4693**
    4132** ^This API can be invoked at program startup in order to register
    4133** one or more statically linked extensions that will be available
    4134** to all new [database connections].
    		4694** ^This interface causes the xEntryPoint() function to be invoked for
    4695** each new [database connection] that is created. The idea here is that
    4696** xEntryPoint() is the entry point for a statically linked SQLite extension
    4697** that is to be automatically loaded into all new database connections.
    4135**
    		4698**
    4136** ^(This routine stores a pointer to the extension entry point
    4137** in an array that is obtained from [sqlite3_malloc()]. That memory
    4138** is deallocated by [sqlite3_reset_auto_extension()].)^
    		4699** ^(Even though the function prototype shows that xEntryPoint() takes
    4700** no arguments and returns void, SQLite invokes xEntryPoint() with three
    4701** arguments and expects and integer result as if the signature of the
    4702** entry point where as follows:
    4139**
    		4703**
    4140** ^This function registers an extension entry point that is
    4141** automatically invoked whenever a new [database connection]
    4142** is opened using [sqlite3_open()], [sqlite3_open16()],
    4143** or [sqlite3_open_v2()].
    4144** ^Duplicate extensions are detected so calling this routine
    4145** multiple times with the same extension is harmless.
    4146** ^Automatic extensions apply across all threads.
    		4704** <blockquote><pre>
    4705** &nbsp; int xEntryPoint(
    4706** &nbsp; sqlite3 *db,
    4707** &nbsp; const char **pzErrMsg,
    4708** &nbsp; const struct sqlite3_api_routines *pThunk
    4709** &nbsp; );
    4710** </pre></blockquote>)^
    4711**
    4712** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
    4713** point to an appropriate error message (obtained from [sqlite3_mprintf()])
    4714** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
    4715** is NULL before calling the xEntryPoint(). ^SQLite will invoke
    4716** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
    4717** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
    4718** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
    4719**
    4720** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
    4721** on the list of automatic extensions is a harmless no-op. ^No entry point
    4722** will be called more than once for each database connection that is opened.
    4723**
    4724** See also: [sqlite3_reset_auto_extension()].
    4147*/
    4148SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
    4149
    4150/*
    4151** CAPI3REF: Reset Automatic Extension Loading
    4152**
    		4725*/
    4726SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
    4727
    4728/*
    4729** CAPI3REF: Reset Automatic Extension Loading
    4730**
    4153** ^(This function disables all previously registered automatic
    4154** extensions. It undoes the effect of all prior
    4155** [sqlite3_auto_extension()] calls.)^
    4156**
    4157** ^This function disables automatic extensions in all threads.
    		4731** ^This interface disables all automatic extensions previously
    4732** registered using [sqlite3_auto_extension()].
    4158*/
    4159SQLITE_API void sqlite3_reset_auto_extension(void);
    4160
    4161/*
    		4733*/
    4734SQLITE_API void sqlite3_reset_auto_extension(void);
    4735
    4736/*
    4162****** EXPERIMENTAL - subject to change without notice **************
    4163**
    4164** The interface to the virtual-table mechanism is currently considered
    4165** to be experimental. The interface might change in incompatible ways.
    4166** If this is a problem for you, do not use the interface at this time.
    4167**
    4168** When the virtual-table mechanism stabilizes, we will declare the
    4169** interface fixed, support it indefinitely, and remove this comment.
    4170*/
    4171
    4172/*
    4173** Structures used by the virtual table interface
    4174*/
    4175typedef struct sqlite3_vtab sqlite3_vtab;
    4176typedef struct sqlite3_index_info sqlite3_index_info;
    4177typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
    4178typedef struct sqlite3_module sqlite3_module;
    4179
    4180/*
    4181** CAPI3REF: Virtual Table Object
    4182** KEYWORDS: sqlite3_module {virtual table module}
    		4737** The interface to the virtual-table mechanism is currently considered
    4738** to be experimental. The interface might change in incompatible ways.
    4739** If this is a problem for you, do not use the interface at this time.
    4740**
    4741** When the virtual-table mechanism stabilizes, we will declare the
    4742** interface fixed, support it indefinitely, and remove this comment.
    4743*/
    4744
    4745/*
    4746** Structures used by the virtual table interface
    4747*/
    4748typedef struct sqlite3_vtab sqlite3_vtab;
    4749typedef struct sqlite3_index_info sqlite3_index_info;
    4750typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
    4751typedef struct sqlite3_module sqlite3_module;
    4752
    4753/*
    4754** CAPI3REF: Virtual Table Object
    4755** KEYWORDS: sqlite3_module {virtual table module}
    4183** EXPERIMENTAL
    4184**
    		4756**
    4185** This structure, sometimes called a a "virtual table module",
    4186** defines the implementation of a [virtual tables].
    		4757** This structure, sometimes called a "virtual table module",
    4758** defines the implementation of a [virtual tables].
    4187** This structure consists mostly of methods for the module.
    4188**
    4189** ^A virtual table module is created by filling in a persistent
    4190** instance of this structure and passing a pointer to that instance
    4191** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
    4192** ^The registration remains valid until it is replaced by a different
    4193** module or until the [database connection] closes. The content
    4194** of this structure must not change while it is registered with

    --- 22 unchanged lines hidden (view full) ---

    4217 int (*xBegin)(sqlite3_vtab *pVTab);
    4218 int (*xSync)(sqlite3_vtab *pVTab);
    4219 int (*xCommit)(sqlite3_vtab *pVTab);
    4220 int (*xRollback)(sqlite3_vtab *pVTab);
    4221 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
    4222 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
    4223 void **ppArg);
    4224 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
    		4759** This structure consists mostly of methods for the module.
    4760**
    4761** ^A virtual table module is created by filling in a persistent
    4762** instance of this structure and passing a pointer to that instance
    4763** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
    4764** ^The registration remains valid until it is replaced by a different
    4765** module or until the [database connection] closes. The content
    4766** of this structure must not change while it is registered with

    --- 22 unchanged lines hidden (view full) ---

    4789 int (*xBegin)(sqlite3_vtab *pVTab);
    4790 int (*xSync)(sqlite3_vtab *pVTab);
    4791 int (*xCommit)(sqlite3_vtab *pVTab);
    4792 int (*xRollback)(sqlite3_vtab *pVTab);
    4793 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
    4794 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
    4795 void **ppArg);
    4796 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
    4797 /* The methods above are in version 1 of the sqlite_module object. Those
    4798 ** below are for version 2 and greater. */
    4799 int (*xSavepoint)(sqlite3_vtab *pVTab, int);
    4800 int (*xRelease)(sqlite3_vtab *pVTab, int);
    4801 int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
    4225};
    4226
    4227/*
    4228** CAPI3REF: Virtual Table Indexing Information
    4229** KEYWORDS: sqlite3_index_info
    		4802};
    4803
    4804/*
    4805** CAPI3REF: Virtual Table Indexing Information
    4806** KEYWORDS: sqlite3_index_info
    4230** EXPERIMENTAL
    4231**
    		4807**
    4232** The sqlite3_index_info structure and its substructures is used to
    		4808** The sqlite3_index_info structure and its substructures is used as part
    4809** of the [virtual table] interface to
    4233** pass information into and receive the reply from the [xBestIndex]
    4234** method of a [virtual table module]. The fields under **Inputs** are the
    4235** inputs to xBestIndex and are read-only. xBestIndex inserts its
    4236** results into the **Outputs** fields.
    4237**
    4238** ^(The aConstraint[] array records WHERE clause constraints of the form:
    4239**
    		4810** pass information into and receive the reply from the [xBestIndex]
    4811** method of a [virtual table module]. The fields under **Inputs** are the
    4812** inputs to xBestIndex and are read-only. xBestIndex inserts its
    4813** results into the **Outputs** fields.
    4814**
    4815** ^(The aConstraint[] array records WHERE clause constraints of the form:
    4816**
    4240** <pre>column OP expr</pre>
    		4817** <blockquote>column OP expr</blockquote>
    4241**
    4242** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^ ^(The particular operator is
    		4818**
    4819** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^ ^(The particular operator is
    4243** stored in aConstraint[].op.)^ ^(The index of the column is stored in
    		4820** stored in aConstraint[].op using one of the
    4821** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
    4822** ^(The index of the column is stored in
    4244** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
    4245** expr on the right-hand side can be evaluated (and thus the constraint
    4246** is usable) and false if it cannot.)^
    4247**
    4248** ^The optimizer automatically inverts terms of the form "expr OP column"
    4249** and makes other simplifications to the WHERE clause in an attempt to
    4250** get as many WHERE clause terms into the form shown above as possible.
    4251** ^The aConstraint[] array only reports WHERE clause terms that are

    --- 43 unchanged lines hidden (view full) ---

    4295 unsigned char omit; /* Do not code a test for this constraint */
    4296 } *aConstraintUsage;
    4297 int idxNum; /* Number used to identify the index */
    4298 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
    4299 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
    4300 int orderByConsumed; /* True if output is already ordered */
    4301 double estimatedCost; /* Estimated cost of using this index */
    4302};
    		4823** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
    4824** expr on the right-hand side can be evaluated (and thus the constraint
    4825** is usable) and false if it cannot.)^
    4826**
    4827** ^The optimizer automatically inverts terms of the form "expr OP column"
    4828** and makes other simplifications to the WHERE clause in an attempt to
    4829** get as many WHERE clause terms into the form shown above as possible.
    4830** ^The aConstraint[] array only reports WHERE clause terms that are

    --- 43 unchanged lines hidden (view full) ---

    4874 unsigned char omit; /* Do not code a test for this constraint */
    4875 } *aConstraintUsage;
    4876 int idxNum; /* Number used to identify the index */
    4877 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
    4878 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
    4879 int orderByConsumed; /* True if output is already ordered */
    4880 double estimatedCost; /* Estimated cost of using this index */
    4881};
    4882
    4883/*
    4884** CAPI3REF: Virtual Table Constraint Operator Codes
    4885**
    4886** These macros defined the allowed values for the
    4887** [sqlite3_index_info].aConstraint[].op field. Each value represents
    4888** an operator that is part of a constraint term in the wHERE clause of
    4889** a query that uses a [virtual table].
    4890*/
    4303#define SQLITE_INDEX_CONSTRAINT_EQ 2
    4304#define SQLITE_INDEX_CONSTRAINT_GT 4
    4305#define SQLITE_INDEX_CONSTRAINT_LE 8
    4306#define SQLITE_INDEX_CONSTRAINT_LT 16
    4307#define SQLITE_INDEX_CONSTRAINT_GE 32
    4308#define SQLITE_INDEX_CONSTRAINT_MATCH 64
    4309
    4310/*
    4311** CAPI3REF: Register A Virtual Table Implementation
    		4891#define SQLITE_INDEX_CONSTRAINT_EQ 2
    4892#define SQLITE_INDEX_CONSTRAINT_GT 4
    4893#define SQLITE_INDEX_CONSTRAINT_LE 8
    4894#define SQLITE_INDEX_CONSTRAINT_LT 16
    4895#define SQLITE_INDEX_CONSTRAINT_GE 32
    4896#define SQLITE_INDEX_CONSTRAINT_MATCH 64
    4897
    4898/*
    4899** CAPI3REF: Register A Virtual Table Implementation
    4312** EXPERIMENTAL
    4313**
    4314** ^These routines are used to register a new [virtual table module] name.
    4315** ^Module names must be registered before
    4316** creating a new [virtual table] using the module and before using a
    4317** preexisting [virtual table] for the module.
    4318**
    4319** ^The module name is registered on the [database connection] specified
    		4900**
    4901** ^These routines are used to register a new [virtual table module] name.
    4902** ^Module names must be registered before
    4903** creating a new [virtual table] using the module and before using a
    4904** preexisting [virtual table] for the module.
    4905**
    4906** ^The module name is registered on the [database connection] specified
    4320** by the first parameter. ^The name of the module is given by the
    		4907** by the first parameter. ^The name of the module is given by the
    4321** second parameter. ^The third parameter is a pointer to
    4322** the implementation of the [virtual table module]. ^The fourth
    4323** parameter is an arbitrary client data pointer that is passed through
    4324** into the [xCreate] and [xConnect] methods of the virtual table module
    4325** when a new virtual table is be being created or reinitialized.
    4326**
    4327** ^The sqlite3_create_module_v2() interface has a fifth parameter which
    4328** is a pointer to a destructor for the pClientData. ^SQLite will
    4329** invoke the destructor function (if it is not NULL) when SQLite
    		4908** second parameter. ^The third parameter is a pointer to
    4909** the implementation of the [virtual table module]. ^The fourth
    4910** parameter is an arbitrary client data pointer that is passed through
    4911** into the [xCreate] and [xConnect] methods of the virtual table module
    4912** when a new virtual table is be being created or reinitialized.
    4913**
    4914** ^The sqlite3_create_module_v2() interface has a fifth parameter which
    4915** is a pointer to a destructor for the pClientData. ^SQLite will
    4916** invoke the destructor function (if it is not NULL) when SQLite
    4330** no longer needs the pClientData pointer. ^The sqlite3_create_module()
    		4917** no longer needs the pClientData pointer. ^The destructor will also
    4918** be invoked if the call to sqlite3_create_module_v2() fails.
    4919** ^The sqlite3_create_module()
    4331** interface is equivalent to sqlite3_create_module_v2() with a NULL
    4332** destructor.
    4333*/
    		4920** interface is equivalent to sqlite3_create_module_v2() with a NULL
    4921** destructor.
    4922*/
    4334SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module(
    		4923SQLITE_API int sqlite3_create_module(
    4335 sqlite3 *db, /* SQLite connection to register module with */
    4336 const char *zName, /* Name of the module */
    4337 const sqlite3_module *p, /* Methods for the module */
    4338 void *pClientData /* Client data for xCreate/xConnect */
    4339);
    		4924 sqlite3 *db, /* SQLite connection to register module with */
    4925 const char *zName, /* Name of the module */
    4926 const sqlite3_module *p, /* Methods for the module */
    4927 void *pClientData /* Client data for xCreate/xConnect */
    4928);
    4340SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
    		4929SQLITE_API int sqlite3_create_module_v2(
    4341 sqlite3 *db, /* SQLite connection to register module with */
    4342 const char *zName, /* Name of the module */
    4343 const sqlite3_module *p, /* Methods for the module */
    4344 void *pClientData, /* Client data for xCreate/xConnect */
    4345 void(*xDestroy)(void*) /* Module destructor function */
    4346);
    4347
    4348/*
    4349** CAPI3REF: Virtual Table Instance Object
    4350** KEYWORDS: sqlite3_vtab
    		4930 sqlite3 *db, /* SQLite connection to register module with */
    4931 const char *zName, /* Name of the module */
    4932 const sqlite3_module *p, /* Methods for the module */
    4933 void *pClientData, /* Client data for xCreate/xConnect */
    4934 void(*xDestroy)(void*) /* Module destructor function */
    4935);
    4936
    4937/*
    4938** CAPI3REF: Virtual Table Instance Object
    4939** KEYWORDS: sqlite3_vtab
    4351** EXPERIMENTAL
    4352**
    4353** Every [virtual table module] implementation uses a subclass
    4354** of this object to describe a particular instance
    4355** of the [virtual table]. Each subclass will
    4356** be tailored to the specific needs of the module implementation.
    4357** The purpose of this superclass is to define certain fields that are
    4358** common to all module implementations.
    4359**

    --- 9 unchanged lines hidden (view full) ---

    4369 int nRef; /* NO LONGER USED */
    4370 char *zErrMsg; /* Error message from sqlite3_mprintf() */
    4371 /* Virtual table implementations will typically add additional fields */
    4372};
    4373
    4374/*
    4375** CAPI3REF: Virtual Table Cursor Object
    4376** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
    		4940**
    4941** Every [virtual table module] implementation uses a subclass
    4942** of this object to describe a particular instance
    4943** of the [virtual table]. Each subclass will
    4944** be tailored to the specific needs of the module implementation.
    4945** The purpose of this superclass is to define certain fields that are
    4946** common to all module implementations.
    4947**

    --- 9 unchanged lines hidden (view full) ---

    4957 int nRef; /* NO LONGER USED */
    4958 char *zErrMsg; /* Error message from sqlite3_mprintf() */
    4959 /* Virtual table implementations will typically add additional fields */
    4960};
    4961
    4962/*
    4963** CAPI3REF: Virtual Table Cursor Object
    4964** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
    4377** EXPERIMENTAL
    4378**
    4379** Every [virtual table module] implementation uses a subclass of the
    4380** following structure to describe cursors that point into the
    4381** [virtual table] and are used
    4382** to loop through the virtual table. Cursors are created using the
    4383** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
    4384** by the [sqlite3_module.xClose | xClose] method. Cursors are used
    4385** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods

    --- 5 unchanged lines hidden (view full) ---

    4391*/
    4392struct sqlite3_vtab_cursor {
    4393 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
    4394 /* Virtual table implementations will typically add additional fields */
    4395};
    4396
    4397/*
    4398** CAPI3REF: Declare The Schema Of A Virtual Table
    		4965**
    4966** Every [virtual table module] implementation uses a subclass of the
    4967** following structure to describe cursors that point into the
    4968** [virtual table] and are used
    4969** to loop through the virtual table. Cursors are created using the
    4970** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
    4971** by the [sqlite3_module.xClose | xClose] method. Cursors are used
    4972** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods

    --- 5 unchanged lines hidden (view full) ---

    4978*/
    4979struct sqlite3_vtab_cursor {
    4980 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
    4981 /* Virtual table implementations will typically add additional fields */
    4982};
    4983
    4984/*
    4985** CAPI3REF: Declare The Schema Of A Virtual Table
    4399** EXPERIMENTAL
    4400**
    4401** ^The [xCreate] and [xConnect] methods of a
    4402** [virtual table module] call this interface
    4403** to declare the format (the names and datatypes of the columns) of
    4404** the virtual tables they implement.
    4405*/
    		4986**
    4987** ^The [xCreate] and [xConnect] methods of a
    4988** [virtual table module] call this interface
    4989** to declare the format (the names and datatypes of the columns) of
    4990** the virtual tables they implement.
    4991*/
    4406SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
    		4992SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
    4407
    4408/*
    4409** CAPI3REF: Overload A Function For A Virtual Table
    		4993
    4994/*
    4995** CAPI3REF: Overload A Function For A Virtual Table
    4410** EXPERIMENTAL
    4411**
    4412** ^(Virtual tables can provide alternative implementations of functions
    		4996**
    4997** ^(Virtual tables can provide alternative implementations of functions
    4413** using the [xFindFunction] method of the [virtual table module].
    		4998** using the [xFindFunction] method of the [virtual table module].
    4414** But global versions of those functions
    4415** must exist in order to be overloaded.)^
    4416**
    4417** ^(This API makes sure a global version of a function with a particular
    4418** name and number of parameters exists. If no such function exists
    4419** before this API is called, a new function is created.)^ ^The implementation
    4420** of the new function always causes an exception to be thrown. So
    4421** the new function is not good for anything by itself. Its only
    4422** purpose is to be a placeholder function that can be overloaded
    4423** by a [virtual table].
    4424*/
    		4999** But global versions of those functions
    5000** must exist in order to be overloaded.)^
    5001**
    5002** ^(This API makes sure a global version of a function with a particular
    5003** name and number of parameters exists. If no such function exists
    5004** before this API is called, a new function is created.)^ ^The implementation
    5005** of the new function always causes an exception to be thrown. So
    5006** the new function is not good for anything by itself. Its only
    5007** purpose is to be a placeholder function that can be overloaded
    5008** by a [virtual table].
    5009*/
    4425SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
    		5010SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
    4426
    4427/*
    4428** The interface to the virtual-table mechanism defined above (back up
    4429** to a comment remarkably similar to this one) is currently considered
    4430** to be experimental. The interface might change in incompatible ways.
    4431** If this is a problem for you, do not use the interface at this time.
    4432**
    4433** When the virtual-table mechanism stabilizes, we will declare the
    4434** interface fixed, support it indefinitely, and remove this comment.
    		5011
    5012/*
    5013** The interface to the virtual-table mechanism defined above (back up
    5014** to a comment remarkably similar to this one) is currently considered
    5015** to be experimental. The interface might change in incompatible ways.
    5016** If this is a problem for you, do not use the interface at this time.
    5017**
    5018** When the virtual-table mechanism stabilizes, we will declare the
    5019** interface fixed, support it indefinitely, and remove this comment.
    4435**
    4436****** EXPERIMENTAL - subject to change without notice **************
    4437*/
    4438
    4439/*
    4440** CAPI3REF: A Handle To An Open BLOB
    4441** KEYWORDS: {BLOB handle} {BLOB handles}
    4442**
    4443** An instance of this object represents an open BLOB on which
    4444** [sqlite3_blob_open | incremental BLOB I/O] can be performed.

    --- 13 unchanged lines hidden (view full) ---

    4458** in other words, the same BLOB that would be selected by:
    4459**
    4460** <pre>
    4461** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
    4462** </pre>)^
    4463**
    4464** ^If the flags parameter is non-zero, then the BLOB is opened for read
    4465** and write access. ^If it is zero, the BLOB is opened for read access.
    		5020*/
    5021
    5022/*
    5023** CAPI3REF: A Handle To An Open BLOB
    5024** KEYWORDS: {BLOB handle} {BLOB handles}
    5025**
    5026** An instance of this object represents an open BLOB on which
    5027** [sqlite3_blob_open | incremental BLOB I/O] can be performed.

    --- 13 unchanged lines hidden (view full) ---

    5041** in other words, the same BLOB that would be selected by:
    5042**
    5043** <pre>
    5044** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
    5045** </pre>)^
    5046**
    5047** ^If the flags parameter is non-zero, then the BLOB is opened for read
    5048** and write access. ^If it is zero, the BLOB is opened for read access.
    4466** ^It is not possible to open a column that is part of an index or primary
    4467** key for writing. ^If [foreign key constraints] are enabled, it is
    		5049** ^It is not possible to open a column that is part of an index or primary
    5050** key for writing. ^If [foreign key constraints] are enabled, it is
    4468** not possible to open a column that is part of a [child key] for writing.
    4469**
    4470** ^Note that the database name is not the filename that contains
    4471** the database but rather the symbolic name of the database that
    4472** appears after the AS keyword when the database is connected using [ATTACH].
    4473** ^For the main database file, the database name is "main".
    4474** ^For TEMP tables, the database name is "temp".
    4475**

    --- 7 unchanged lines hidden (view full) ---

    4483** regardless of the success or failure of this routine.
    4484**
    4485** ^(If the row that a BLOB handle points to is modified by an
    4486** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
    4487** then the BLOB handle is marked as "expired".
    4488** This is true if any column of the row is changed, even a column
    4489** other than the one the BLOB handle is open on.)^
    4490** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
    		5051** not possible to open a column that is part of a [child key] for writing.
    5052**
    5053** ^Note that the database name is not the filename that contains
    5054** the database but rather the symbolic name of the database that
    5055** appears after the AS keyword when the database is connected using [ATTACH].
    5056** ^For the main database file, the database name is "main".
    5057** ^For TEMP tables, the database name is "temp".
    5058**

    --- 7 unchanged lines hidden (view full) ---

    5066** regardless of the success or failure of this routine.
    5067**
    5068** ^(If the row that a BLOB handle points to is modified by an
    5069** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
    5070** then the BLOB handle is marked as "expired".
    5071** This is true if any column of the row is changed, even a column
    5072** other than the one the BLOB handle is open on.)^
    5073** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
    4491** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
    		5074** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
    4492** ^(Changes written into a BLOB prior to the BLOB expiring are not
    4493** rolled back by the expiration of the BLOB. Such changes will eventually
    4494** commit if the transaction continues to completion.)^
    4495**
    4496** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
    4497** the opened blob. ^The size of a blob may not be changed by this
    4498** interface. Use the [UPDATE] SQL command to change the size of a
    4499** blob.

    --- 12 unchanged lines hidden (view full) ---

    4512 const char *zTable,
    4513 const char *zColumn,
    4514 sqlite3_int64 iRow,
    4515 int flags,
    4516 sqlite3_blob **ppBlob
    4517);
    4518
    4519/*
    		5075** ^(Changes written into a BLOB prior to the BLOB expiring are not
    5076** rolled back by the expiration of the BLOB. Such changes will eventually
    5077** commit if the transaction continues to completion.)^
    5078**
    5079** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
    5080** the opened blob. ^The size of a blob may not be changed by this
    5081** interface. Use the [UPDATE] SQL command to change the size of a
    5082** blob.

    --- 12 unchanged lines hidden (view full) ---

    5095 const char *zTable,
    5096 const char *zColumn,
    5097 sqlite3_int64 iRow,
    5098 int flags,
    5099 sqlite3_blob **ppBlob
    5100);
    5101
    5102/*
    5103** CAPI3REF: Move a BLOB Handle to a New Row
    5104**
    5105** ^This function is used to move an existing blob handle so that it points
    5106** to a different row of the same database table. ^The new row is identified
    5107** by the rowid value passed as the second argument. Only the row can be
    5108** changed. ^The database, table and column on which the blob handle is open
    5109** remain the same. Moving an existing blob handle to a new row can be
    5110** faster than closing the existing handle and opening a new one.
    5111**
    5112** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
    5113** it must exist and there must be either a blob or text value stored in
    5114** the nominated column.)^ ^If the new row is not present in the table, or if
    5115** it does not contain a blob or text value, or if another error occurs, an
    5116** SQLite error code is returned and the blob handle is considered aborted.
    5117** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
    5118** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
    5119** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
    5120** always returns zero.
    5121**
    5122** ^This function sets the database handle error code and message.
    5123*/
    5124SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
    5125
    5126/*
    4520** CAPI3REF: Close A BLOB Handle
    4521**
    4522** ^Closes an open [BLOB handle].
    4523**
    4524** ^Closing a BLOB shall cause the current transaction to commit
    4525** if there are no other BLOBs, no pending prepared statements, and the
    4526** database connection is in [autocommit mode].
    4527** ^If any writes were made to the BLOB, they might be held in cache

    --- 10 unchanged lines hidden (view full) ---

    4538** ^Calling this routine with a null pointer (such as would be returned
    4539** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
    4540*/
    4541SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
    4542
    4543/*
    4544** CAPI3REF: Return The Size Of An Open BLOB
    4545**
    		5127** CAPI3REF: Close A BLOB Handle
    5128**
    5129** ^Closes an open [BLOB handle].
    5130**
    5131** ^Closing a BLOB shall cause the current transaction to commit
    5132** if there are no other BLOBs, no pending prepared statements, and the
    5133** database connection is in [autocommit mode].
    5134** ^If any writes were made to the BLOB, they might be held in cache

    --- 10 unchanged lines hidden (view full) ---

    5145** ^Calling this routine with a null pointer (such as would be returned
    5146** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
    5147*/
    5148SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
    5149
    5150/*
    5151** CAPI3REF: Return The Size Of An Open BLOB
    5152**
    4546** ^Returns the size in bytes of the BLOB accessible via the
    		5153** ^Returns the size in bytes of the BLOB accessible via the
    4547** successfully opened [BLOB handle] in its only argument. ^The
    4548** incremental blob I/O routines can only read or overwriting existing
    4549** blob content; they cannot change the size of a blob.
    4550**
    4551** This routine only works on a [BLOB handle] which has been created
    4552** by a prior successful call to [sqlite3_blob_open()] and which has not
    4553** been closed by [sqlite3_blob_close()]. Passing any other pointer in
    4554** to this routine results in undefined and probably undesirable behavior.

    --- 216 unchanged lines hidden (view full) ---

    4771SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
    4772SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
    4773SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
    4774SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
    4775SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
    4776
    4777/*
    4778** CAPI3REF: Mutex Methods Object
    		5154** successfully opened [BLOB handle] in its only argument. ^The
    5155** incremental blob I/O routines can only read or overwriting existing
    5156** blob content; they cannot change the size of a blob.
    5157**
    5158** This routine only works on a [BLOB handle] which has been created
    5159** by a prior successful call to [sqlite3_blob_open()] and which has not
    5160** been closed by [sqlite3_blob_close()]. Passing any other pointer in
    5161** to this routine results in undefined and probably undesirable behavior.

    --- 216 unchanged lines hidden (view full) ---

    5378SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
    5379SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
    5380SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
    5381SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
    5382SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
    5383
    5384/*
    5385** CAPI3REF: Mutex Methods Object
    4779** EXPERIMENTAL
    4780**
    4781** An instance of this structure defines the low-level routines
    4782** used to allocate and use mutexes.
    4783**
    4784** Usually, the default mutex implementations provided by SQLite are
    4785** sufficient, however the user has the option of substituting a custom
    4786** implementation for specialized deployments or systems for which SQLite
    4787** does not provide a suitable implementation. In this case, the user
    4788** creates and populates an instance of this structure to pass
    4789** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
    4790** Additionally, an instance of this structure can be used as an
    4791** output variable when querying the system for the current mutex
    4792** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
    4793**
    4794** ^The xMutexInit method defined by this structure is invoked as
    4795** part of system initialization by the sqlite3_initialize() function.
    		5386**
    5387** An instance of this structure defines the low-level routines
    5388** used to allocate and use mutexes.
    5389**
    5390** Usually, the default mutex implementations provided by SQLite are
    5391** sufficient, however the user has the option of substituting a custom
    5392** implementation for specialized deployments or systems for which SQLite
    5393** does not provide a suitable implementation. In this case, the user
    5394** creates and populates an instance of this structure to pass
    5395** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
    5396** Additionally, an instance of this structure can be used as an
    5397** output variable when querying the system for the current mutex
    5398** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
    5399**
    5400** ^The xMutexInit method defined by this structure is invoked as
    5401** part of system initialization by the sqlite3_initialize() function.
    4796** ^The xMutexInit routine is calle by SQLite exactly once for each
    		5402** ^The xMutexInit routine is called by SQLite exactly once for each
    4797** effective call to [sqlite3_initialize()].
    4798**
    4799** ^The xMutexEnd method defined by this structure is invoked as
    4800** part of system shutdown by the sqlite3_shutdown() function. The
    4801** implementation of this method is expected to release all outstanding
    4802** resources obtained by the mutex methods implementation, especially
    4803** those obtained by the xMutexInit method. ^The xMutexEnd()
    4804** interface is invoked exactly once for each call to [sqlite3_shutdown()].

    --- 16 unchanged lines hidden (view full) ---

    4821** above silently ignore any invocations that pass a NULL pointer instead
    4822** of a valid mutex handle. The implementations of the methods defined
    4823** by this structure are not required to handle this case, the results
    4824** of passing a NULL pointer instead of a valid mutex handle are undefined
    4825** (i.e. it is acceptable to provide an implementation that segfaults if
    4826** it is passed a NULL pointer).
    4827**
    4828** The xMutexInit() method must be threadsafe. ^It must be harmless to
    		5403** effective call to [sqlite3_initialize()].
    5404**
    5405** ^The xMutexEnd method defined by this structure is invoked as
    5406** part of system shutdown by the sqlite3_shutdown() function. The
    5407** implementation of this method is expected to release all outstanding
    5408** resources obtained by the mutex methods implementation, especially
    5409** those obtained by the xMutexInit method. ^The xMutexEnd()
    5410** interface is invoked exactly once for each call to [sqlite3_shutdown()].

    --- 16 unchanged lines hidden (view full) ---

    5427** above silently ignore any invocations that pass a NULL pointer instead
    5428** of a valid mutex handle. The implementations of the methods defined
    5429** by this structure are not required to handle this case, the results
    5430** of passing a NULL pointer instead of a valid mutex handle are undefined
    5431** (i.e. it is acceptable to provide an implementation that segfaults if
    5432** it is passed a NULL pointer).
    5433**
    5434** The xMutexInit() method must be threadsafe. ^It must be harmless to
    4829** invoke xMutexInit() mutiple times within the same process and without
    		5435** invoke xMutexInit() multiple times within the same process and without
    4830** intervening calls to xMutexEnd(). Second and subsequent calls to
    4831** xMutexInit() must be no-ops.
    4832**
    4833** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
    4834** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory
    4835** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
    4836** memory allocation for a fast or recursive mutex.
    4837**

    --- 32 unchanged lines hidden (view full) ---

    4870**
    4871** ^The implementation is not required to provided versions of these
    4872** routines that actually work. If the implementation does not provide working
    4873** versions of these routines, it should at least provide stubs that always
    4874** return true so that one does not get spurious assertion failures.
    4875**
    4876** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
    4877** the routine should return 1. This seems counter-intuitive since
    		5436** intervening calls to xMutexEnd(). Second and subsequent calls to
    5437** xMutexInit() must be no-ops.
    5438**
    5439** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
    5440** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory
    5441** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
    5442** memory allocation for a fast or recursive mutex.
    5443**

    --- 32 unchanged lines hidden (view full) ---

    5476**
    5477** ^The implementation is not required to provided versions of these
    5478** routines that actually work. If the implementation does not provide working
    5479** versions of these routines, it should at least provide stubs that always
    5480** return true so that one does not get spurious assertion failures.
    5481**
    5482** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
    5483** the routine should return 1. This seems counter-intuitive since
    4878** clearly the mutex cannot be held if it does not exist. But the
    		5484** clearly the mutex cannot be held if it does not exist. But
    4879** the reason the mutex does not exist is because the build is not
    4880** using mutexes. And we do not want the assert() containing the
    4881** call to sqlite3_mutex_held() to fail, so a non-zero return is
    4882** the appropriate thing to do. ^The sqlite3_mutex_notheld()
    4883** interface should also return 1 when given a NULL pointer.
    4884*/
    4885#ifndef NDEBUG
    4886SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);

    --- 13 unchanged lines hidden (view full) ---

    4900#define SQLITE_MUTEX_FAST 0
    4901#define SQLITE_MUTEX_RECURSIVE 1
    4902#define SQLITE_MUTEX_STATIC_MASTER 2
    4903#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
    4904#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
    4905#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
    4906#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
    4907#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
    		5485** the reason the mutex does not exist is because the build is not
    5486** using mutexes. And we do not want the assert() containing the
    5487** call to sqlite3_mutex_held() to fail, so a non-zero return is
    5488** the appropriate thing to do. ^The sqlite3_mutex_notheld()
    5489** interface should also return 1 when given a NULL pointer.
    5490*/
    5491#ifndef NDEBUG
    5492SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);

    --- 13 unchanged lines hidden (view full) ---

    5506#define SQLITE_MUTEX_FAST 0
    5507#define SQLITE_MUTEX_RECURSIVE 1
    5508#define SQLITE_MUTEX_STATIC_MASTER 2
    5509#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
    5510#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
    5511#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
    5512#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
    5513#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
    4908#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
    		5514#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
    5515#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
    4909
    4910/*
    4911** CAPI3REF: Retrieve the mutex for a database connection
    4912**
    		5516
    5517/*
    5518** CAPI3REF: Retrieve the mutex for a database connection
    5519**
    4913** ^This interface returns a pointer the [sqlite3_mutex] object that
    		5520** ^This interface returns a pointer the [sqlite3_mutex] object that
    4914** serializes access to the [database connection] given in the argument
    4915** when the [threading mode] is Serialized.
    4916** ^If the [threading mode] is Single-thread or Multi-thread then this
    4917** routine returns a NULL pointer.
    4918*/
    4919SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
    4920
    4921/*
    4922** CAPI3REF: Low-Level Control Of Database Files
    4923**
    4924** ^The [sqlite3_file_control()] interface makes a direct call to the
    4925** xFileControl method for the [sqlite3_io_methods] object associated
    4926** with a particular database identified by the second argument. ^The
    		5521** serializes access to the [database connection] given in the argument
    5522** when the [threading mode] is Serialized.
    5523** ^If the [threading mode] is Single-thread or Multi-thread then this
    5524** routine returns a NULL pointer.
    5525*/
    5526SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
    5527
    5528/*
    5529** CAPI3REF: Low-Level Control Of Database Files
    5530**
    5531** ^The [sqlite3_file_control()] interface makes a direct call to the
    5532** xFileControl method for the [sqlite3_io_methods] object associated
    5533** with a particular database identified by the second argument. ^The
    4927** name of the database "main" for the main database or "temp" for the
    		5534** name of the database is "main" for the main database or "temp" for the
    4928** TEMP database, or the name that appears after the AS keyword for
    4929** databases that are added using the [ATTACH] SQL command.
    4930** ^A NULL pointer can be used in place of "main" to refer to the
    4931** main database file.
    4932** ^The third and fourth parameters to this routine
    4933** are passed directly through to the second and third parameters of
    4934** the xFileControl method. ^The return value of the xFileControl
    4935** method becomes the return value of this routine.
    4936**
    		5535** TEMP database, or the name that appears after the AS keyword for
    5536** databases that are added using the [ATTACH] SQL command.
    5537** ^A NULL pointer can be used in place of "main" to refer to the
    5538** main database file.
    5539** ^The third and fourth parameters to this routine
    5540** are passed directly through to the second and third parameters of
    5541** the xFileControl method. ^The return value of the xFileControl
    5542** method becomes the return value of this routine.
    5543**
    5544** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
    5545** a pointer to the underlying [sqlite3_file] object to be written into
    5546** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER
    5547** case is a short-circuit path which does not actually invoke the
    5548** underlying sqlite3_io_methods.xFileControl method.
    5549**
    4937** ^If the second parameter (zDbName) does not match the name of any
    4938** open database file, then SQLITE_ERROR is returned. ^This error
    4939** code is not remembered and will not be recalled by [sqlite3_errcode()]
    4940** or [sqlite3_errmsg()]. The underlying xFileControl method might
    4941** also return SQLITE_ERROR. There is no way to distinguish between
    4942** an incorrect zDbName and an SQLITE_ERROR return from the underlying
    4943** xFileControl method.
    4944**

    --- 39 unchanged lines hidden (view full) ---

    4984#define SQLITE_TESTCTRL_FAULT_INSTALL 9
    4985#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
    4986#define SQLITE_TESTCTRL_PENDING_BYTE 11
    4987#define SQLITE_TESTCTRL_ASSERT 12
    4988#define SQLITE_TESTCTRL_ALWAYS 13
    4989#define SQLITE_TESTCTRL_RESERVE 14
    4990#define SQLITE_TESTCTRL_OPTIMIZATIONS 15
    4991#define SQLITE_TESTCTRL_ISKEYWORD 16
    		5550** ^If the second parameter (zDbName) does not match the name of any
    5551** open database file, then SQLITE_ERROR is returned. ^This error
    5552** code is not remembered and will not be recalled by [sqlite3_errcode()]
    5553** or [sqlite3_errmsg()]. The underlying xFileControl method might
    5554** also return SQLITE_ERROR. There is no way to distinguish between
    5555** an incorrect zDbName and an SQLITE_ERROR return from the underlying
    5556** xFileControl method.
    5557**

    --- 39 unchanged lines hidden (view full) ---

    5597#define SQLITE_TESTCTRL_FAULT_INSTALL 9
    5598#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
    5599#define SQLITE_TESTCTRL_PENDING_BYTE 11
    5600#define SQLITE_TESTCTRL_ASSERT 12
    5601#define SQLITE_TESTCTRL_ALWAYS 13
    5602#define SQLITE_TESTCTRL_RESERVE 14
    5603#define SQLITE_TESTCTRL_OPTIMIZATIONS 15
    5604#define SQLITE_TESTCTRL_ISKEYWORD 16
    4992#define SQLITE_TESTCTRL_LAST 16
    		5605#define SQLITE_TESTCTRL_PGHDRSZ 17
    5606#define SQLITE_TESTCTRL_SCRATCHMALLOC 18
    5607#define SQLITE_TESTCTRL_LOCALTIME_FAULT 19
    5608#define SQLITE_TESTCTRL_LAST 19
    4993
    4994/*
    4995** CAPI3REF: SQLite Runtime Status
    		5609
    5610/*
    5611** CAPI3REF: SQLite Runtime Status
    4996** EXPERIMENTAL
    4997**
    4998** ^This interface is used to retrieve runtime status information
    		5612**
    5613** ^This interface is used to retrieve runtime status information
    4999** about the preformance of SQLite, and optionally to reset various
    		5614** about the performance of SQLite, and optionally to reset various
    5000** highwater marks. ^The first argument is an integer code for
    5001** the specific parameter to measure. ^(Recognized integer codes
    		5615** highwater marks. ^The first argument is an integer code for
    5616** the specific parameter to measure. ^(Recognized integer codes
    5002** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].)^
    		5617** are of the form [status parameters | SQLITE_STATUS_...].)^
    5003** ^The current value of the parameter is returned into *pCurrent.
    5004** ^The highest recorded value is returned in *pHighwater. ^If the
    5005** resetFlag is true, then the highest record value is reset after
    5006** *pHighwater is written. ^(Some parameters do not record the highest
    5007** value. For those parameters
    5008** nothing is written into *pHighwater and the resetFlag is ignored.)^
    5009** ^(Other parameters record only the highwater mark and not the current
    5010** value. For these latter parameters nothing is written into *pCurrent.)^
    5011**
    		5618** ^The current value of the parameter is returned into *pCurrent.
    5619** ^The highest recorded value is returned in *pHighwater. ^If the
    5620** resetFlag is true, then the highest record value is reset after
    5621** *pHighwater is written. ^(Some parameters do not record the highest
    5622** value. For those parameters
    5623** nothing is written into *pHighwater and the resetFlag is ignored.)^
    5624** ^(Other parameters record only the highwater mark and not the current
    5625** value. For these latter parameters nothing is written into *pCurrent.)^
    5626**
    5012** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
    		5627** ^The sqlite3_status() routine returns SQLITE_OK on success and a
    5013** non-zero [error code] on failure.
    5014**
    5015** This routine is threadsafe but is not atomic. This routine can be
    5016** called while other threads are running the same or different SQLite
    5017** interfaces. However the values returned in *pCurrent and
    5018** *pHighwater reflect the status of SQLite at different points in time
    5019** and it is possible that another thread might change the parameter
    5020** in between the times when *pCurrent and *pHighwater are written.
    5021**
    5022** See also: [sqlite3_db_status()]
    5023*/
    		5628** non-zero [error code] on failure.
    5629**
    5630** This routine is threadsafe but is not atomic. This routine can be
    5631** called while other threads are running the same or different SQLite
    5632** interfaces. However the values returned in *pCurrent and
    5633** *pHighwater reflect the status of SQLite at different points in time
    5634** and it is possible that another thread might change the parameter
    5635** in between the times when *pCurrent and *pHighwater are written.
    5636**
    5637** See also: [sqlite3_db_status()]
    5638*/
    5024SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
    		5639SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
    5025
    5026
    5027/*
    5028** CAPI3REF: Status Parameters
    		5640
    5641
    5642/*
    5643** CAPI3REF: Status Parameters
    5029** EXPERIMENTAL
    		5644** KEYWORDS: {status parameters}
    5030**
    5031** These integer constants designate various run-time status parameters
    5032** that can be returned by [sqlite3_status()].
    5033**
    5034** <dl>
    		5645**
    5646** These integer constants designate various run-time status parameters
    5647** that can be returned by [sqlite3_status()].
    5648**
    5649** <dl>
    5035** ^(
    SQLITE_STATUS_MEMORY_USED

    		5650** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
    5036** <dd>This parameter is the current amount of memory checked out
    5037** using [sqlite3_malloc()], either directly or indirectly. The
    5038** figure includes calls made to [sqlite3_malloc()] by the application
    5039** and internal memory usage by the SQLite library. Scratch memory
    5040** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
    5041** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
    5042** this parameter. The amount returned is the sum of the allocation
    5043** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
    5044**
    		5651** <dd>This parameter is the current amount of memory checked out
    5652** using [sqlite3_malloc()], either directly or indirectly. The
    5653** figure includes calls made to [sqlite3_malloc()] by the application
    5654** and internal memory usage by the SQLite library. Scratch memory
    5655** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
    5656** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
    5657** this parameter. The amount returned is the sum of the allocation
    5658** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
    5659**
    5045** ^(
    SQLITE_STATUS_MALLOC_SIZE

    		5660** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
    5046** <dd>This parameter records the largest memory allocation request
    5047** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
    5048** internal equivalents). Only the value returned in the
    		5661** <dd>This parameter records the largest memory allocation request
    5662** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
    5663** internal equivalents). Only the value returned in the
    5049** *pHighwater parameter to [sqlite3_status()] is of interest.
    		5664** *pHighwater parameter to [sqlite3_status()] is of interest.
    5050** The value written into the *pCurrent parameter is undefined.</dd>)^
    5051**
    		5665** The value written into the *pCurrent parameter is undefined.</dd>)^
    5666**
    5052** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
    		5667** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
    5668** <dd>This parameter records the number of separate memory allocations
    5669** currently checked out.</dd>)^
    5670**
    5671** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
    5053** <dd>This parameter returns the number of pages used out of the
    		5672** <dd>This parameter returns the number of pages used out of the
    5054** [pagecache memory allocator] that was configured using
    		5673** [pagecache memory allocator] that was configured using
    5055** [SQLITE_CONFIG_PAGECACHE]. The
    5056** value returned is in pages, not in bytes.</dd>)^
    5057**
    		5674** [SQLITE_CONFIG_PAGECACHE]. The
    5675** value returned is in pages, not in bytes.</dd>)^
    5676**
    5677** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]
    5058** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
    5059** <dd>This parameter returns the number of bytes of page cache
    		5678** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
    5679** <dd>This parameter returns the number of bytes of page cache
    5060** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE]
    		5680** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
    5061** buffer and where forced to overflow to [sqlite3_malloc()]. The
    5062** returned value includes allocations that overflowed because they
    5063** where too large (they were larger than the "sz" parameter to
    5064** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
    5065** no space was left in the page cache.</dd>)^
    5066**
    		5681** buffer and where forced to overflow to [sqlite3_malloc()]. The
    5682** returned value includes allocations that overflowed because they
    5683** where too large (they were larger than the "sz" parameter to
    5684** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
    5685** no space was left in the page cache.</dd>)^
    5686**
    5067** ^(
    SQLITE_STATUS_PAGECACHE_SIZE

    		5687** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
    5068** <dd>This parameter records the largest memory allocation request
    5069** handed to [pagecache memory allocator]. Only the value returned in the
    		5688** <dd>This parameter records the largest memory allocation request
    5689** handed to [pagecache memory allocator]. Only the value returned in the
    5070** *pHighwater parameter to [sqlite3_status()] is of interest.
    		5690** *pHighwater parameter to [sqlite3_status()] is of interest.
    5071** The value written into the *pCurrent parameter is undefined.</dd>)^
    5072**
    		5691** The value written into the *pCurrent parameter is undefined.</dd>)^
    5692**
    5073** ^(
    SQLITE_STATUS_SCRATCH_USED

    		5693** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
    5074** <dd>This parameter returns the number of allocations used out of the
    5075** [scratch memory allocator] configured using
    5076** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
    5077** in bytes. Since a single thread may only have one scratch allocation
    5078** outstanding at time, this parameter also reports the number of threads
    5079** using scratch memory at the same time.</dd>)^
    5080**
    		5694** <dd>This parameter returns the number of allocations used out of the
    5695** [scratch memory allocator] configured using
    5696** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
    5697** in bytes. Since a single thread may only have one scratch allocation
    5698** outstanding at time, this parameter also reports the number of threads
    5699** using scratch memory at the same time.</dd>)^
    5700**
    5081** ^(
    SQLITE_STATUS_SCRATCH_OVERFLOW

    		5701** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
    5082** <dd>This parameter returns the number of bytes of scratch memory
    		5702** <dd>This parameter returns the number of bytes of scratch memory
    5083** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH]
    		5703** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
    5084** buffer and where forced to overflow to [sqlite3_malloc()]. The values
    5085** returned include overflows because the requested allocation was too
    5086** larger (that is, because the requested allocation was larger than the
    5087** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
    5088** slots were available.
    5089** </dd>)^
    5090**
    		5704** buffer and where forced to overflow to [sqlite3_malloc()]. The values
    5705** returned include overflows because the requested allocation was too
    5706** larger (that is, because the requested allocation was larger than the
    5707** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
    5708** slots were available.
    5709** </dd>)^
    5710**
    5091** ^(
    SQLITE_STATUS_SCRATCH_SIZE

    		5711** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
    5092** <dd>This parameter records the largest memory allocation request
    5093** handed to [scratch memory allocator]. Only the value returned in the
    		5712** <dd>This parameter records the largest memory allocation request
    5713** handed to [scratch memory allocator]. Only the value returned in the
    5094** *pHighwater parameter to [sqlite3_status()] is of interest.
    		5714** *pHighwater parameter to [sqlite3_status()] is of interest.
    5095** The value written into the *pCurrent parameter is undefined.</dd>)^
    5096**
    		5715** The value written into the *pCurrent parameter is undefined.</dd>)^
    5716**
    5097** ^(
    SQLITE_STATUS_PARSER_STACK

    		5717** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
    5098** <dd>This parameter records the deepest parser stack. It is only
    5099** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
    5100** </dl>
    5101**
    5102** New status parameters may be added from time to time.
    5103*/
    5104#define SQLITE_STATUS_MEMORY_USED 0
    5105#define SQLITE_STATUS_PAGECACHE_USED 1
    5106#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
    5107#define SQLITE_STATUS_SCRATCH_USED 3
    5108#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
    5109#define SQLITE_STATUS_MALLOC_SIZE 5
    5110#define SQLITE_STATUS_PARSER_STACK 6
    5111#define SQLITE_STATUS_PAGECACHE_SIZE 7
    5112#define SQLITE_STATUS_SCRATCH_SIZE 8
    		5718** <dd>This parameter records the deepest parser stack. It is only
    5719** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
    5720** </dl>
    5721**
    5722** New status parameters may be added from time to time.
    5723*/
    5724#define SQLITE_STATUS_MEMORY_USED 0
    5725#define SQLITE_STATUS_PAGECACHE_USED 1
    5726#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
    5727#define SQLITE_STATUS_SCRATCH_USED 3
    5728#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
    5729#define SQLITE_STATUS_MALLOC_SIZE 5
    5730#define SQLITE_STATUS_PARSER_STACK 6
    5731#define SQLITE_STATUS_PAGECACHE_SIZE 7
    5732#define SQLITE_STATUS_SCRATCH_SIZE 8
    5733#define SQLITE_STATUS_MALLOC_COUNT 9
    5113
    5114/*
    5115** CAPI3REF: Database Connection Status
    		5734
    5735/*
    5736** CAPI3REF: Database Connection Status
    5116** EXPERIMENTAL
    5117**
    		5737**
    5118** ^This interface is used to retrieve runtime status information
    		5738** ^This interface is used to retrieve runtime status information
    5119** about a single [database connection]. ^The first argument is the
    5120** database connection object to be interrogated. ^The second argument
    		5739** about a single [database connection]. ^The first argument is the
    5740** database connection object to be interrogated. ^The second argument
    5121** is the parameter to interrogate. ^Currently, the only allowed value
    5122** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
    5123** Additional options will likely appear in future releases of SQLite.
    		5741** is an integer constant, taken from the set of
    5742** [SQLITE_DBSTATUS options], that
    5743** determines the parameter to interrogate. The set of
    5744** [SQLITE_DBSTATUS options] is likely
    5745** to grow in future releases of SQLite.
    5124**
    5125** ^The current value of the requested parameter is written into *pCur
    5126** and the highest instantaneous value is written into *pHiwtr. ^If
    5127** the resetFlg is true, then the highest instantaneous value is
    5128** reset back down to the current value.
    5129**
    		5746**
    5747** ^The current value of the requested parameter is written into *pCur
    5748** and the highest instantaneous value is written into *pHiwtr. ^If
    5749** the resetFlg is true, then the highest instantaneous value is
    5750** reset back down to the current value.
    5751**
    5752** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
    5753** non-zero [error code] on failure.
    5754**
    5130** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
    5131*/
    		5755** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
    5756*/
    5132SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
    		5757SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
    5133
    5134/*
    5135** CAPI3REF: Status Parameters for database connections
    		5758
    5759/*
    5760** CAPI3REF: Status Parameters for database connections
    5136** EXPERIMENTAL
    		5761** KEYWORDS: {SQLITE_DBSTATUS options}
    5137**
    5138** These constants are the available integer "verbs" that can be passed as
    5139** the second argument to the [sqlite3_db_status()] interface.
    5140**
    5141** New verbs may be added in future releases of SQLite. Existing verbs
    5142** might be discontinued. Applications should check the return code from
    5143** [sqlite3_db_status()] to make sure that the call worked.
    5144** The [sqlite3_db_status()] interface will return a non-zero error code
    5145** if a discontinued or unsupported verb is invoked.
    5146**
    5147** <dl>
    		5762**
    5763** These constants are the available integer "verbs" that can be passed as
    5764** the second argument to the [sqlite3_db_status()] interface.
    5765**
    5766** New verbs may be added in future releases of SQLite. Existing verbs
    5767** might be discontinued. Applications should check the return code from
    5768** [sqlite3_db_status()] to make sure that the call worked.
    5769** The [sqlite3_db_status()] interface will return a non-zero error code
    5770** if a discontinued or unsupported verb is invoked.
    5771**
    5772** <dl>
    5148** ^(
    SQLITE_DBSTATUS_LOOKASIDE_USED

    		5773** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
    5149** <dd>This parameter returns the number of lookaside memory slots currently
    5150** checked out.</dd>)^
    		5774** <dd>This parameter returns the number of lookaside memory slots currently
    5775** checked out.</dd>)^
    5776**
    5777** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
    5778** <dd>This parameter returns the number malloc attempts that were
    5779** satisfied using lookaside memory. Only the high-water value is meaningful;
    5780** the current value is always zero.)^
    5781**
    5782** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
    5783** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
    5784** <dd>This parameter returns the number malloc attempts that might have
    5785** been satisfied using lookaside memory but failed due to the amount of
    5786** memory requested being larger than the lookaside slot size.
    5787** Only the high-water value is meaningful;
    5788** the current value is always zero.)^
    5789**
    5790** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
    5791** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
    5792** <dd>This parameter returns the number malloc attempts that might have
    5793** been satisfied using lookaside memory but failed due to all lookaside
    5794** memory already being in use.
    5795** Only the high-water value is meaningful;
    5796** the current value is always zero.)^
    5797**
    5798** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
    5799** <dd>This parameter returns the approximate number of of bytes of heap
    5800** memory used by all pager caches associated with the database connection.)^
    5801** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
    5802**
    5803** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
    5804** <dd>This parameter returns the approximate number of of bytes of heap
    5805** memory used to store the schema for all databases associated
    5806** with the connection - main, temp, and any [ATTACH]-ed databases.)^
    5807** ^The full amount of memory used by the schemas is reported, even if the
    5808** schema memory is shared with other database connections due to
    5809** [shared cache mode] being enabled.
    5810** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
    5811**
    5812** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
    5813** <dd>This parameter returns the approximate number of of bytes of heap
    5814** and lookaside memory used by all prepared statements associated with
    5815** the database connection.)^
    5816** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
    5817** </dd>
    5151** </dl>
    5152*/
    		5818** </dl>
    5819*/
    5153#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
    		5820#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
    5821#define SQLITE_DBSTATUS_CACHE_USED 1
    5822#define SQLITE_DBSTATUS_SCHEMA_USED 2
    5823#define SQLITE_DBSTATUS_STMT_USED 3
    5824#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
    5825#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
    5826#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
    5827#define SQLITE_DBSTATUS_MAX 6 /* Largest defined DBSTATUS */
    5154
    5155
    5156/*
    5157** CAPI3REF: Prepared Statement Status
    		5828
    5829
    5830/*
    5831** CAPI3REF: Prepared Statement Status
    5158** EXPERIMENTAL
    5159**
    5160** ^(Each prepared statement maintains various
    		5832**
    5833** ^(Each prepared statement maintains various
    5161** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
    		5834** [SQLITE_STMTSTATUS counters] that measure the number
    5162** of times it has performed specific operations.)^ These counters can
    5163** be used to monitor the performance characteristics of the prepared
    5164** statements. For example, if the number of table steps greatly exceeds
    5165** the number of table searches or result rows, that would tend to indicate
    5166** that the prepared statement is using a full table scan rather than
    		5835** of times it has performed specific operations.)^ These counters can
    5836** be used to monitor the performance characteristics of the prepared
    5837** statements. For example, if the number of table steps greatly exceeds
    5838** the number of table searches or result rows, that would tend to indicate
    5839** that the prepared statement is using a full table scan rather than
    5167** an index.
    		5840** an index.
    5168**
    5169** ^(This interface is used to retrieve and reset counter values from
    5170** a [prepared statement]. The first argument is the prepared statement
    5171** object to be interrogated. The second argument
    		5841**
    5842** ^(This interface is used to retrieve and reset counter values from
    5843** a [prepared statement]. The first argument is the prepared statement
    5844** object to be interrogated. The second argument
    5172** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
    		5845** is an integer code for a specific [SQLITE_STMTSTATUS counter]
    5173** to be interrogated.)^
    5174** ^The current value of the requested counter is returned.
    5175** ^If the resetFlg is true, then the counter is reset to zero after this
    5176** interface call returns.
    5177**
    5178** See also: [sqlite3_status()] and [sqlite3_db_status()].
    5179*/
    		5846** to be interrogated.)^
    5847** ^The current value of the requested counter is returned.
    5848** ^If the resetFlg is true, then the counter is reset to zero after this
    5849** interface call returns.
    5850**
    5851** See also: [sqlite3_status()] and [sqlite3_db_status()].
    5852*/
    5180SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
    		5853SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
    5181
    5182/*
    5183** CAPI3REF: Status Parameters for prepared statements
    		5854
    5855/*
    5856** CAPI3REF: Status Parameters for prepared statements
    5184** EXPERIMENTAL
    		5857** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
    5185**
    5186** These preprocessor macros define integer codes that name counter
    5187** values associated with the [sqlite3_stmt_status()] interface.
    5188** The meanings of the various counters are as follows:
    5189**
    5190** <dl>
    		5858**
    5859** These preprocessor macros define integer codes that name counter
    5860** values associated with the [sqlite3_stmt_status()] interface.
    5861** The meanings of the various counters are as follows:
    5862**
    5863** <dl>
    5191**
    SQLITE_STMTSTATUS_FULLSCAN_STEP

    		5864** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
    5192** <dd>^This is the number of times that SQLite has stepped forward in
    5193** a table as part of a full table scan. Large numbers for this counter
    		5865** <dd>^This is the number of times that SQLite has stepped forward in
    5866** a table as part of a full table scan. Large numbers for this counter
    5194** may indicate opportunities for performance improvement through
    		5867** may indicate opportunities for performance improvement through
    5195** careful use of indices.</dd>
    5196**
    		5868** careful use of indices.</dd>
    5869**
    5197**
    SQLITE_STMTSTATUS_SORT

    		5870** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
    5198** <dd>^This is the number of sort operations that have occurred.
    5199** A non-zero value in this counter may indicate an opportunity to
    5200** improvement performance through careful use of indices.</dd>
    5201**
    		5871** <dd>^This is the number of sort operations that have occurred.
    5872** A non-zero value in this counter may indicate an opportunity to
    5873** improvement performance through careful use of indices.</dd>
    5874**
    5875** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
    5876** <dd>^This is the number of rows inserted into transient indices that
    5877** were created automatically in order to help joins run faster.
    5878** A non-zero value in this counter may indicate an opportunity to
    5879** improvement performance by adding permanent indices that do not
    5880** need to be reinitialized each time the statement is run.</dd>
    5881**
    5202** </dl>
    5203*/
    5204#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
    5205#define SQLITE_STMTSTATUS_SORT 2
    		5882** </dl>
    5883*/
    5884#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
    5885#define SQLITE_STMTSTATUS_SORT 2
    5886#define SQLITE_STMTSTATUS_AUTOINDEX 3
    5206
    5207/*
    5208** CAPI3REF: Custom Page Cache Object
    		5887
    5888/*
    5889** CAPI3REF: Custom Page Cache Object
    5209** EXPERIMENTAL
    5210**
    5211** The sqlite3_pcache type is opaque. It is implemented by
    5212** the pluggable module. The SQLite core has no knowledge of
    5213** its size or internal structure and never deals with the
    5214** sqlite3_pcache object except by holding and passing pointers
    5215** to the object.
    5216**
    5217** See [sqlite3_pcache_methods] for additional information.
    5218*/
    5219typedef struct sqlite3_pcache sqlite3_pcache;
    5220
    5221/*
    5222** CAPI3REF: Application Defined Page Cache.
    5223** KEYWORDS: {page cache}
    		5890**
    5891** The sqlite3_pcache type is opaque. It is implemented by
    5892** the pluggable module. The SQLite core has no knowledge of
    5893** its size or internal structure and never deals with the
    5894** sqlite3_pcache object except by holding and passing pointers
    5895** to the object.
    5896**
    5897** See [sqlite3_pcache_methods] for additional information.
    5898*/
    5899typedef struct sqlite3_pcache sqlite3_pcache;
    5900
    5901/*
    5902** CAPI3REF: Application Defined Page Cache.
    5903** KEYWORDS: {page cache}
    5224** EXPERIMENTAL
    5225**
    5226** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
    		5904**
    5905** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
    5227** register an alternative page cache implementation by passing in an
    5228** instance of the sqlite3_pcache_methods structure.)^ The majority of the
    5229** heap memory used by SQLite is used by the page cache to cache data read
    5230** from, or ready to be written to, the database file. By implementing a
    5231** custom page cache using this API, an application can control more
    5232** precisely the amount of memory consumed by SQLite, the way in which
    5233** that memory is allocated and released, and the policies used to
    5234** determine exactly which parts of a database file are cached and for
    		5906** register an alternative page cache implementation by passing in an
    5907** instance of the sqlite3_pcache_methods structure.)^
    5908** In many applications, most of the heap memory allocated by
    5909** SQLite is used for the page cache.
    5910** By implementing a
    5911** custom page cache using this API, an application can better control
    5912** the amount of memory consumed by SQLite, the way in which
    5913** that memory is allocated and released, and the policies used to
    5914** determine exactly which parts of a database file are cached and for
    5235** how long.
    5236**
    		5915** how long.
    5916**
    5917** The alternative page cache mechanism is an
    5918** extreme measure that is only needed by the most demanding applications.
    5919** The built-in page cache is recommended for most uses.
    5920**
    5237** ^(The contents of the sqlite3_pcache_methods structure are copied to an
    5238** internal buffer by SQLite within the call to [sqlite3_config]. Hence
    5239** the application may discard the parameter after the call to
    5240** [sqlite3_config()] returns.)^
    5241**
    		5921** ^(The contents of the sqlite3_pcache_methods structure are copied to an
    5922** internal buffer by SQLite within the call to [sqlite3_config]. Hence
    5923** the application may discard the parameter after the call to
    5924** [sqlite3_config()] returns.)^
    5925**
    5242** ^The xInit() method is called once for each call to [sqlite3_initialize()]
    		5926** [[the xInit() page cache method]]
    5927** ^(The xInit() method is called once for each effective
    5928** call to [sqlite3_initialize()])^
    5243** (usually only once during the lifetime of the process). ^(The xInit()
    5244** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
    		5929** (usually only once during the lifetime of the process). ^(The xInit()
    5930** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
    5245** ^The xInit() method can set up up global structures and/or any mutexes
    5246** required by the custom page cache implementation.
    		5931** The intent of the xInit() method is to set up global data structures
    5932** required by the custom page cache implementation.
    5933** ^(If the xInit() method is NULL, then the
    5934** built-in default page cache is used instead of the application defined
    5935** page cache.)^
    5247**
    		5936**
    5248** ^The xShutdown() method is called from within [sqlite3_shutdown()],
    5249** if the application invokes this API. It can be used to clean up
    		5937** [[the xShutdown() page cache method]]
    5938** ^The xShutdown() method is called by [sqlite3_shutdown()].
    5939** It can be used to clean up
    5250** any outstanding resources before process shutdown, if required.
    		5940** any outstanding resources before process shutdown, if required.
    5941** ^The xShutdown() method may be NULL.
    5251**
    		5942**
    5252** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
    5253** the xInit method, so the xInit method need not be threadsafe. ^The
    		5943** ^SQLite automatically serializes calls to the xInit method,
    5944** so the xInit method need not be threadsafe. ^The
    5254** xShutdown method is only called from [sqlite3_shutdown()] so it does
    5255** not need to be threadsafe either. All other methods must be threadsafe
    5256** in multithreaded applications.
    5257**
    5258** ^SQLite will never invoke xInit() more than once without an intervening
    5259** call to xShutdown().
    5260**
    		5945** xShutdown method is only called from [sqlite3_shutdown()] so it does
    5946** not need to be threadsafe either. All other methods must be threadsafe
    5947** in multithreaded applications.
    5948**
    5949** ^SQLite will never invoke xInit() more than once without an intervening
    5950** call to xShutdown().
    5951**
    5261** ^The xCreate() method is used to construct a new cache instance. SQLite
    5262** will typically create one cache instance for each open database file,
    		5952** [[the xCreate() page cache methods]]
    5953** ^SQLite invokes the xCreate() method to construct a new cache instance.
    5954** SQLite will typically create one cache instance for each open database file,
    5263** though this is not guaranteed. ^The
    5264** first parameter, szPage, is the size in bytes of the pages that must
    5265** be allocated by the cache. ^szPage will not be a power of two. ^szPage
    5266** will the page size of the database file that is to be cached plus an
    		5955** though this is not guaranteed. ^The
    5956** first parameter, szPage, is the size in bytes of the pages that must
    5957** be allocated by the cache. ^szPage will not be a power of two. ^szPage
    5958** will the page size of the database file that is to be cached plus an
    5267** increment (here called "R") of about 100 or 200. ^SQLite will use the
    		5959** increment (here called "R") of less than 250. SQLite will use the
    5268** extra R bytes on each page to store metadata about the underlying
    5269** database page on disk. The value of R depends
    5270** on the SQLite version, the target platform, and how SQLite was compiled.
    		5960** extra R bytes on each page to store metadata about the underlying
    5961** database page on disk. The value of R depends
    5962** on the SQLite version, the target platform, and how SQLite was compiled.
    5271** ^R is constant for a particular build of SQLite. ^The second argument to
    		5963** ^(R is constant for a particular build of SQLite. Except, there are two
    5964** distinct values of R when SQLite is compiled with the proprietary
    5965** ZIPVFS extension.)^ ^The second argument to
    5272** xCreate(), bPurgeable, is true if the cache being created will
    5273** be used to cache database pages of a file stored on disk, or
    		5966** xCreate(), bPurgeable, is true if the cache being created will
    5967** be used to cache database pages of a file stored on disk, or
    5274** false if it is used for an in-memory database. ^The cache implementation
    		5968** false if it is used for an in-memory database. The cache implementation
    5275** does not have to do anything special based with the value of bPurgeable;
    5276** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
    5277** never invoke xUnpin() except to deliberately delete a page.
    		5969** does not have to do anything special based with the value of bPurgeable;
    5970** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
    5971** never invoke xUnpin() except to deliberately delete a page.
    5278** ^In other words, a cache created with bPurgeable set to false will
    		5972** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
    5973** false will always have the "discard" flag set to true.
    5974** ^Hence, a cache created with bPurgeable false will
    5279** never contain any unpinned pages.
    5280**
    		5975** never contain any unpinned pages.
    5976**
    5977** [[the xCachesize() page cache method]]
    5281** ^(The xCachesize() method may be called at any time by SQLite to set the
    5282** suggested maximum cache-size (number of pages stored by) the cache
    5283** instance passed as the first argument. This is the value configured using
    		5978** ^(The xCachesize() method may be called at any time by SQLite to set the
    5979** suggested maximum cache-size (number of pages stored by) the cache
    5980** instance passed as the first argument. This is the value configured using
    5284** the SQLite "[PRAGMA cache_size]" command.)^ ^As with the bPurgeable
    		5981** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
    5285** parameter, the implementation is not required to do anything with this
    5286** value; it is advisory only.
    5287**
    		5982** parameter, the implementation is not required to do anything with this
    5983** value; it is advisory only.
    5984**
    5288** ^The xPagecount() method should return the number of pages currently
    5289** stored in the cache.
    5290**
    5291** ^The xFetch() method is used to fetch a page and return a pointer to it.
    5292** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
    5293** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
    5294** mimimum key value is 1. After it has been retrieved using xFetch, the page
    		5985** [[the xPagecount() page cache methods]]
    5986** The xPagecount() method must return the number of pages currently
    5987** stored in the cache, both pinned and unpinned.
    5988**
    5989** [[the xFetch() page cache methods]]
    5990** The xFetch() method locates a page in the cache and returns a pointer to
    5991** the page, or a NULL pointer.
    5992** A "page", in this context, means a buffer of szPage bytes aligned at an
    5993** 8-byte boundary. The page to be fetched is determined by the key. ^The
    5994** minimum key value is 1. After it has been retrieved using xFetch, the page
    5295** is considered to be "pinned".
    5296**
    		5995** is considered to be "pinned".
    5996**
    5297** ^If the requested page is already in the page cache, then the page cache
    		5997** If the requested page is already in the page cache, then the page cache
    5298** implementation must return a pointer to the page buffer with its content
    		5998** implementation must return a pointer to the page buffer with its content
    5299** intact. ^(If the requested page is not already in the cache, then the
    5300** behavior of the cache implementation is determined by the value of the
    5301** createFlag parameter passed to xFetch, according to the following table:
    		5999** intact. If the requested page is not already in the cache, then the
    6000** cache implementation should use the value of the createFlag
    6001** parameter to help it determined what action to take:
    5302**
    5303** <table border=1 width=85% align=center>
    5304** <tr><th> createFlag <th> Behaviour when page is not already in cache
    5305** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
    5306** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
    5307** Otherwise return NULL.
    5308** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
    5309** NULL if allocating a new page is effectively impossible.
    		6002**
    6003** <table border=1 width=85% align=center>
    6004** <tr><th> createFlag <th> Behaviour when page is not already in cache
    6005** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
    6006** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
    6007** Otherwise return NULL.
    6008** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
    6009** NULL if allocating a new page is effectively impossible.
    5310** </table>)^
    		6010**

    5311**
    6011**
    5312** SQLite will normally invoke xFetch() with a createFlag of 0 or 1. If
    5313** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
    6012** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
    6013** will only use a createFlag of 2 after a prior call with a createFlag of 1
    6014** failed.)^ In between the to xFetch() calls, SQLite may
    5314** attempt to unpin one or more cache pages by spilling the content of
    6015** attempt to unpin one or more cache pages by spilling the content of
    5315** pinned pages to disk and synching the operating system disk cache. After
    5316** attempting to unpin pages, the xFetch() method will be invoked again with
    5317** a createFlag of 2.
    6016** pinned pages to disk and synching the operating system disk cache.
    5318**
    6017**
    6018** [[the xUnpin() page cache method]]
    5319** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
    6019** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
    5320** as its second argument. ^(If the third parameter, discard, is non-zero,
    5321** then the page should be evicted from the cache. In this case SQLite
    5322** assumes that the next time the page is retrieved from the cache using
    5323** the xFetch() method, it will be zeroed.)^ ^If the discard parameter is
    5324** zero, then the page is considered to be unpinned. ^The cache implementation
    6020** as its second argument. If the third parameter, discard, is non-zero,
    6021** then the page must be evicted from the cache.
    6022** ^If the discard parameter is
    6023** zero, then the page may be discarded or retained at the discretion of
    6024** page cache implementation. ^The page cache implementation
    5325** may choose to evict unpinned pages at any time.
    5326**
    6025** may choose to evict unpinned pages at any time.
    6026**
    5327** ^(The cache is not required to perform any reference counting. A single
    5328** call to xUnpin() unpins the page regardless of the number of prior calls
    5329** to xFetch().)^
    6027** The cache must not perform any reference counting. A single
    6028** call to xUnpin() unpins the page regardless of the number of prior calls
    6029** to xFetch().
    5330**
    6030**
    5331** ^The xRekey() method is used to change the key value associated with the
    5332** page passed as the second argument from oldKey to newKey. ^If the cache
    5333** previously contains an entry associated with newKey, it should be
    6031** [[the xRekey() page cache methods]]
    6032** The xRekey() method is used to change the key value associated with the
    6033** page passed as the second argument. If the cache
    6034** previously contains an entry associated with newKey, it must be
    5334** discarded. ^Any prior cache entry associated with newKey is guaranteed not
    5335** to be pinned.
    5336**
    6035** discarded. ^Any prior cache entry associated with newKey is guaranteed not
    6036** to be pinned.
    6037**
    5337** ^When SQLite calls the xTruncate() method, the cache must discard all
    6038** When SQLite calls the xTruncate() method, the cache must discard all
    5338** existing cache entries with page numbers (keys) greater than or equal
    6039** existing cache entries with page numbers (keys) greater than or equal
    5339** to the value of the iLimit parameter passed to xTruncate(). ^If any
    6040** to the value of the iLimit parameter passed to xTruncate(). If any
    5340** of these pages are pinned, they are implicitly unpinned, meaning that
    5341** they can be safely discarded.
    5342**
    6041** of these pages are pinned, they are implicitly unpinned, meaning that
    6042** they can be safely discarded.
    6043**
    6044** [[the xDestroy() page cache method]]
    5343** ^The xDestroy() method is used to delete a cache allocated by xCreate().
    5344** All resources associated with the specified cache should be freed. ^After
    5345** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
    5346** handle invalid, and will not use it with any other sqlite3_pcache_methods
    5347** functions.
    5348*/
    5349typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
    5350struct sqlite3_pcache_methods {

    --- 7 unchanged lines hidden (view full) ---

    5358 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
    5359 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
    5360 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
    5361 void (*xDestroy)(sqlite3_pcache*);
    5362};
    5363
    5364/*
    5365** CAPI3REF: Online Backup Object
    6045** ^The xDestroy() method is used to delete a cache allocated by xCreate().
    6046** All resources associated with the specified cache should be freed. ^After
    6047** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
    6048** handle invalid, and will not use it with any other sqlite3_pcache_methods
    6049** functions.
    6050*/
    6051typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
    6052struct sqlite3_pcache_methods {

    --- 7 unchanged lines hidden (view full) ---

    6060 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
    6061 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
    6062 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
    6063 void (*xDestroy)(sqlite3_pcache*);
    6064};
    6065
    6066/*
    6067** CAPI3REF: Online Backup Object
    5366** EXPERIMENTAL
    5367**
    5368** The sqlite3_backup object records state information about an ongoing
    5369** online backup operation. ^The sqlite3_backup object is created by
    5370** a call to [sqlite3_backup_init()] and is destroyed by a call to
    5371** [sqlite3_backup_finish()].
    5372**
    5373** See Also: [Using the SQLite Online Backup API]
    5374*/
    5375typedef struct sqlite3_backup sqlite3_backup;
    5376
    5377/*
    5378** CAPI3REF: Online Backup API.
    6068**
    6069** The sqlite3_backup object records state information about an ongoing
    6070** online backup operation. ^The sqlite3_backup object is created by
    6071** a call to [sqlite3_backup_init()] and is destroyed by a call to
    6072** [sqlite3_backup_finish()].
    6073**
    6074** See Also: [Using the SQLite Online Backup API]
    6075*/
    6076typedef struct sqlite3_backup sqlite3_backup;
    6077
    6078/*
    6079** CAPI3REF: Online Backup API.
    5379** EXPERIMENTAL
    5380**
    5381** The backup API copies the content of one database into another.
    5382** It is useful either for creating backups of databases or
    6080**
    6081** The backup API copies the content of one database into another.
    6082** It is useful either for creating backups of databases or
    5383** for copying in-memory databases to or from persistent files.
    6083** for copying in-memory databases to or from persistent files.
    5384**
    5385** See Also: [Using the SQLite Online Backup API]
    5386**
    6084**
    6085** See Also: [Using the SQLite Online Backup API]
    6086**
    5387** ^Exclusive access is required to the destination database for the
    5388** duration of the operation. ^However the source database is only
    5389** read-locked while it is actually being read; it is not locked
    5390** continuously for the entire backup operation. ^Thus, the backup may be
    5391** performed on a live source database without preventing other users from
    6087** ^SQLite holds a write transaction open on the destination database file
    6088** for the duration of the backup operation.
    6089** ^The source database is read-locked only while it is being read;
    6090** it is not locked continuously for the entire backup operation.
    6091** ^Thus, the backup may be performed on a live source database without
    6092** preventing other database connections from
    5392** reading or writing to the source database while the backup is underway.
    6093** reading or writing to the source database while the backup is underway.
    5393**
    5394** ^(To perform a backup operation:
    6094**
    6095** ^(To perform a backup operation:
    5395** <ol>
    5396** <li><b>sqlite3_backup_init()</b> is called once to initialize the
    6096** <ol>
    6097** <li><b>sqlite3_backup_init()</b> is called once to initialize the
    5397** backup,
    5398**
  • sqlite3_backup_step() is called one or more times to transfer
    6098** backup,
    6099** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
    5399** the data between the two databases, and finally
    6100** the data between the two databases, and finally
    5400**
  • sqlite3_backup_finish() is called to release all resources
    5401** associated with the backup operation.
    6101** <li><b>sqlite3_backup_finish()</b> is called to release all resources
    6102** associated with the backup operation.
    5402** </ol>)^
    5403** There should be exactly one call to sqlite3_backup_finish() for each
    5404** successful call to sqlite3_backup_init().
    5405**
    6103** </ol>)^
    6104** There should be exactly one call to sqlite3_backup_finish() for each
    6105** successful call to sqlite3_backup_init().
    6106**
    5406** sqlite3_backup_init()
    6107** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
    5407**
    6108**
    5408** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
    5409** [database connection] associated with the destination database
    6109** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
    6110** [database connection] associated with the destination database
    5410** and the database name, respectively.
    5411** ^The database name is "main" for the main database, "temp" for the
    5412** temporary database, or the name specified after the AS keyword in
    5413** an [ATTACH] statement for an attached database.
    6111** and the database name, respectively.
    6112** ^The database name is "main" for the main database, "temp" for the
    6113** temporary database, or the name specified after the AS keyword in
    6114** an [ATTACH] statement for an attached database.
    5414** ^The S and M arguments passed to
    6115** ^The S and M arguments passed to
    5415** sqlite3_backup_init(D,N,S,M) identify the [database connection]
    5416** and database name of the source database, respectively.
    5417** ^The source and destination [database connections] (parameters S and D)
    6116** sqlite3_backup_init(D,N,S,M) identify the [database connection]
    6117** and database name of the source database, respectively.
    6118** ^The source and destination [database connections] (parameters S and D)
    5418** must be different or else sqlite3_backup_init(D,N,S,M) will file with
    6119** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
    5419** an error.
    5420**
    5421** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
    6120** an error.
    6121**
    6122** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
    5422** returned and an error code and error message are store3d in the
    6123** returned and an error code and error message are stored in the
    5423** destination [database connection] D.
    5424** ^The error code and message for the failed call to sqlite3_backup_init()
    5425** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
    5426** [sqlite3_errmsg16()] functions.
    5427** ^A successful call to sqlite3_backup_init() returns a pointer to an
    5428** [sqlite3_backup] object.
    5429** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
    6124** destination [database connection] D.
    6125** ^The error code and message for the failed call to sqlite3_backup_init()
    6126** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
    6127** [sqlite3_errmsg16()] functions.
    6128** ^A successful call to sqlite3_backup_init() returns a pointer to an
    6129** [sqlite3_backup] object.
    6130** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
    5430** sqlite3_backup_finish() functions to perform the specified backup
    6131** sqlite3_backup_finish() functions to perform the specified backup
    5431** operation.
    5432**
    6132** operation.
    6133**
    5433** sqlite3_backup_step()
    6134** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
    5434**
    6135**
    5435** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
    6136** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
    5436** the source and destination databases specified by [sqlite3_backup] object B.
    6137** the source and destination databases specified by [sqlite3_backup] object B.
    5437** ^If N is negative, all remaining source pages are copied.
    6138** ^If N is negative, all remaining source pages are copied.
    5438** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
    6139** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
    5439** are still more pages to be copied, then the function resturns [SQLITE_OK].
    6140** are still more pages to be copied, then the function returns [SQLITE_OK].
    5440** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
    5441** from source to destination, then it returns [SQLITE_DONE].
    5442** ^If an error occurs while running sqlite3_backup_step(B,N),
    5443** then an [error code] is returned. ^As well as [SQLITE_OK] and
    5444** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
    5445** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
    5446** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
    5447**
    6141** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
    6142** from source to destination, then it returns [SQLITE_DONE].
    6143** ^If an error occurs while running sqlite3_backup_step(B,N),
    6144** then an [error code] is returned. ^As well as [SQLITE_OK] and
    6145** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
    6146** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
    6147** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
    6148**
    5448** ^The sqlite3_backup_step() might return [SQLITE_READONLY] if the destination
    5449** database was opened read-only or if
    5450** the destination is an in-memory database with a different page size
    5451** from the source database.
    6149** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
    6150** <ol>
    6151** <li> the destination database was opened read-only, or
    6152** <li> the destination database is using write-ahead-log journaling
    6153** and the destination and source page sizes differ, or
    6154** <li> the destination database is an in-memory database and the
    6155** destination and source page sizes differ.
    6156** </ol>)^
    5452**
    5453** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
    5454** the [sqlite3_busy_handler | busy-handler function]
    6157**
    6158** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
    6159** the [sqlite3_busy_handler | busy-handler function]
    5455** is invoked (if one is specified). ^If the
    5456** busy-handler returns non-zero before the lock is available, then
    6160** is invoked (if one is specified). ^If the
    6161** busy-handler returns non-zero before the lock is available, then
    5457** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
    5458** sqlite3_backup_step() can be retried later. ^If the source
    5459** [database connection]
    5460** is being used to write to the source database when sqlite3_backup_step()
    5461** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
    5462** case the call to sqlite3_backup_step() can be retried later on. ^(If
    5463** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
    6162** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
    6163** sqlite3_backup_step() can be retried later. ^If the source
    6164** [database connection]
    6165** is being used to write to the source database when sqlite3_backup_step()
    6166** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
    6167** case the call to sqlite3_backup_step() can be retried later on. ^(If
    6168** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
    5464** [SQLITE_READONLY] is returned, then
    5465** there is no point in retrying the call to sqlite3_backup_step(). These
    5466** errors are considered fatal.)^ The application must accept
    5467** that the backup operation has failed and pass the backup operation handle
    6169** [SQLITE_READONLY] is returned, then
    6170** there is no point in retrying the call to sqlite3_backup_step(). These
    6171** errors are considered fatal.)^ The application must accept
    6172** that the backup operation has failed and pass the backup operation handle
    5468** to the sqlite3_backup_finish() to release associated resources.
    5469**
    5470** ^The first call to sqlite3_backup_step() obtains an exclusive lock
    6173** to the sqlite3_backup_finish() to release associated resources.
    6174**
    6175** ^The first call to sqlite3_backup_step() obtains an exclusive lock
    5471** on the destination file. ^The exclusive lock is not released until either
    5472** sqlite3_backup_finish() is called or the backup operation is complete
    6176** on the destination file. ^The exclusive lock is not released until either
    6177** sqlite3_backup_finish() is called or the backup operation is complete
    5473** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
    5474** sqlite3_backup_step() obtains a [shared lock] on the source database that
    5475** lasts for the duration of the sqlite3_backup_step() call.
    5476** ^Because the source database is not locked between calls to
    5477** sqlite3_backup_step(), the source database may be modified mid-way
    5478** through the backup process. ^If the source database is modified by an
    5479** external process or via a database connection other than the one being
    5480** used by the backup operation, then the backup will be automatically
    6178** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
    6179** sqlite3_backup_step() obtains a [shared lock] on the source database that
    6180** lasts for the duration of the sqlite3_backup_step() call.
    6181** ^Because the source database is not locked between calls to
    6182** sqlite3_backup_step(), the source database may be modified mid-way
    6183** through the backup process. ^If the source database is modified by an
    6184** external process or via a database connection other than the one being
    6185** used by the backup operation, then the backup will be automatically
    5481** restarted by the next call to sqlite3_backup_step(). ^If the source
    6186** restarted by the next call to sqlite3_backup_step(). ^If the source
    5482** database is modified by the using the same database connection as is used
    5483** by the backup operation, then the backup database is automatically
    5484** updated at the same time.
    5485**
    6187** database is modified by the using the same database connection as is used
    6188** by the backup operation, then the backup database is automatically
    6189** updated at the same time.
    6190**
    5486** sqlite3_backup_finish()
    6191** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
    5487**
    6192**
    5488** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
    6193** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
    5489** application wishes to abandon the backup operation, the application
    5490** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
    5491** ^The sqlite3_backup_finish() interfaces releases all
    6194** application wishes to abandon the backup operation, the application
    6195** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
    6196** ^The sqlite3_backup_finish() interfaces releases all
    5492** resources associated with the [sqlite3_backup] object.
    6197** resources associated with the [sqlite3_backup] object.
    5493** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
    5494** active write-transaction on the destination database is rolled back.
    5495** The [sqlite3_backup] object is invalid
    5496** and may not be used following a call to sqlite3_backup_finish().
    5497**
    5498** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
    5499** sqlite3_backup_step() errors occurred, regardless or whether or not
    5500** sqlite3_backup_step() completed.
    5501** ^If an out-of-memory condition or IO error occurred during any prior
    5502** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
    5503** sqlite3_backup_finish() returns the corresponding [error code].
    5504**
    5505** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
    5506** is not a permanent error and does not affect the return value of
    5507** sqlite3_backup_finish().
    5508**
    6198** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
    6199** active write-transaction on the destination database is rolled back.
    6200** The [sqlite3_backup] object is invalid
    6201** and may not be used following a call to sqlite3_backup_finish().
    6202**
    6203** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
    6204** sqlite3_backup_step() errors occurred, regardless or whether or not
    6205** sqlite3_backup_step() completed.
    6206** ^If an out-of-memory condition or IO error occurred during any prior
    6207** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
    6208** sqlite3_backup_finish() returns the corresponding [error code].
    6209**
    6210** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
    6211** is not a permanent error and does not affect the return value of
    6212** sqlite3_backup_finish().
    6213**
    5509** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
    6214** [[sqlite3_backup__remaining()]] [[sqlite3_backup_pagecount()]]
    6215** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
    5510**
    5511** ^Each call to sqlite3_backup_step() sets two values inside
    5512** the [sqlite3_backup] object: the number of pages still to be backed
    6216**
    6217** ^Each call to sqlite3_backup_step() sets two values inside
    6218** the [sqlite3_backup] object: the number of pages still to be backed
    5513** up and the total number of pages in the source databae file.
    6219** up and the total number of pages in the source database file.
    5514** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
    5515** retrieve these two values, respectively.
    5516**
    5517** ^The values returned by these functions are only updated by
    5518** sqlite3_backup_step(). ^If the source database is modified during a backup
    5519** operation, then the values are not updated to account for any extra
    5520** pages that need to be updated or the size of the source database file
    5521** changing.
    5522**
    5523** <b>Concurrent Usage of Database Handles</b>
    5524**
    5525** ^The source [database connection] may be used by the application for other
    5526** purposes while a backup operation is underway or being initialized.
    5527** ^If SQLite is compiled and configured to support threadsafe database
    5528** connections, then the source database connection may be used concurrently
    5529** from within other threads.
    5530**
    6220** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
    6221** retrieve these two values, respectively.
    6222**
    6223** ^The values returned by these functions are only updated by
    6224** sqlite3_backup_step(). ^If the source database is modified during a backup
    6225** operation, then the values are not updated to account for any extra
    6226** pages that need to be updated or the size of the source database file
    6227** changing.
    6228**
    6229** <b>Concurrent Usage of Database Handles</b>
    6230**
    6231** ^The source [database connection] may be used by the application for other
    6232** purposes while a backup operation is underway or being initialized.
    6233** ^If SQLite is compiled and configured to support threadsafe database
    6234** connections, then the source database connection may be used concurrently
    6235** from within other threads.
    6236**
    5531** However, the application must guarantee that the destination
    5532** [database connection] is not passed to any other API (by any thread) after
    6237** However, the application must guarantee that the destination
    6238** [database connection] is not passed to any other API (by any thread) after
    5533** sqlite3_backup_init() is called and before the corresponding call to
    5534** sqlite3_backup_finish(). SQLite does not currently check to see
    5535** if the application incorrectly accesses the destination [database connection]
    5536** and so no error code is reported, but the operations may malfunction
    5537** nevertheless. Use of the destination database connection while a
    5538** backup is in progress might also also cause a mutex deadlock.
    5539**
    5540** If running in [shared cache mode], the application must
    5541** guarantee that the shared cache used by the destination database
    5542** is not accessed while the backup is running. In practice this means
    6239** sqlite3_backup_init() is called and before the corresponding call to
    6240** sqlite3_backup_finish(). SQLite does not currently check to see
    6241** if the application incorrectly accesses the destination [database connection]
    6242** and so no error code is reported, but the operations may malfunction
    6243** nevertheless. Use of the destination database connection while a
    6244** backup is in progress might also also cause a mutex deadlock.
    6245**
    6246** If running in [shared cache mode], the application must
    6247** guarantee that the shared cache used by the destination database
    6248** is not accessed while the backup is running. In practice this means
    5543** that the application must guarantee that the disk file being
    6249** that the application must guarantee that the disk file being
    5544** backed up to is not accessed by any connection within the process,
    5545** not just the specific connection that was passed to sqlite3_backup_init().
    5546**
    6250** backed up to is not accessed by any connection within the process,
    6251** not just the specific connection that was passed to sqlite3_backup_init().
    6252**
    5547** The [sqlite3_backup] object itself is partially threadsafe. Multiple
    6253** The [sqlite3_backup] object itself is partially threadsafe. Multiple
    5548** threads may safely make multiple concurrent calls to sqlite3_backup_step().
    5549** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
    5550** APIs are not strictly speaking threadsafe. If they are invoked at the
    5551** same time as another thread is invoking sqlite3_backup_step() it is
    5552** possible that they return invalid values.
    5553*/
    5554SQLITE_API sqlite3_backup *sqlite3_backup_init(
    5555 sqlite3 *pDest, /* Destination database handle */
    5556 const char *zDestName, /* Destination database name */
    5557 sqlite3 *pSource, /* Source database handle */
    5558 const char *zSourceName /* Source database name */
    5559);
    5560SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
    5561SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
    5562SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
    5563SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
    5564
    5565/*
    5566** CAPI3REF: Unlock Notification
    6254** threads may safely make multiple concurrent calls to sqlite3_backup_step().
    6255** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
    6256** APIs are not strictly speaking threadsafe. If they are invoked at the
    6257** same time as another thread is invoking sqlite3_backup_step() it is
    6258** possible that they return invalid values.
    6259*/
    6260SQLITE_API sqlite3_backup *sqlite3_backup_init(
    6261 sqlite3 *pDest, /* Destination database handle */
    6262 const char *zDestName, /* Destination database name */
    6263 sqlite3 *pSource, /* Source database handle */
    6264 const char *zSourceName /* Source database name */
    6265);
    6266SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
    6267SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
    6268SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
    6269SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
    6270
    6271/*
    6272** CAPI3REF: Unlock Notification
    5567** EXPERIMENTAL
    5568**
    5569** ^When running in shared-cache mode, a database operation may fail with
    5570** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
    5571** individual tables within the shared-cache cannot be obtained. See
    6273**
    6274** ^When running in shared-cache mode, a database operation may fail with
    6275** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
    6276** individual tables within the shared-cache cannot be obtained. See
    5572** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
    5573** ^This API may be used to register a callback that SQLite will invoke
    6277** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
    6278** ^This API may be used to register a callback that SQLite will invoke
    5574** when the connection currently holding the required lock relinquishes it.
    5575** ^This API is only available if the library was compiled with the
    5576** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
    5577**
    5578** See Also: [Using the SQLite Unlock Notification Feature].
    5579**
    5580** ^Shared-cache locks are released when a database connection concludes
    6279** when the connection currently holding the required lock relinquishes it.
    6280** ^This API is only available if the library was compiled with the
    6281** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
    6282**
    6283** See Also: [Using the SQLite Unlock Notification Feature].
    6284**
    6285** ^Shared-cache locks are released when a database connection concludes
    5581** its current transaction, either by committing it or rolling it back.
    6286** its current transaction, either by committing it or rolling it back.
    5582**
    5583** ^When a connection (known as the blocked connection) fails to obtain a
    5584** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
    5585** identity of the database connection (the blocking connection) that
    6287**
    6288** ^When a connection (known as the blocked connection) fails to obtain a
    6289** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
    6290** identity of the database connection (the blocking connection) that
    5586** has locked the required resource is stored internally. ^After an
    6291** has locked the required resource is stored internally. ^After an
    5587** application receives an SQLITE_LOCKED error, it may call the
    6292** application receives an SQLITE_LOCKED error, it may call the
    5588** sqlite3_unlock_notify() method with the blocked connection handle as
    6293** sqlite3_unlock_notify() method with the blocked connection handle as
    5589** the first argument to register for a callback that will be invoked
    5590** when the blocking connections current transaction is concluded. ^The
    5591** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
    5592** call that concludes the blocking connections transaction.
    5593**
    5594** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
    5595** there is a chance that the blocking connection will have already
    5596** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
    5597** If this happens, then the specified callback is invoked immediately,
    5598** from within the call to sqlite3_unlock_notify().)^
    5599**
    5600** ^If the blocked connection is attempting to obtain a write-lock on a
    5601** shared-cache table, and more than one other connection currently holds
    6294** the first argument to register for a callback that will be invoked
    6295** when the blocking connections current transaction is concluded. ^The
    6296** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
    6297** call that concludes the blocking connections transaction.
    6298**
    6299** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
    6300** there is a chance that the blocking connection will have already
    6301** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
    6302** If this happens, then the specified callback is invoked immediately,
    6303** from within the call to sqlite3_unlock_notify().)^
    6304**
    6305** ^If the blocked connection is attempting to obtain a write-lock on a
    6306** shared-cache table, and more than one other connection currently holds
    5602** a read-lock on the same table, then SQLite arbitrarily selects one of
    6307** a read-lock on the same table, then SQLite arbitrarily selects one of
    5603** the other connections to use as the blocking connection.
    5604**
    6308** the other connections to use as the blocking connection.
    6309**
    5605** ^(There may be at most one unlock-notify callback registered by a
    6310** ^(There may be at most one unlock-notify callback registered by a
    5606** blocked connection. If sqlite3_unlock_notify() is called when the
    5607** blocked connection already has a registered unlock-notify callback,
    5608** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
    5609** called with a NULL pointer as its second argument, then any existing
    6311** blocked connection. If sqlite3_unlock_notify() is called when the
    6312** blocked connection already has a registered unlock-notify callback,
    6313** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
    6314** called with a NULL pointer as its second argument, then any existing
    5610** unlock-notify callback is cancelled. ^The blocked connections
    6315** unlock-notify callback is canceled. ^The blocked connections
    5611** unlock-notify callback may also be canceled by closing the blocked
    5612** connection using [sqlite3_close()].
    5613**
    5614** The unlock-notify callback is not reentrant. If an application invokes
    5615** any sqlite3_xxx API functions from within an unlock-notify callback, a
    5616** crash or deadlock may be the result.
    5617**
    5618** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
    5619** returns SQLITE_OK.
    5620**
    5621** <b>Callback Invocation Details</b>
    5622**
    6316** unlock-notify callback may also be canceled by closing the blocked
    6317** connection using [sqlite3_close()].
    6318**
    6319** The unlock-notify callback is not reentrant. If an application invokes
    6320** any sqlite3_xxx API functions from within an unlock-notify callback, a
    6321** crash or deadlock may be the result.
    6322**
    6323** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
    6324** returns SQLITE_OK.
    6325**
    6326** <b>Callback Invocation Details</b>
    6327**
    5623** When an unlock-notify callback is registered, the application provides a
    6328** When an unlock-notify callback is registered, the application provides a
    5624** single void* pointer that is passed to the callback when it is invoked.
    5625** However, the signature of the callback function allows SQLite to pass
    5626** it an array of void* context pointers. The first argument passed to
    5627** an unlock-notify callback is a pointer to an array of void* pointers,
    5628** and the second is the number of entries in the array.
    5629**
    5630** When a blocking connections transaction is concluded, there may be
    5631** more than one blocked connection that has registered for an unlock-notify
    5632** callback. ^If two or more such blocked connections have specified the
    5633** same callback function, then instead of invoking the callback function
    5634** multiple times, it is invoked once with the set of void* context pointers
    5635** specified by the blocked connections bundled together into an array.
    6329** single void* pointer that is passed to the callback when it is invoked.
    6330** However, the signature of the callback function allows SQLite to pass
    6331** it an array of void* context pointers. The first argument passed to
    6332** an unlock-notify callback is a pointer to an array of void* pointers,
    6333** and the second is the number of entries in the array.
    6334**
    6335** When a blocking connections transaction is concluded, there may be
    6336** more than one blocked connection that has registered for an unlock-notify
    6337** callback. ^If two or more such blocked connections have specified the
    6338** same callback function, then instead of invoking the callback function
    6339** multiple times, it is invoked once with the set of void* context pointers
    6340** specified by the blocked connections bundled together into an array.
    5636** This gives the application an opportunity to prioritize any actions
    6341** This gives the application an opportunity to prioritize any actions
    5637** related to the set of unblocked database connections.
    5638**
    5639** <b>Deadlock Detection</b>
    5640**
    6342** related to the set of unblocked database connections.
    6343**
    6344** <b>Deadlock Detection</b>
    6345**
    5641** Assuming that after registering for an unlock-notify callback a
    6346** Assuming that after registering for an unlock-notify callback a
    5642** database waits for the callback to be issued before taking any further
    5643** action (a reasonable assumption), then using this API may cause the
    5644** application to deadlock. For example, if connection X is waiting for
    5645** connection Y's transaction to be concluded, and similarly connection
    5646** Y is waiting on connection X's transaction, then neither connection
    5647** will proceed and the system may remain deadlocked indefinitely.
    5648**
    5649** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock

    --- 6 unchanged lines hidden (view full) ---

    5656** A's transaction is concluded. ^Indirect deadlock is also detected, so
    5657** the system is also considered to be deadlocked if connection B has
    5658** registered for an unlock-notify callback on the conclusion of connection
    5659** C's transaction, where connection C is waiting on connection A. ^Any
    5660** number of levels of indirection are allowed.
    5661**
    5662** <b>The "DROP TABLE" Exception</b>
    5663**
    6347** database waits for the callback to be issued before taking any further
    6348** action (a reasonable assumption), then using this API may cause the
    6349** application to deadlock. For example, if connection X is waiting for
    6350** connection Y's transaction to be concluded, and similarly connection
    6351** Y is waiting on connection X's transaction, then neither connection
    6352** will proceed and the system may remain deadlocked indefinitely.
    6353**
    6354** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock

    --- 6 unchanged lines hidden (view full) ---

    6361** A's transaction is concluded. ^Indirect deadlock is also detected, so
    6362** the system is also considered to be deadlocked if connection B has
    6363** registered for an unlock-notify callback on the conclusion of connection
    6364** C's transaction, where connection C is waiting on connection A. ^Any
    6365** number of levels of indirection are allowed.
    6366**
    6367** <b>The "DROP TABLE" Exception</b>
    6368**
    5664** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
    6369** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
    5665** always appropriate to call sqlite3_unlock_notify(). There is however,
    5666** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
    5667** SQLite checks if there are any currently executing SELECT statements
    5668** that belong to the same connection. If there are, SQLITE_LOCKED is
    5669** returned. In this case there is no "blocking connection", so invoking
    5670** sqlite3_unlock_notify() results in the unlock-notify callback being
    5671** invoked immediately. If the application then re-attempts the "DROP TABLE"
    5672** or "DROP INDEX" query, an infinite loop might be the result.
    5673**
    5674** One way around this problem is to check the extended error code returned
    5675** by an sqlite3_step() call. ^(If there is a blocking connection, then the
    5676** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
    6370** always appropriate to call sqlite3_unlock_notify(). There is however,
    6371** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
    6372** SQLite checks if there are any currently executing SELECT statements
    6373** that belong to the same connection. If there are, SQLITE_LOCKED is
    6374** returned. In this case there is no "blocking connection", so invoking
    6375** sqlite3_unlock_notify() results in the unlock-notify callback being
    6376** invoked immediately. If the application then re-attempts the "DROP TABLE"
    6377** or "DROP INDEX" query, an infinite loop might be the result.
    6378**
    6379** One way around this problem is to check the extended error code returned
    6380** by an sqlite3_step() call. ^(If there is a blocking connection, then the
    6381** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
    5677** the special "DROP TABLE/INDEX" case, the extended error code is just
    6382** the special "DROP TABLE/INDEX" case, the extended error code is just
    5678** SQLITE_LOCKED.)^
    5679*/
    5680SQLITE_API int sqlite3_unlock_notify(
    5681 sqlite3 *pBlocked, /* Waiting connection */
    5682 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
    5683 void *pNotifyArg /* Argument to pass to xNotify */
    5684);
    5685
    5686
    5687/*
    5688** CAPI3REF: String Comparison
    6383** SQLITE_LOCKED.)^
    6384*/
    6385SQLITE_API int sqlite3_unlock_notify(
    6386 sqlite3 *pBlocked, /* Waiting connection */
    6387 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
    6388 void *pNotifyArg /* Argument to pass to xNotify */
    6389);
    6390
    6391
    6392/*
    6393** CAPI3REF: String Comparison
    5689** EXPERIMENTAL
    5690**
    5691** ^The [sqlite3_strnicmp()] API allows applications and extensions to
    5692** compare the contents of two buffers containing UTF-8 strings in a
    6394**
    6395** ^The [sqlite3_strnicmp()] API allows applications and extensions to
    6396** compare the contents of two buffers containing UTF-8 strings in a
    5693** case-indendent fashion, using the same definition of case independence
    6397** case-independent fashion, using the same definition of case independence
    5694** that SQLite uses internally when comparing identifiers.
    5695*/
    5696SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
    5697
    5698/*
    5699** CAPI3REF: Error Logging Interface
    6398** that SQLite uses internally when comparing identifiers.
    6399*/
    6400SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
    6401
    6402/*
    6403** CAPI3REF: Error Logging Interface
    5700** EXPERIMENTAL
    5701**
    5702** ^The [sqlite3_log()] interface writes a message into the error log
    5703** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
    5704** ^If logging is enabled, the zFormat string and subsequent arguments are
    6404**
    6405** ^The [sqlite3_log()] interface writes a message into the error log
    6406** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
    6407** ^If logging is enabled, the zFormat string and subsequent arguments are
    5705** passed through to [sqlite3_vmprintf()] to generate the final output string.
    6408** used with [sqlite3_snprintf()] to generate the final output string.
    5706**
    5707** The sqlite3_log() interface is intended for use by extensions such as
    5708** virtual tables, collating functions, and SQL functions. While there is
    5709** nothing to prevent an application from calling sqlite3_log(), doing so
    5710** is considered bad form.
    5711**
    5712** The zFormat string must not be NULL.
    5713**
    5714** To avoid deadlocks and other threading problems, the sqlite3_log() routine
    5715** will not use dynamically allocated memory. The log message is stored in
    5716** a fixed-length buffer on the stack. If the log message is longer than
    5717** a few hundred characters, it will be truncated to the length of the
    5718** buffer.
    5719*/
    5720SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
    5721
    5722/*
    6409**
    6410** The sqlite3_log() interface is intended for use by extensions such as
    6411** virtual tables, collating functions, and SQL functions. While there is
    6412** nothing to prevent an application from calling sqlite3_log(), doing so
    6413** is considered bad form.
    6414**
    6415** The zFormat string must not be NULL.
    6416**
    6417** To avoid deadlocks and other threading problems, the sqlite3_log() routine
    6418** will not use dynamically allocated memory. The log message is stored in
    6419** a fixed-length buffer on the stack. If the log message is longer than
    6420** a few hundred characters, it will be truncated to the length of the
    6421** buffer.
    6422*/
    6423SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
    6424
    6425/*
    6426** CAPI3REF: Write-Ahead Log Commit Hook
    6427**
    6428** ^The [sqlite3_wal_hook()] function is used to register a callback that
    6429** will be invoked each time a database connection commits data to a
    6430** [write-ahead log] (i.e. whenever a transaction is committed in
    6431** [journal_mode | journal_mode=WAL mode]).
    6432**
    6433** ^The callback is invoked by SQLite after the commit has taken place and
    6434** the associated write-lock on the database released, so the implementation
    6435** may read, write or [checkpoint] the database as required.
    6436**
    6437** ^The first parameter passed to the callback function when it is invoked
    6438** is a copy of the third parameter passed to sqlite3_wal_hook() when
    6439** registering the callback. ^The second is a copy of the database handle.
    6440** ^The third parameter is the name of the database that was written to -
    6441** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
    6442** is the number of pages currently in the write-ahead log file,
    6443** including those that were just committed.
    6444**
    6445** The callback function should normally return [SQLITE_OK]. ^If an error
    6446** code is returned, that error will propagate back up through the
    6447** SQLite code base to cause the statement that provoked the callback
    6448** to report an error, though the commit will have still occurred. If the
    6449** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
    6450** that does not correspond to any valid SQLite error code, the results
    6451** are undefined.
    6452**
    6453** A single database handle may have at most a single write-ahead log callback
    6454** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
    6455** previously registered write-ahead log callback. ^Note that the
    6456** [sqlite3_wal_autocheckpoint()] interface and the
    6457** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
    6458** those overwrite any prior [sqlite3_wal_hook()] settings.
    6459*/
    6460SQLITE_API void *sqlite3_wal_hook(
    6461 sqlite3*,
    6462 int(*)(void *,sqlite3*,const char*,int),
    6463 void*
    6464);
    6465
    6466/*
    6467** CAPI3REF: Configure an auto-checkpoint
    6468**
    6469** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
    6470** [sqlite3_wal_hook()] that causes any database on [database connection] D
    6471** to automatically [checkpoint]
    6472** after committing a transaction if there are N or
    6473** more frames in the [write-ahead log] file. ^Passing zero or
    6474** a negative value as the nFrame parameter disables automatic
    6475** checkpoints entirely.
    6476**
    6477** ^The callback registered by this function replaces any existing callback
    6478** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
    6479** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
    6480** configured by this function.
    6481**
    6482** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
    6483** from SQL.
    6484**
    6485** ^Every new [database connection] defaults to having the auto-checkpoint
    6486** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
    6487** pages. The use of this interface
    6488** is only necessary if the default setting is found to be suboptimal
    6489** for a particular application.
    6490*/
    6491SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
    6492
    6493/*
    6494** CAPI3REF: Checkpoint a database
    6495**
    6496** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
    6497** on [database connection] D to be [checkpointed]. ^If X is NULL or an
    6498** empty string, then a checkpoint is run on all databases of
    6499** connection D. ^If the database connection D is not in
    6500** [WAL | write-ahead log mode] then this interface is a harmless no-op.
    6501**
    6502** ^The [wal_checkpoint pragma] can be used to invoke this interface
    6503** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
    6504** [wal_autocheckpoint pragma] can be used to cause this interface to be
    6505** run whenever the WAL reaches a certain size threshold.
    6506**
    6507** See also: [sqlite3_wal_checkpoint_v2()]
    6508*/
    6509SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
    6510
    6511/*
    6512** CAPI3REF: Checkpoint a database
    6513**
    6514** Run a checkpoint operation on WAL database zDb attached to database
    6515** handle db. The specific operation is determined by the value of the
    6516** eMode parameter:
    6517**
    6518** <dl>
    6519** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
    6520** Checkpoint as many frames as possible without waiting for any database
    6521** readers or writers to finish. Sync the db file if all frames in the log
    6522** are checkpointed. This mode is the same as calling
    6523** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
    6524**
    6525** <dt>SQLITE_CHECKPOINT_FULL<dd>
    6526** This mode blocks (calls the busy-handler callback) until there is no
    6527** database writer and all readers are reading from the most recent database
    6528** snapshot. It then checkpoints all frames in the log file and syncs the
    6529** database file. This call blocks database writers while it is running,
    6530** but not database readers.
    6531**
    6532** <dt>SQLITE_CHECKPOINT_RESTART<dd>
    6533** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
    6534** checkpointing the log file it blocks (calls the busy-handler callback)
    6535** until all readers are reading from the database file only. This ensures
    6536** that the next client to write to the database file restarts the log file
    6537** from the beginning. This call blocks database writers while it is running,
    6538** but not database readers.
    6539** </dl>
    6540**
    6541** If pnLog is not NULL, then *pnLog is set to the total number of frames in
    6542** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
    6543** the total number of checkpointed frames (including any that were already
    6544** checkpointed when this function is called). *pnLog and *pnCkpt may be
    6545** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
    6546** If no values are available because of an error, they are both set to -1
    6547** before returning to communicate this to the caller.
    6548**
    6549** All calls obtain an exclusive "checkpoint" lock on the database file. If
    6550** any other process is running a checkpoint operation at the same time, the
    6551** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
    6552** busy-handler configured, it will not be invoked in this case.
    6553**
    6554** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
    6555** "writer" lock on the database file. If the writer lock cannot be obtained
    6556** immediately, and a busy-handler is configured, it is invoked and the writer
    6557** lock retried until either the busy-handler returns 0 or the lock is
    6558** successfully obtained. The busy-handler is also invoked while waiting for
    6559** database readers as described above. If the busy-handler returns 0 before
    6560** the writer lock is obtained or while waiting for database readers, the
    6561** checkpoint operation proceeds from that point in the same way as
    6562** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
    6563** without blocking any further. SQLITE_BUSY is returned in this case.
    6564**
    6565** If parameter zDb is NULL or points to a zero length string, then the
    6566** specified operation is attempted on all WAL databases. In this case the
    6567** values written to output parameters *pnLog and *pnCkpt are undefined. If
    6568** an SQLITE_BUSY error is encountered when processing one or more of the
    6569** attached WAL databases, the operation is still attempted on any remaining
    6570** attached databases and SQLITE_BUSY is returned to the caller. If any other
    6571** error occurs while processing an attached database, processing is abandoned
    6572** and the error code returned to the caller immediately. If no error
    6573** (SQLITE_BUSY or otherwise) is encountered while processing the attached
    6574** databases, SQLITE_OK is returned.
    6575**
    6576** If database zDb is the name of an attached database that is not in WAL
    6577** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
    6578** zDb is not NULL (or a zero length string) and is not the name of any
    6579** attached database, SQLITE_ERROR is returned to the caller.
    6580*/
    6581SQLITE_API int sqlite3_wal_checkpoint_v2(
    6582 sqlite3 *db, /* Database handle */
    6583 const char *zDb, /* Name of attached database (or NULL) */
    6584 int eMode, /* SQLITE_CHECKPOINT_* value */
    6585 int *pnLog, /* OUT: Size of WAL log in frames */
    6586 int *pnCkpt /* OUT: Total number of frames checkpointed */
    6587);
    6588
    6589/*
    6590** CAPI3REF: Checkpoint operation parameters
    6591**
    6592** These constants can be used as the 3rd parameter to
    6593** [sqlite3_wal_checkpoint_v2()]. See the [sqlite3_wal_checkpoint_v2()]
    6594** documentation for additional information about the meaning and use of
    6595** each of these values.
    6596*/
    6597#define SQLITE_CHECKPOINT_PASSIVE 0
    6598#define SQLITE_CHECKPOINT_FULL 1
    6599#define SQLITE_CHECKPOINT_RESTART 2
    6600
    6601/*
    6602** CAPI3REF: Virtual Table Interface Configuration
    6603**
    6604** This function may be called by either the [xConnect] or [xCreate] method
    6605** of a [virtual table] implementation to configure
    6606** various facets of the virtual table interface.
    6607**
    6608** If this interface is invoked outside the context of an xConnect or
    6609** xCreate virtual table method then the behavior is undefined.
    6610**
    6611** At present, there is only one option that may be configured using
    6612** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
    6613** may be added in the future.
    6614*/
    6615SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
    6616
    6617/*
    6618** CAPI3REF: Virtual Table Configuration Options
    6619**
    6620** These macros define the various options to the
    6621** [sqlite3_vtab_config()] interface that [virtual table] implementations
    6622** can use to customize and optimize their behavior.
    6623**
    6624** <dl>
    6625** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
    6626** <dd>Calls of the form
    6627** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
    6628** where X is an integer. If X is zero, then the [virtual table] whose
    6629** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
    6630** support constraints. In this configuration (which is the default) if
    6631** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
    6632** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
    6633** specified as part of the users SQL statement, regardless of the actual
    6634** ON CONFLICT mode specified.
    6635**
    6636** If X is non-zero, then the virtual table implementation guarantees
    6637** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
    6638** any modifications to internal or persistent data structures have been made.
    6639** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
    6640** is able to roll back a statement or database transaction, and abandon
    6641** or continue processing the current SQL statement as appropriate.
    6642** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
    6643** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
    6644** had been ABORT.
    6645**
    6646** Virtual table implementations that are required to handle OR REPLACE
    6647** must do so within the [xUpdate] method. If a call to the
    6648** [sqlite3_vtab_on_conflict()] function indicates that the current ON
    6649** CONFLICT policy is REPLACE, the virtual table implementation should
    6650** silently replace the appropriate rows within the xUpdate callback and
    6651** return SQLITE_OK. Or, if this is not possible, it may return
    6652** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
    6653** constraint handling.
    6654** </dl>
    6655*/
    6656#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
    6657
    6658/*
    6659** CAPI3REF: Determine The Virtual Table Conflict Policy
    6660**
    6661** This function may only be called from within a call to the [xUpdate] method
    6662** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
    6663** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
    6664** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
    6665** of the SQL statement that triggered the call to the [xUpdate] method of the
    6666** [virtual table].
    6667*/
    6668SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
    6669
    6670/*
    6671** CAPI3REF: Conflict resolution modes
    6672**
    6673** These constants are returned by [sqlite3_vtab_on_conflict()] to
    6674** inform a [virtual table] implementation what the [ON CONFLICT] mode
    6675** is for the SQL statement being evaluated.
    6676**
    6677** Note that the [SQLITE_IGNORE] constant is also used as a potential
    6678** return value from the [sqlite3_set_authorizer()] callback and that
    6679** [SQLITE_ABORT] is also a [result code].
    6680*/
    6681#define SQLITE_ROLLBACK 1
    6682/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
    6683#define SQLITE_FAIL 3
    6684/* #define SQLITE_ABORT 4 // Also an error code */
    6685#define SQLITE_REPLACE 5
    6686
    6687
    6688
    6689/*
    5723** Undo the hack that converts floating point types to integer for
    5724** builds on processors without floating point support.
    5725*/
    5726#ifdef SQLITE_OMIT_FLOATING_POINT
    5727# undef double
    5728#endif
    5729
    5730#ifdef __cplusplus
    5731} /* End of the 'extern "C"' block */
    5732#endif
    5733#endif
    5734
    6690** Undo the hack that converts floating point types to integer for
    6691** builds on processors without floating point support.
    6692*/
    6693#ifdef SQLITE_OMIT_FLOATING_POINT
    6694# undef double
    6695#endif
    6696
    6697#ifdef __cplusplus
    6698} /* End of the 'extern "C"' block */
    6699#endif
    6700#endif
    6701
    6702/*
    6703** 2010 August 30
    6704**
    6705** The author disclaims copyright to this source code. In place of
    6706** a legal notice, here is a blessing:
    6707**
    6708** May you do good and not evil.
    6709** May you find forgiveness for yourself and forgive others.
    6710** May you share freely, never taking more than you give.
    6711**
    6712*************************************************************************
    6713*/
    6714
    6715#ifndef _SQLITE3RTREE_H_
    6716#define _SQLITE3RTREE_H_
    6717
    6718
    6719#ifdef __cplusplus
    6720extern "C" {
    6721#endif
    6722
    6723typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
    6724
    6725/*
    6726** Register a geometry callback named zGeom that can be used as part of an
    6727** R-Tree geometry query as follows:
    6728**
    6729** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
    6730*/
    6731SQLITE_API int sqlite3_rtree_geometry_callback(
    6732 sqlite3 *db,
    6733 const char *zGeom,
    6734 int (*xGeom)(sqlite3_rtree_geometry *, int nCoord, double *aCoord, int *pRes),
    6735 void *pContext
    6736);
    6737
    6738
    6739/*
    6740** A pointer to a structure of the following type is passed as the first
    6741** argument to callbacks registered using rtree_geometry_callback().
    6742*/
    6743struct sqlite3_rtree_geometry {
    6744 void *pContext; /* Copy of pContext passed to s_r_g_c() */
    6745 int nParam; /* Size of array aParam[] */
    6746 double *aParam; /* Parameters passed to SQL geom function */
    6747 void *pUser; /* Callback implementation user data */
    6748 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
    6749};
    6750
    6751
    6752#ifdef __cplusplus
    6753} /* end of the 'extern "C"' block */
    6754#endif
    6755
    6756#endif /* ifndef _SQLITE3RTREE_H_ */
    6757