84
** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>
86
** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
87
** the sqlite3.h file specify the version of SQLite with which
88
** that header file is associated.
90
** The "version" of SQLite is a string of the form "W.X.Y" or "W.X.Y.Z".
91
** The W value is major version number and is always 3 in SQLite3.
92
** The W value only changes when backwards compatibility is
93
** broken and we intend to never break backwards compatibility.
94
** The X value is the minor version number and only changes when
95
** there are major feature enhancements that are forwards compatible
96
** but not backwards compatible.
97
** The Y value is the release number and is incremented with
98
** each release but resets back to 0 whenever X is incremented.
99
** The Z value only appears on branch releases.
101
** The SQLITE_VERSION_NUMBER is an integer that is computed as
105
** SQLITE_VERSION_NUMBER = W*1000000 + X*1000 + Y
106
** </pre></blockquote>
84
** CAPI3REF: Compile-Time Library Version Numbers
86
** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
87
** evaluates to a string literal that is the SQLite version in the
88
** format "X.Y.Z" where X is the major version number (always 3 for
89
** SQLite3) and Y is the minor version number and Z is the release number.)^
90
** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
91
** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
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.
108
98
** Since version 3.6.18, SQLite source code has been stored in the
109
** <a href="http://www.fossil-scm.org/">fossil configuration management
110
** system</a>. The SQLITE_SOURCE_ID
111
** macro is a string which identifies a particular check-in of SQLite
112
** within its configuration management system. The string contains the
113
** date and time of the check-in (UTC) and an SHA1 hash of the entire
99
** <a href="http://www.fossil-scm.org/">Fossil configuration management
100
** system</a>. ^The SQLITE_SOURCE_ID macro evalutes 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.
116
106
** See also: [sqlite3_libversion()],
117
107
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
118
108
** [sqlite_version()] and [sqlite_source_id()].
120
** Requirements: [H10011] [H10014]
122
#define SQLITE_VERSION "3.6.19"
123
#define SQLITE_VERSION_NUMBER 3006019
124
#define SQLITE_SOURCE_ID "2009-10-14 11:33:55 c1d499afc50d54b376945b4efb65c56c787a073d"
110
#define SQLITE_VERSION "3.6.22"
111
#define SQLITE_VERSION_NUMBER 3006022
112
#define SQLITE_SOURCE_ID "2010-01-05 15:30:36 28d0d7710761114a44a1a3a425a6883c661f06e7"
127
** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
115
** CAPI3REF: Run-Time Library Version Numbers
128
116
** KEYWORDS: sqlite3_version
130
118
** These interfaces provide the same information as the [SQLITE_VERSION],
131
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] #defines in the header,
132
** but are associated with the library instead of the header file. Cautious
119
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
120
** but are associated with the library instead of the header file. ^(Cautious
133
121
** programmers might include assert() statements in their application to
134
122
** verify that values returned by these interfaces match the macros in
135
123
** the header, and thus insure that the application is
280
270
typedef int (*sqlite3_callback)(void*,int,char**, char**);
283
** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
285
** The sqlite3_exec() interface is a convenient way of running one or more
286
** SQL statements without having to write a lot of C code. The UTF-8 encoded
287
** SQL statements are passed in as the second parameter to sqlite3_exec().
288
** The statements are evaluated one by one until either an error or
289
** an interrupt is encountered, or until they are all done. The 3rd parameter
290
** is an optional callback that is invoked once for each row of any query
291
** results produced by the SQL statements. The 5th parameter tells where
292
** to write any error messages.
294
** The error message passed back through the 5th parameter is held
295
** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak,
296
** the calling application should call [sqlite3_free()] on any error
297
** message returned through the 5th parameter when it has finished using
298
** the error message.
300
** If the SQL statement in the 2nd parameter is NULL or an empty string
301
** or a string containing only whitespace and comments, then no SQL
302
** statements are evaluated and the database is not changed.
304
** The sqlite3_exec() interface is implemented in terms of
305
** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
306
** The sqlite3_exec() routine does nothing to the database that cannot be done
307
** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
309
** The first parameter to [sqlite3_exec()] must be an valid and open
310
** [database connection].
312
** The database connection must not be closed while
313
** [sqlite3_exec()] is running.
315
** The calling function should use [sqlite3_free()] to free
316
** the memory that *errmsg is left pointing at once the error
317
** message is no longer needed.
319
** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
320
** must remain unchanged while [sqlite3_exec()] is running.
323
** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
324
** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
273
** CAPI3REF: One-Step Query Execution Interface
275
** The sqlite3_exec() interface is a convenience wrapper around
276
** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
277
** that allows an application to run multiple statements of SQL
278
** without having to use a lot of C code.
280
** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
281
** semicolon-separate SQL statements passed into its 2nd argument,
282
** in the context of the [database connection] passed in as its 1st
283
** argument. ^If the callback function of the 3rd argument to
284
** sqlite3_exec() is not NULL, then it is invoked for each result row
285
** coming out of the evaluated SQL statements. ^The 4th argument to
286
** to sqlite3_exec() is relayed through to the 1st argument of each
287
** callback invocation. ^If the callback pointer to sqlite3_exec()
288
** is NULL, then no callback is ever invoked and result rows are
291
** ^If an error occurs while evaluating the SQL statements passed into
292
** sqlite3_exec(), then execution of the current statement stops and
293
** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
294
** is not NULL then any error message is written into memory obtained
295
** from [sqlite3_malloc()] and passed back through the 5th parameter.
296
** To avoid memory leaks, the application should invoke [sqlite3_free()]
297
** on error message strings returned through the 5th parameter of
298
** of sqlite3_exec() after the error message string is no longer needed.
299
** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
300
** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
301
** NULL before returning.
303
** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
304
** routine returns SQLITE_ABORT without invoking the callback again and
305
** without running any subsequent SQL statements.
307
** ^The 2nd argument to the sqlite3_exec() callback function is the
308
** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
309
** callback is an array of pointers to strings obtained as if from
310
** [sqlite3_column_text()], one for each column. ^If an element of a
311
** result row is NULL then the corresponding string pointer for the
312
** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
313
** sqlite3_exec() callback is an array of pointers to strings where each
314
** entry represents the name of corresponding result column as obtained
315
** from [sqlite3_column_name()].
317
** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
318
** to an empty string, or a pointer that contains only whitespace and/or
319
** SQL comments, then no SQL statements are evaluated and the database
325
** <li> The application must insure that the 1st parameter to sqlite3_exec()
326
** is a valid and open [database connection].
327
** <li> The application must not close [database connection] specified by
328
** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
329
** <li> The application must not modify the SQL statement text passed into
330
** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
326
333
SQLITE_API int sqlite3_exec(
327
334
sqlite3*, /* An open database */
830
837
#define SQLITE_ACCESS_READ 2
833
** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
840
** CAPI3REF: Initialize The SQLite Library
835
** The sqlite3_initialize() routine initializes the
836
** SQLite library. The sqlite3_shutdown() routine
842
** ^The sqlite3_initialize() routine initializes the
843
** SQLite library. ^The sqlite3_shutdown() routine
837
844
** deallocates any resources that were allocated by sqlite3_initialize().
845
** These routines are designed to aid in process initialization and
846
** shutdown on embedded systems. Workstation applications using
847
** SQLite normally do not need to invoke either of these routines.
839
849
** A call to sqlite3_initialize() is an "effective" call if it is
840
850
** the first time sqlite3_initialize() is invoked during the lifetime of
841
851
** the process, or if it is the first time sqlite3_initialize() is invoked
842
** following a call to sqlite3_shutdown(). Only an effective call
852
** following a call to sqlite3_shutdown(). ^(Only an effective call
843
853
** of sqlite3_initialize() does any initialization. All other calls
844
** are harmless no-ops.
854
** are harmless no-ops.)^
846
856
** A call to sqlite3_shutdown() is an "effective" call if it is the first
847
** call to sqlite3_shutdown() since the last sqlite3_initialize(). Only
857
** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
848
858
** an effective call to sqlite3_shutdown() does any deinitialization.
849
** All other calls to sqlite3_shutdown() are harmless no-ops.
851
** Among other things, sqlite3_initialize() shall invoke
852
** sqlite3_os_init(). Similarly, sqlite3_shutdown()
853
** shall invoke sqlite3_os_end().
855
** The sqlite3_initialize() routine returns [SQLITE_OK] on success.
856
** If for some reason, sqlite3_initialize() is unable to initialize
859
** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
861
** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
862
** is not. The sqlite3_shutdown() interface must only be called from a
863
** single thread. All open [database connections] must be closed and all
864
** other SQLite resources must be deallocated prior to invoking
865
** sqlite3_shutdown().
867
** Among other things, ^sqlite3_initialize() will invoke
868
** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
869
** will invoke sqlite3_os_end().
871
** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
872
** ^If for some reason, sqlite3_initialize() is unable to initialize
857
873
** the library (perhaps it is unable to allocate a needed resource such
858
874
** as a mutex) it returns an [error code] other than [SQLITE_OK].
860
** The sqlite3_initialize() routine is called internally by many other
876
** ^The sqlite3_initialize() routine is called internally by many other
861
877
** SQLite interfaces so that an application usually does not need to
862
878
** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
863
879
** calls sqlite3_initialize() so the SQLite library will be automatically
864
880
** initialized when [sqlite3_open()] is called if it has not be initialized
865
** already. However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
881
** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
866
882
** compile-time option, then the automatic calls to sqlite3_initialize()
867
883
** are omitted and the application must call sqlite3_initialize() directly
868
884
** prior to using any other SQLite interface. For maximum portability,
1080
1104
** to [database connections] and [prepared statements] so that the
1081
1105
** application is free to use the same [database connection] or the
1082
1106
** same [prepared statement] in different threads at the same time.
1083
** See the [threading mode] documentation for additional information.</dd>
1107
** ^If SQLite is compiled with
1108
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1109
** it is not possible to set the Serialized [threading mode] and
1110
** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1111
** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1085
1113
** <dt>SQLITE_CONFIG_MALLOC</dt>
1086
** <dd>This option takes a single argument which is a pointer to an
1114
** <dd> ^(This option takes a single argument which is a pointer to an
1087
1115
** instance of the [sqlite3_mem_methods] structure. The argument specifies
1088
1116
** alternative low-level memory allocation routines to be used in place of
1089
** the memory allocation routines built into SQLite.</dd>
1117
** the memory allocation routines built into SQLite.)^ ^SQLite makes
1118
** its own private copy of the content of the [sqlite3_mem_methods] structure
1119
** before the [sqlite3_config()] call returns.</dd>
1091
1121
** <dt>SQLITE_CONFIG_GETMALLOC</dt>
1092
** <dd>This option takes a single argument which is a pointer to an
1122
** <dd> ^(This option takes a single argument which is a pointer to an
1093
1123
** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
1094
** structure is filled with the currently defined memory allocation routines.
1124
** structure is filled with the currently defined memory allocation routines.)^
1095
1125
** This option can be used to overload the default memory allocation
1096
1126
** routines with a wrapper that simulations memory allocation failure or
1097
** tracks memory usage, for example.</dd>
1127
** tracks memory usage, for example. </dd>
1099
1129
** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1100
** <dd>This option takes single argument of type int, interpreted as a
1130
** <dd> ^This option takes single argument of type int, interpreted as a
1101
1131
** boolean, which enables or disables the collection of memory allocation
1102
** statistics. When disabled, the following SQLite interfaces become
1132
** statistics. ^(When memory allocation statistics are disabled, the
1133
** following SQLite interfaces become non-operational:
1105
1135
** <li> [sqlite3_memory_used()]
1106
1136
** <li> [sqlite3_memory_highwater()]
1107
1137
** <li> [sqlite3_soft_heap_limit()]
1108
1138
** <li> [sqlite3_status()]
1140
** ^Memory allocation statistics are enabled by default unless SQLite is
1141
** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1142
** allocation statistics are disabled by default.
1112
1145
** <dt>SQLITE_CONFIG_SCRATCH</dt>
1113
** <dd>This option specifies a static memory buffer that SQLite can use for
1146
** <dd> ^This option specifies a static memory buffer that SQLite can use for
1114
1147
** scratch memory. There are three arguments: A pointer an 8-byte
1115
1148
** aligned memory buffer from which the scrach allocations will be
1116
1149
** drawn, the size of each scratch allocation (sz),
1117
1150
** and the maximum number of scratch allocations (N). The sz
1118
1151
** argument must be a multiple of 16. The sz parameter should be a few bytes
1119
1152
** larger than the actual scratch space required due to internal overhead.
1120
** The first argument should pointer to an 8-byte aligned buffer
1153
** The first argument must be a pointer to an 8-byte aligned buffer
1121
1154
** of at least sz*N bytes of memory.
1122
** SQLite will use no more than one scratch buffer at once per thread, so
1123
** N should be set to the expected maximum number of threads. The sz
1124
** parameter should be 6 times the size of the largest database page size.
1125
** Scratch buffers are used as part of the btree balance operation. If
1126
** The btree balancer needs additional memory beyond what is provided by
1127
** scratch buffers or if no scratch buffer space is specified, then SQLite
1128
** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
1155
** ^SQLite will use no more than one scratch buffer per thread. So
1156
** N should be set to the expected maximum number of threads. ^SQLite will
1157
** never require a scratch buffer that is more than 6 times the database
1158
** page size. ^If SQLite needs needs additional scratch memory beyond
1159
** what is provided by this configuration option, then
1160
** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
1130
1162
** <dt>SQLITE_CONFIG_PAGECACHE</dt>
1131
** <dd>This option specifies a static memory buffer that SQLite can use for
1163
** <dd> ^This option specifies a static memory buffer that SQLite can use for
1132
1164
** the database page cache with the default page cache implemenation.
1133
1165
** This configuration should not be used if an application-define page
1134
1166
** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1165
1197
** boundary or subsequent behavior of SQLite will be undefined.</dd>
1167
1199
** <dt>SQLITE_CONFIG_MUTEX</dt>
1168
** <dd>This option takes a single argument which is a pointer to an
1200
** <dd> ^(This option takes a single argument which is a pointer to an
1169
1201
** instance of the [sqlite3_mutex_methods] structure. The argument specifies
1170
1202
** alternative low-level mutex routines to be used in place
1171
** the mutex routines built into SQLite.</dd>
1203
** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
1204
** content of the [sqlite3_mutex_methods] structure before the call to
1205
** [sqlite3_config()] returns. ^If SQLite is compiled with
1206
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1207
** the entire mutexing subsystem is omitted from the build and hence calls to
1208
** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1209
** return [SQLITE_ERROR].</dd>
1173
1211
** <dt>SQLITE_CONFIG_GETMUTEX</dt>
1174
** <dd>This option takes a single argument which is a pointer to an
1212
** <dd> ^(This option takes a single argument which is a pointer to an
1175
1213
** instance of the [sqlite3_mutex_methods] structure. The
1176
1214
** [sqlite3_mutex_methods]
1177
** structure is filled with the currently defined mutex routines.
1215
** structure is filled with the currently defined mutex routines.)^
1178
1216
** This option can be used to overload the default mutex allocation
1179
1217
** routines with a wrapper used to track mutex usage for performance
1180
** profiling or testing, for example.</dd>
1218
** profiling or testing, for example. ^If SQLite is compiled with
1219
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1220
** the entire mutexing subsystem is omitted from the build and hence calls to
1221
** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1222
** return [SQLITE_ERROR].</dd>
1182
1224
** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1183
** <dd>This option takes two arguments that determine the default
1184
** memory allocation lookaside optimization. The first argument is the
1225
** <dd> ^(This option takes two arguments that determine the default
1226
** memory allocation for the lookaside memory allocator on each
1227
** [database connection]. The first argument is the
1185
1228
** size of each lookaside buffer slot and the second is the number of
1186
** slots allocated to each database connection. This option sets the
1187
** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1229
** slots allocated to each database connection.)^ ^(This option sets the
1230
** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1188
1231
** verb to [sqlite3_db_config()] can be used to change the lookaside
1189
** configuration on individual connections.</dd>
1232
** configuration on individual connections.)^ </dd>
1191
1234
** <dt>SQLITE_CONFIG_PCACHE</dt>
1192
** <dd>This option takes a single argument which is a pointer to
1235
** <dd> ^(This option takes a single argument which is a pointer to
1193
1236
** an [sqlite3_pcache_methods] object. This object specifies the interface
1194
** to a custom page cache implementation. SQLite makes a copy of the
1237
** to a custom page cache implementation.)^ ^SQLite makes a copy of the
1195
1238
** object and uses it for page cache memory allocations.</dd>
1197
1240
** <dt>SQLITE_CONFIG_GETPCACHE</dt>
1198
** <dd>This option takes a single argument which is a pointer to an
1241
** <dd> ^(This option takes a single argument which is a pointer to an
1199
1242
** [sqlite3_pcache_methods] object. SQLite copies of the current
1200
** page cache implementation into that object.</dd>
1243
** page cache implementation into that object.)^ </dd>
1255
** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700>
1257
** The sqlite3_extended_result_codes() routine enables or disables the
1258
** [extended result codes] feature of SQLite. The extended result
1259
** codes are disabled by default for historical compatibility considerations.
1262
** [H12201] [H12202]
1300
** CAPI3REF: Enable Or Disable Extended Result Codes
1302
** ^The sqlite3_extended_result_codes() routine enables or disables the
1303
** [extended result codes] feature of SQLite. ^The extended result
1304
** codes are disabled by default for historical compatibility.
1264
1306
SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
1267
** CAPI3REF: Last Insert Rowid {H12220} <S10700>
1309
** CAPI3REF: Last Insert Rowid
1269
** Each entry in an SQLite table has a unique 64-bit signed
1270
** integer key called the [ROWID | "rowid"]. The rowid is always available
1311
** ^Each entry in an SQLite table has a unique 64-bit signed
1312
** integer key called the [ROWID | "rowid"]. ^The rowid is always available
1271
1313
** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
1272
** names are not also used by explicitly declared columns. If
1314
** names are not also used by explicitly declared columns. ^If
1273
1315
** the table has a column of type [INTEGER PRIMARY KEY] then that column
1274
1316
** is another alias for the rowid.
1276
** This routine returns the [rowid] of the most recent
1318
** ^This routine returns the [rowid] of the most recent
1277
1319
** successful [INSERT] into the database from the [database connection]
1278
** in the first argument. If no successful [INSERT]s
1320
** in the first argument. ^If no successful [INSERT]s
1279
1321
** have ever occurred on that database connection, zero is returned.
1281
** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
1323
** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
1282
1324
** row is returned by this routine as long as the trigger is running.
1283
1325
** But once the trigger terminates, the value returned by this routine
1284
** reverts to the last value inserted before the trigger fired.
1326
** reverts to the last value inserted before the trigger fired.)^
1286
** An [INSERT] that fails due to a constraint violation is not a
1328
** ^An [INSERT] that fails due to a constraint violation is not a
1287
1329
** successful [INSERT] and does not change the value returned by this
1288
** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1330
** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1289
1331
** and INSERT OR ABORT make no changes to the return value of this
1290
** routine when their insertion fails. When INSERT OR REPLACE
1332
** routine when their insertion fails. ^(When INSERT OR REPLACE
1291
1333
** encounters a constraint violation, it does not fail. The
1292
1334
** INSERT continues to completion after deleting rows that caused
1293
1335
** the constraint problem so INSERT OR REPLACE will always change
1294
** the return value of this interface.
1336
** the return value of this interface.)^
1296
** For the purposes of this routine, an [INSERT] is considered to
1338
** ^For the purposes of this routine, an [INSERT] is considered to
1297
1339
** be successful even if it is subsequently rolled back.
1300
** [H12221] [H12223]
1341
** This function is accessible to SQL statements via the
1342
** [last_insert_rowid() SQL function].
1302
1344
** If a separate thread performs a new [INSERT] on the same
1303
1345
** database connection while the [sqlite3_last_insert_rowid()]
1394
1431
SQLITE_API int sqlite3_total_changes(sqlite3*);
1397
** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500>
1434
** CAPI3REF: Interrupt A Long-Running Query
1399
** This function causes any pending database operation to abort and
1436
** ^This function causes any pending database operation to abort and
1400
1437
** return at its earliest opportunity. This routine is typically
1401
1438
** called in response to a user action such as pressing "Cancel"
1402
1439
** or Ctrl-C where the user wants a long query operation to halt
1403
1440
** immediately.
1405
** It is safe to call this routine from a thread different from the
1442
** ^It is safe to call this routine from a thread different from the
1406
1443
** thread that is currently running the database operation. But it
1407
1444
** is not safe to call this routine with a [database connection] that
1408
1445
** is closed or might close before sqlite3_interrupt() returns.
1410
** If an SQL operation is very nearly finished at the time when
1447
** ^If an SQL operation is very nearly finished at the time when
1411
1448
** sqlite3_interrupt() is called, then it might not have an opportunity
1412
1449
** to be interrupted and might continue to completion.
1414
** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1415
** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1451
** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1452
** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1416
1453
** that is inside an explicit transaction, then the entire transaction
1417
1454
** will be rolled back automatically.
1419
** The sqlite3_interrupt(D) call is in effect until all currently running
1420
** SQL statements on [database connection] D complete. Any new SQL statements
1456
** ^The sqlite3_interrupt(D) call is in effect until all currently running
1457
** SQL statements on [database connection] D complete. ^Any new SQL statements
1421
1458
** that are started after the sqlite3_interrupt() call and before the
1422
1459
** running statements reaches zero are interrupted as if they had been
1423
** running prior to the sqlite3_interrupt() call. New SQL statements
1460
** running prior to the sqlite3_interrupt() call. ^New SQL statements
1424
1461
** that are started after the running statement count reaches zero are
1425
1462
** not effected by the sqlite3_interrupt().
1426
** A call to sqlite3_interrupt(D) that occurs when there are no running
1463
** ^A call to sqlite3_interrupt(D) that occurs when there are no running
1427
1464
** SQL statements is a no-op and has no effect on SQL statements
1428
1465
** that are started after the sqlite3_interrupt() call returns.
1431
** [H12271] [H12272]
1433
1467
** If the database connection closes while [sqlite3_interrupt()]
1434
1468
** is running then bad things will likely happen.
1436
1470
SQLITE_API void sqlite3_interrupt(sqlite3*);
1439
** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
1473
** CAPI3REF: Determine If An SQL Statement Is Complete
1441
1475
** These routines are useful during command-line input to determine if the
1442
1476
** currently entered text seems to form a complete SQL statement or
1443
1477
** if additional input is needed before sending the text into
1444
** SQLite for parsing. These routines return 1 if the input string
1445
** appears to be a complete SQL statement. A statement is judged to be
1478
** SQLite for parsing. ^These routines return 1 if the input string
1479
** appears to be a complete SQL statement. ^A statement is judged to be
1446
1480
** complete if it ends with a semicolon token and is not a prefix of a
1447
** well-formed CREATE TRIGGER statement. Semicolons that are embedded within
1481
** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
1448
1482
** string literals or quoted identifier names or comments are not
1449
1483
** independent tokens (they are part of the token in which they are
1450
** embedded) and thus do not count as a statement terminator. Whitespace
1484
** embedded) and thus do not count as a statement terminator. ^Whitespace
1451
1485
** and comments that follow the final semicolon are ignored.
1453
** These routines return 0 if the statement is incomplete. If a
1487
** ^These routines return 0 if the statement is incomplete. ^If a
1454
1488
** memory allocation fails, then SQLITE_NOMEM is returned.
1456
** These routines do not parse the SQL statements thus
1490
** ^These routines do not parse the SQL statements thus
1457
1491
** will not detect syntactically incorrect SQL.
1459
** If SQLite has not been initialized using [sqlite3_initialize()] prior
1493
** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
1460
1494
** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
1461
1495
** automatically by sqlite3_complete16(). If that initialization fails,
1462
1496
** then the return value from sqlite3_complete16() will be non-zero
1463
** regardless of whether or not the input SQL is complete.
1465
** Requirements: [H10511] [H10512]
1497
** regardless of whether or not the input SQL is complete.)^
1467
1499
** The input to [sqlite3_complete()] must be a zero-terminated
1468
1500
** UTF-8 string.
1508
1540
** will induce the first process to release its read lock and allow
1509
1541
** the second process to proceed.
1511
** The default busy callback is NULL.
1543
** ^The default busy callback is NULL.
1513
** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1545
** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1514
1546
** when SQLite is in the middle of a large transaction where all the
1515
1547
** changes will not fit into the in-memory cache. SQLite will
1516
1548
** already hold a RESERVED lock on the database file, but it needs
1517
1549
** to promote this lock to EXCLUSIVE so that it can spill cache
1518
1550
** pages into the database file without harm to concurrent
1519
** readers. If it is unable to promote the lock, then the in-memory
1551
** readers. ^If it is unable to promote the lock, then the in-memory
1520
1552
** cache will be left in an inconsistent state and so the error
1521
1553
** code is promoted from the relatively benign [SQLITE_BUSY] to
1522
** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
1554
** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion
1523
1555
** forces an automatic rollback of the changes. See the
1524
1556
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
1525
1557
** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1526
1558
** this is important.
1528
** There can only be a single busy handler defined for each
1560
** ^(There can only be a single busy handler defined for each
1529
1561
** [database connection]. Setting a new busy handler clears any
1530
** previously set handler. Note that calling [sqlite3_busy_timeout()]
1562
** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
1531
1563
** will also set or clear the busy handler.
1533
1565
** The busy callback should not take any actions which modify the
1534
1566
** database connection that invoked the busy handler. Any such actions
1535
1567
** result in undefined behavior.
1538
** [H12311] [H12312] [H12314] [H12316] [H12318]
1540
1569
** A busy handler must not close the database connection
1541
1570
** or [prepared statement] that invoked the busy handler.
1543
1572
SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1546
** CAPI3REF: Set A Busy Timeout {H12340} <S40410>
1575
** CAPI3REF: Set A Busy Timeout
1548
** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
1549
** for a specified amount of time when a table is locked. The handler
1577
** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
1578
** for a specified amount of time when a table is locked. ^The handler
1550
1579
** will sleep multiple times until at least "ms" milliseconds of sleeping
1551
** have accumulated. {H12343} After "ms" milliseconds of sleeping,
1580
** have accumulated. ^After at least "ms" milliseconds of sleeping,
1552
1581
** the handler returns 0 which causes [sqlite3_step()] to return
1553
1582
** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1555
** Calling this routine with an argument less than or equal to zero
1584
** ^Calling this routine with an argument less than or equal to zero
1556
1585
** turns off all busy handlers.
1558
** There can only be a single busy handler for a particular
1587
** ^(There can only be a single busy handler for a particular
1559
1588
** [database connection] any any given moment. If another busy handler
1560
1589
** was defined (using [sqlite3_busy_handler()]) prior to calling
1561
** this routine, that other busy handler is cleared.
1564
** [H12341] [H12343] [H12344]
1590
** this routine, that other busy handler is cleared.)^
1566
1592
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
1569
** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000>
1595
** CAPI3REF: Convenience Routines For Running Queries
1571
1597
** Definition: A <b>result table</b> is memory data structure created by the
1572
1598
** [sqlite3_get_table()] interface. A result table records the
1852
1873
** the build-in random() and randomblob() SQL functions. This interface allows
1853
1874
** applications to access the same PRNG for other purposes.
1855
** A call to this routine stores N bytes of randomness into buffer P.
1876
** ^A call to this routine stores N bytes of randomness into buffer P.
1857
** The first time this routine is invoked (either internally or by
1878
** ^The first time this routine is invoked (either internally or by
1858
1879
** the application) the PRNG is seeded using randomness obtained
1859
1880
** from the xRandomness method of the default [sqlite3_vfs] object.
1860
** On all subsequent invocations, the pseudo-randomness is generated
1881
** ^On all subsequent invocations, the pseudo-randomness is generated
1861
1882
** internally and without recourse to the [sqlite3_vfs] xRandomness
1867
1885
SQLITE_API void sqlite3_randomness(int N, void *P);
1870
** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100>
1888
** CAPI3REF: Compile-Time Authorization Callbacks
1872
** This routine registers a authorizer callback with a particular
1890
** ^This routine registers a authorizer callback with a particular
1873
1891
** [database connection], supplied in the first argument.
1874
** The authorizer callback is invoked as SQL statements are being compiled
1892
** ^The authorizer callback is invoked as SQL statements are being compiled
1875
1893
** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1876
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
1894
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
1877
1895
** points during the compilation process, as logic is being created
1878
1896
** to perform various actions, the authorizer callback is invoked to
1879
** see if those actions are allowed. The authorizer callback should
1897
** see if those actions are allowed. ^The authorizer callback should
1880
1898
** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
1881
1899
** specific action but allow the SQL statement to continue to be
1882
1900
** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1883
** rejected with an error. If the authorizer callback returns
1901
** rejected with an error. ^If the authorizer callback returns
1884
1902
** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
1885
1903
** then the [sqlite3_prepare_v2()] or equivalent call that triggered
1886
1904
** the authorizer will fail with an error message.
1888
1906
** When the callback returns [SQLITE_OK], that means the operation
1889
** requested is ok. When the callback returns [SQLITE_DENY], the
1907
** requested is ok. ^When the callback returns [SQLITE_DENY], the
1890
1908
** [sqlite3_prepare_v2()] or equivalent call that triggered the
1891
1909
** authorizer will fail with an error message explaining that
1892
1910
** access is denied.
1894
** The first parameter to the authorizer callback is a copy of the third
1895
** parameter to the sqlite3_set_authorizer() interface. The second parameter
1912
** ^The first parameter to the authorizer callback is a copy of the third
1913
** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
1896
1914
** to the callback is an integer [SQLITE_COPY | action code] that specifies
1897
** the particular action to be authorized. The third through sixth parameters
1915
** the particular action to be authorized. ^The third through sixth parameters
1898
1916
** to the callback are zero-terminated strings that contain additional
1899
1917
** details about the action to be authorized.
1901
** If the action code is [SQLITE_READ]
1919
** ^If the action code is [SQLITE_READ]
1902
1920
** and the callback returns [SQLITE_IGNORE] then the
1903
1921
** [prepared statement] statement is constructed to substitute
1904
1922
** a NULL value in place of the table column that would have
1905
1923
** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
1906
1924
** return can be used to deny an untrusted user access to individual
1907
1925
** columns of a table.
1908
** If the action code is [SQLITE_DELETE] and the callback returns
1926
** ^If the action code is [SQLITE_DELETE] and the callback returns
1909
1927
** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
1910
1928
** [truncate optimization] is disabled and all rows are deleted individually.
2298
2295
** Additional information is available at [limits | Limits in SQLite].
2301
** <dt>SQLITE_LIMIT_LENGTH</dt>
2302
** <dd>The maximum size of any string or BLOB or table row.<dd>
2304
** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
2305
** <dd>The maximum length of an SQL statement.</dd>
2307
** <dt>SQLITE_LIMIT_COLUMN</dt>
2298
** ^(<dt>SQLITE_LIMIT_LENGTH</dt>
2299
** <dd>The maximum size of any string or BLOB or table row.<dd>)^
2301
** ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
2302
** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
2304
** ^(<dt>SQLITE_LIMIT_COLUMN</dt>
2308
2305
** <dd>The maximum number of columns in a table definition or in the
2309
2306
** result set of a [SELECT] or the maximum number of columns in an index
2310
** or in an ORDER BY or GROUP BY clause.</dd>
2312
** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
2313
** <dd>The maximum depth of the parse tree on any expression.</dd>
2315
** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
2316
** <dd>The maximum number of terms in a compound SELECT statement.</dd>
2318
** <dt>SQLITE_LIMIT_VDBE_OP</dt>
2307
** or in an ORDER BY or GROUP BY clause.</dd>)^
2309
** ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
2310
** <dd>The maximum depth of the parse tree on any expression.</dd>)^
2312
** ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
2313
** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
2315
** ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
2319
2316
** <dd>The maximum number of instructions in a virtual machine program
2320
** used to implement an SQL statement.</dd>
2322
** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
2323
** <dd>The maximum number of arguments on a function.</dd>
2325
** <dt>SQLITE_LIMIT_ATTACHED</dt>
2326
** <dd>The maximum number of [ATTACH | attached databases].</dd>
2328
** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
2317
** used to implement an SQL statement.</dd>)^
2319
** ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
2320
** <dd>The maximum number of arguments on a function.</dd>)^
2322
** ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
2323
** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
2325
** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
2329
2326
** <dd>The maximum length of the pattern argument to the [LIKE] or
2330
** [GLOB] operators.</dd>
2327
** [GLOB] operators.</dd>)^
2332
** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2329
** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2333
2330
** <dd>The maximum number of variables in an SQL statement that can
2336
** <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
2337
** <dd>The maximum depth of recursion for triggers.</dd>
2333
** ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
2334
** <dd>The maximum depth of recursion for triggers.</dd>)^
2340
2337
#define SQLITE_LIMIT_LENGTH 0
2538
2537
** In the templates above, NNN represents an integer literal,
2539
** and VVV represents an alphanumeric identifer. The values of these
2538
** and VVV represents an alphanumeric identifer.)^ ^The values of these
2540
2539
** parameters (also called "host parameter names" or "SQL parameters")
2541
2540
** can be set using the sqlite3_bind_*() routines defined here.
2543
** The first argument to the sqlite3_bind_*() routines is always
2542
** ^The first argument to the sqlite3_bind_*() routines is always
2544
2543
** a pointer to the [sqlite3_stmt] object returned from
2545
2544
** [sqlite3_prepare_v2()] or its variants.
2547
** The second argument is the index of the SQL parameter to be set.
2548
** The leftmost SQL parameter has an index of 1. When the same named
2546
** ^The second argument is the index of the SQL parameter to be set.
2547
** ^The leftmost SQL parameter has an index of 1. ^When the same named
2549
2548
** SQL parameter is used more than once, second and subsequent
2550
2549
** occurrences have the same index as the first occurrence.
2551
** The index for named parameters can be looked up using the
2552
** [sqlite3_bind_parameter_index()] API if desired. The index
2550
** ^The index for named parameters can be looked up using the
2551
** [sqlite3_bind_parameter_index()] API if desired. ^The index
2553
2552
** for "?NNN" parameters is the value of NNN.
2554
** The NNN value must be between 1 and the [sqlite3_limit()]
2553
** ^The NNN value must be between 1 and the [sqlite3_limit()]
2555
2554
** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
2557
** The third argument is the value to bind to the parameter.
2556
** ^The third argument is the value to bind to the parameter.
2559
** In those routines that have a fourth argument, its value is the
2558
** ^(In those routines that have a fourth argument, its value is the
2560
2559
** number of bytes in the parameter. To be clear: the value is the
2561
** number of <u>bytes</u> in the value, not the number of characters.
2562
** If the fourth parameter is negative, the length of the string is
2560
** number of <u>bytes</u> in the value, not the number of characters.)^
2561
** ^If the fourth parameter is negative, the length of the string is
2563
2562
** the number of bytes up to the first zero terminator.
2565
** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
2564
** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
2566
2565
** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
2567
** string after SQLite has finished with it. If the fifth argument is
2566
** string after SQLite has finished with it. ^If the fifth argument is
2568
2567
** the special value [SQLITE_STATIC], then SQLite assumes that the
2569
2568
** information is in static, unmanaged space and does not need to be freed.
2570
** If the fifth argument has the value [SQLITE_TRANSIENT], then
2569
** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
2571
2570
** SQLite makes its own private copy of the data immediately, before
2572
2571
** the sqlite3_bind_*() routine returns.
2574
** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
2575
** is filled with zeroes. A zeroblob uses a fixed amount of memory
2573
** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
2574
** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
2576
2575
** (just an integer to hold its size) while it is being processed.
2577
2576
** Zeroblobs are intended to serve as placeholders for BLOBs whose
2578
2577
** content is later written using
2579
2578
** [sqlite3_blob_open | incremental BLOB I/O] routines.
2580
** A negative value for the zeroblob results in a zero-length BLOB.
2582
** The sqlite3_bind_*() routines must be called after
2583
** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
2584
** before [sqlite3_step()].
2585
** Bindings are not cleared by the [sqlite3_reset()] routine.
2586
** Unbound parameters are interpreted as NULL.
2588
** These routines return [SQLITE_OK] on success or an error code if
2589
** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
2590
** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails.
2591
** [SQLITE_MISUSE] might be returned if these routines are called on a
2592
** virtual machine that is the wrong state or which has already been finalized.
2593
** Detection of misuse is unreliable. Applications should not depend
2594
** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a
2595
** a logic error in the application. Future versions of SQLite might
2596
** panic rather than return SQLITE_MISUSE.
2579
** ^A negative value for the zeroblob results in a zero-length BLOB.
2581
** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
2582
** for the [prepared statement] or with a prepared statement for which
2583
** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
2584
** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
2585
** routine is passed a [prepared statement] that has been finalized, the
2586
** result is undefined and probably harmful.
2588
** ^Bindings are not cleared by the [sqlite3_reset()] routine.
2589
** ^Unbound parameters are interpreted as NULL.
2591
** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
2592
** [error code] if anything goes wrong.
2593
** ^[SQLITE_RANGE] is returned if the parameter
2594
** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
2598
2596
** See also: [sqlite3_bind_parameter_count()],
2599
2597
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
2602
** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527]
2603
** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551]
2606
2599
SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
2607
2600
SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
2614
2607
SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
2617
** CAPI3REF: Number Of SQL Parameters {H13600} <S70300>
2610
** CAPI3REF: Number Of SQL Parameters
2619
** This routine can be used to find the number of [SQL parameters]
2612
** ^This routine can be used to find the number of [SQL parameters]
2620
2613
** in a [prepared statement]. SQL parameters are tokens of the
2621
2614
** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
2622
2615
** placeholders for values that are [sqlite3_bind_blob | bound]
2623
2616
** to the parameters at a later time.
2625
** This routine actually returns the index of the largest (rightmost)
2618
** ^(This routine actually returns the index of the largest (rightmost)
2626
2619
** parameter. For all forms except ?NNN, this will correspond to the
2627
** number of unique parameters. If parameters of the ?NNN are used,
2628
** there may be gaps in the list.
2620
** number of unique parameters. If parameters of the ?NNN form are used,
2621
** there may be gaps in the list.)^
2630
2623
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2631
2624
** [sqlite3_bind_parameter_name()], and
2632
2625
** [sqlite3_bind_parameter_index()].
2637
2627
SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
2640
** CAPI3REF: Name Of A Host Parameter {H13620} <S70300>
2630
** CAPI3REF: Name Of A Host Parameter
2642
** This routine returns a pointer to the name of the n-th
2643
** [SQL parameter] in a [prepared statement].
2644
** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
2632
** ^The sqlite3_bind_parameter_name(P,N) interface returns
2633
** the name of the N-th [SQL parameter] in the [prepared statement] P.
2634
** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
2645
2635
** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
2646
2636
** respectively.
2647
2637
** In other words, the initial ":" or "$" or "@" or "?"
2648
** is included as part of the name.
2649
** Parameters of the form "?" without a following integer have no name
2650
** and are also referred to as "anonymous parameters".
2652
** The first host parameter has an index of 1, not 0.
2654
** If the value n is out of range or if the n-th parameter is
2655
** nameless, then NULL is returned. The returned string is
2638
** is included as part of the name.)^
2639
** ^Parameters of the form "?" without a following integer have no name
2640
** and are referred to as "nameless" or "anonymous parameters".
2642
** ^The first host parameter has an index of 1, not 0.
2644
** ^If the value N is out of range or if the N-th parameter is
2645
** nameless, then NULL is returned. ^The returned string is
2656
2646
** always in UTF-8 encoding even if the named parameter was
2657
2647
** originally specified as UTF-16 in [sqlite3_prepare16()] or
2658
2648
** [sqlite3_prepare16_v2()].
2660
2650
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2661
2651
** [sqlite3_bind_parameter_count()], and
2662
2652
** [sqlite3_bind_parameter_index()].
2667
2654
SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
2670
** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300>
2657
** CAPI3REF: Index Of A Parameter With A Given Name
2672
** Return the index of an SQL parameter given its name. The
2659
** ^Return the index of an SQL parameter given its name. ^The
2673
2660
** index value returned is suitable for use as the second
2674
** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero
2675
** is returned if no matching parameter is found. The parameter
2661
** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
2662
** is returned if no matching parameter is found. ^The parameter
2676
2663
** name must be given in UTF-8 even if the original statement
2677
2664
** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
2679
2666
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2680
2667
** [sqlite3_bind_parameter_count()], and
2681
2668
** [sqlite3_bind_parameter_index()].
2686
2670
SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
2689
** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300>
2673
** CAPI3REF: Reset All Bindings On A Prepared Statement
2691
** Contrary to the intuition of many, [sqlite3_reset()] does not reset
2675
** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
2692
2676
** the [sqlite3_bind_blob | bindings] on a [prepared statement].
2693
** Use this routine to reset all host parameters to NULL.
2677
** ^Use this routine to reset all host parameters to NULL.
2698
2679
SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
2701
** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700>
2682
** CAPI3REF: Number Of Columns In A Result Set
2703
** Return the number of columns in the result set returned by the
2704
** [prepared statement]. This routine returns 0 if pStmt is an SQL
2684
** ^Return the number of columns in the result set returned by the
2685
** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
2705
2686
** statement that does not return data (for example an [UPDATE]).
2710
2688
SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
2713
** CAPI3REF: Column Names In A Result Set {H13720} <S10700>
2691
** CAPI3REF: Column Names In A Result Set
2715
** These routines return the name assigned to a particular column
2716
** in the result set of a [SELECT] statement. The sqlite3_column_name()
2693
** ^These routines return the name assigned to a particular column
2694
** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
2717
2695
** interface returns a pointer to a zero-terminated UTF-8 string
2718
2696
** and sqlite3_column_name16() returns a pointer to a zero-terminated
2719
** UTF-16 string. The first parameter is the [prepared statement]
2720
** that implements the [SELECT] statement. The second parameter is the
2721
** column number. The leftmost column is number 0.
2697
** UTF-16 string. ^The first parameter is the [prepared statement]
2698
** that implements the [SELECT] statement. ^The second parameter is the
2699
** column number. ^The leftmost column is number 0.
2723
** The returned string pointer is valid until either the [prepared statement]
2701
** ^The returned string pointer is valid until either the [prepared statement]
2724
2702
** is destroyed by [sqlite3_finalize()] or until the next call to
2725
2703
** sqlite3_column_name() or sqlite3_column_name16() on the same column.
2727
** If sqlite3_malloc() fails during the processing of either routine
2705
** ^If sqlite3_malloc() fails during the processing of either routine
2728
2706
** (for example during a conversion from UTF-8 to UTF-16) then a
2729
2707
** NULL pointer is returned.
2731
** The name of a result column is the value of the "AS" clause for
2709
** ^The name of a result column is the value of the "AS" clause for
2732
2710
** that column, if there is an AS clause. If there is no AS clause
2733
2711
** then the name of the column is unspecified and may change from
2734
2712
** one release of SQLite to the next.
2737
** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727]
2739
2714
SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
2740
2715
SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
2743
** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700>
2718
** CAPI3REF: Source Of Data In A Query Result
2745
** These routines provide a means to determine what column of what
2746
** table in which database a result of a [SELECT] statement comes from.
2747
** The name of the database or table or column can be returned as
2748
** either a UTF-8 or UTF-16 string. The _database_ routines return
2720
** ^These routines provide a means to determine the database, table, and
2721
** table column that is the origin of a particular result column in
2722
** [SELECT] statement.
2723
** ^The name of the database or table or column can be returned as
2724
** either a UTF-8 or UTF-16 string. ^The _database_ routines return
2749
2725
** the database name, the _table_ routines return the table name, and
2750
2726
** the origin_ routines return the column name.
2751
** The returned string is valid until the [prepared statement] is destroyed
2727
** ^The returned string is valid until the [prepared statement] is destroyed
2752
2728
** using [sqlite3_finalize()] or until the same information is requested
2753
2729
** again in a different encoding.
2755
** The names returned are the original un-aliased names of the
2731
** ^The names returned are the original un-aliased names of the
2756
2732
** database, table, and column.
2758
** The first argument to the following calls is a [prepared statement].
2759
** These functions return information about the Nth column returned by
2734
** ^The first argument to these interfaces is a [prepared statement].
2735
** ^These functions return information about the Nth result column returned by
2760
2736
** the statement, where N is the second function argument.
2737
** ^The left-most column is column 0 for these routines.
2762
** If the Nth column returned by the statement is an expression or
2739
** ^If the Nth column returned by the statement is an expression or
2763
2740
** subquery and is not a column value, then all of these functions return
2764
** NULL. These routine might also return NULL if a memory allocation error
2765
** occurs. Otherwise, they return the name of the attached database, table
2766
** and column that query result column was extracted from.
2768
** As with all other SQLite APIs, those postfixed with "16" return
2769
** UTF-16 encoded strings, the other functions return UTF-8. {END}
2771
** These APIs are only available if the library was compiled with the
2772
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
2741
** NULL. ^These routine might also return NULL if a memory allocation error
2742
** occurs. ^Otherwise, they return the name of the attached database, table,
2743
** or column that query result column was extracted from.
2745
** ^As with all other SQLite APIs, those whose names end with "16" return
2746
** UTF-16 encoded strings and the other functions return UTF-8.
2748
** ^These APIs are only available if the library was compiled with the
2749
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
2775
2751
** If two or more threads call one or more of these routines against the same
2776
2752
** prepared statement and column at the same time then the results are
2780
** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748]
2782
2755
** If two or more threads call one or more
2783
2756
** [sqlite3_column_database_name | column metadata interfaces]
2784
2757
** for the same [prepared statement] and result column
2841
2811
** new "v2" interface is recommended for new applications but the legacy
2842
2812
** interface will continue to be supported.
2844
** In the legacy interface, the return value will be either [SQLITE_BUSY],
2814
** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
2845
2815
** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
2846
** With the "v2" interface, any of the other [result codes] or
2816
** ^With the "v2" interface, any of the other [result codes] or
2847
2817
** [extended result codes] might be returned as well.
2849
** [SQLITE_BUSY] means that the database engine was unable to acquire the
2850
** database locks it needs to do its job. If the statement is a [COMMIT]
2819
** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
2820
** database locks it needs to do its job. ^If the statement is a [COMMIT]
2851
2821
** or occurs outside of an explicit transaction, then you can retry the
2852
2822
** statement. If the statement is not a [COMMIT] and occurs within a
2853
2823
** explicit transaction then you should rollback the transaction before
2856
** [SQLITE_DONE] means that the statement has finished executing
2826
** ^[SQLITE_DONE] means that the statement has finished executing
2857
2827
** successfully. sqlite3_step() should not be called again on this virtual
2858
2828
** machine without first calling [sqlite3_reset()] to reset the virtual
2859
2829
** machine back to its initial state.
2861
** If the SQL statement being executed returns any data, then [SQLITE_ROW]
2831
** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
2862
2832
** is returned each time a new row of data is ready for processing by the
2863
2833
** caller. The values may be accessed using the [column access functions].
2864
2834
** sqlite3_step() is called again to retrieve the next row of data.
2866
** [SQLITE_ERROR] means that a run-time error (such as a constraint
2836
** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
2867
2837
** violation) has occurred. sqlite3_step() should not be called again on
2868
2838
** the VM. More information may be found by calling [sqlite3_errmsg()].
2869
** With the legacy interface, a more specific error code (for example,
2839
** ^With the legacy interface, a more specific error code (for example,
2870
2840
** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
2871
2841
** can be obtained by calling [sqlite3_reset()] on the
2872
** [prepared statement]. In the "v2" interface,
2842
** [prepared statement]. ^In the "v2" interface,
2873
2843
** the more specific error code is returned directly by sqlite3_step().
2875
2845
** [SQLITE_MISUSE] means that the this routine was called inappropriately.
3106
3069
SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
3109
** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100>
3072
** CAPI3REF: Destroy A Prepared Statement Object
3111
** The sqlite3_finalize() function is called to delete a [prepared statement].
3112
** If the statement was executed successfully or not executed at all, then
3113
** SQLITE_OK is returned. If execution of the statement failed then an
3074
** ^The sqlite3_finalize() function is called to delete a [prepared statement].
3075
** ^If the statement was executed successfully or not executed at all, then
3076
** SQLITE_OK is returned. ^If execution of the statement failed then an
3114
3077
** [error code] or [extended error code] is returned.
3116
** This routine can be called at any point during the execution of the
3117
** [prepared statement]. If the virtual machine has not
3079
** ^This routine can be called at any point during the execution of the
3080
** [prepared statement]. ^If the virtual machine has not
3118
3081
** completed execution when this routine is called, that is like
3119
3082
** encountering an error or an [sqlite3_interrupt | interrupt].
3120
** Incomplete updates may be rolled back and transactions canceled,
3083
** ^Incomplete updates may be rolled back and transactions canceled,
3121
3084
** depending on the circumstances, and the
3122
3085
** [error code] returned will be [SQLITE_ABORT].
3125
** [H11302] [H11304]
3127
3087
SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
3130
** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300>
3090
** CAPI3REF: Reset A Prepared Statement Object
3132
3092
** The sqlite3_reset() function is called to reset a [prepared statement]
3133
3093
** object back to its initial state, ready to be re-executed.
3134
** Any SQL statement variables that had values bound to them using
3094
** ^Any SQL statement variables that had values bound to them using
3135
3095
** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
3136
3096
** Use [sqlite3_clear_bindings()] to reset the bindings.
3138
** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
3139
** back to the beginning of its program.
3141
** {H11334} If the most recent call to [sqlite3_step(S)] for the
3142
** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
3143
** or if [sqlite3_step(S)] has never before been called on S,
3144
** then [sqlite3_reset(S)] returns [SQLITE_OK].
3146
** {H11336} If the most recent call to [sqlite3_step(S)] for the
3147
** [prepared statement] S indicated an error, then
3148
** [sqlite3_reset(S)] returns an appropriate [error code].
3150
** {H11338} The [sqlite3_reset(S)] interface does not change the values
3151
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
3098
** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
3099
** back to the beginning of its program.
3101
** ^If the most recent call to [sqlite3_step(S)] for the
3102
** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
3103
** or if [sqlite3_step(S)] has never before been called on S,
3104
** then [sqlite3_reset(S)] returns [SQLITE_OK].
3106
** ^If the most recent call to [sqlite3_step(S)] for the
3107
** [prepared statement] S indicated an error, then
3108
** [sqlite3_reset(S)] returns an appropriate [error code].
3110
** ^The [sqlite3_reset(S)] interface does not change the values
3111
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
3153
3113
SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
3156
** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200>
3116
** CAPI3REF: Create Or Redefine SQL Functions
3157
3117
** KEYWORDS: {function creation routines}
3158
3118
** KEYWORDS: {application-defined SQL function}
3159
3119
** KEYWORDS: {application-defined SQL functions}
3161
** These two functions (collectively known as "function creation routines")
3121
** ^These two functions (collectively known as "function creation routines")
3162
3122
** are used to add SQL functions or aggregates or to redefine the behavior
3163
3123
** of existing SQL functions or aggregates. The only difference between the
3164
3124
** two is that the second parameter, the name of the (scalar) function or
3165
3125
** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
3166
3126
** for sqlite3_create_function16().
3168
** The first parameter is the [database connection] to which the SQL
3169
** function is to be added. If a single program uses more than one database
3170
** connection internally, then SQL functions must be added individually to
3171
** each database connection.
3128
** ^The first parameter is the [database connection] to which the SQL
3129
** function is to be added. ^If an application uses more than one database
3130
** connection then application-defined SQL functions must be added
3131
** to each database connection separately.
3173
3133
** The second parameter is the name of the SQL function to be created or
3174
** redefined. The length of the name is limited to 255 bytes, exclusive of
3134
** redefined. ^The length of the name is limited to 255 bytes, exclusive of
3175
3135
** the zero-terminator. Note that the name length limit is in bytes, not
3176
** characters. Any attempt to create a function with a longer name
3136
** characters. ^Any attempt to create a function with a longer name
3177
3137
** will result in [SQLITE_ERROR] being returned.
3179
** The third parameter (nArg)
3139
** ^The third parameter (nArg)
3180
3140
** is the number of arguments that the SQL function or
3181
** aggregate takes. If this parameter is -1, then the SQL function or
3141
** aggregate takes. ^If this parameter is -1, then the SQL function or
3182
3142
** aggregate may take any number of arguments between 0 and the limit
3183
3143
** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
3184
3144
** parameter is less than -1 or greater than 127 then the behavior is
3188
3148
** [SQLITE_UTF8 | text encoding] this SQL function prefers for
3189
3149
** its parameters. Any SQL function implementation should be able to work
3190
3150
** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
3191
** more efficient with one encoding than another. An application may
3151
** more efficient with one encoding than another. ^An application may
3192
3152
** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
3193
3153
** times with the same function but with different values of eTextRep.
3194
** When multiple implementations of the same function are available, SQLite
3154
** ^When multiple implementations of the same function are available, SQLite
3195
3155
** will pick the one that involves the least amount of data conversion.
3196
3156
** If there is only a single implementation which does not care what text
3197
3157
** encoding is used, then the fourth argument should be [SQLITE_ANY].
3199
** The fifth parameter is an arbitrary pointer. The implementation of the
3200
** function can gain access to this pointer using [sqlite3_user_data()].
3159
** ^(The fifth parameter is an arbitrary pointer. The implementation of the
3160
** function can gain access to this pointer using [sqlite3_user_data()].)^
3202
3162
** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
3203
3163
** pointers to C-language functions that implement the SQL function or
3204
** aggregate. A scalar SQL function requires an implementation of the xFunc
3205
** callback only, NULL pointers should be passed as the xStep and xFinal
3206
** parameters. An aggregate SQL function requires an implementation of xStep
3207
** and xFinal and NULL should be passed for xFunc. To delete an existing
3164
** aggregate. ^A scalar SQL function requires an implementation of the xFunc
3165
** callback only; NULL pointers should be passed as the xStep and xFinal
3166
** parameters. ^An aggregate SQL function requires an implementation of xStep
3167
** and xFinal and NULL should be passed for xFunc. ^To delete an existing
3208
3168
** SQL function or aggregate, pass NULL for all three function callbacks.
3210
** It is permitted to register multiple implementations of the same
3170
** ^It is permitted to register multiple implementations of the same
3211
3171
** functions with the same name but with either differing numbers of
3212
** arguments or differing preferred text encodings. SQLite will use
3172
** arguments or differing preferred text encodings. ^SQLite will use
3213
3173
** the implementation that most closely matches the way in which the
3214
** SQL function is used. A function implementation with a non-negative
3174
** SQL function is used. ^A function implementation with a non-negative
3215
3175
** nArg parameter is a better match than a function implementation with
3216
** a negative nArg. A function where the preferred text encoding
3176
** a negative nArg. ^A function where the preferred text encoding
3217
3177
** matches the database encoding is a better
3218
3178
** match than a function where the encoding is different.
3219
** A function where the encoding difference is between UTF16le and UTF16be
3179
** ^A function where the encoding difference is between UTF16le and UTF16be
3220
3180
** is a closer match than a function where the encoding difference is
3221
3181
** between UTF8 and UTF16.
3223
** Built-in functions may be overloaded by new application-defined functions.
3224
** The first application-defined function with a given name overrides all
3183
** ^Built-in functions may be overloaded by new application-defined functions.
3184
** ^The first application-defined function with a given name overrides all
3225
3185
** built-in functions in the same [database connection] with the same name.
3226
** Subsequent application-defined functions of the same name only override
3186
** ^Subsequent application-defined functions of the same name only override
3227
3187
** prior application-defined functions that are an exact match for the
3228
3188
** number of parameters and preferred encoding.
3230
** An application-defined function is permitted to call other
3190
** ^An application-defined function is permitted to call other
3231
3191
** SQLite interfaces. However, such calls must not
3232
3192
** close the database connection nor finalize or reset the prepared
3233
3193
** statement in which the function is running.
3236
** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16127]
3237
** [H16130] [H16133] [H16136] [H16139] [H16142]
3239
3195
SQLITE_API int sqlite3_create_function(
3352
3304
SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
3355
** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200>
3357
** The implementation of aggregate SQL functions use this routine to allocate
3358
** a structure for storing their state.
3360
** The first time the sqlite3_aggregate_context() routine is called for a
3361
** particular aggregate, SQLite allocates nBytes of memory, zeroes out that
3362
** memory, and returns a pointer to it. On second and subsequent calls to
3363
** sqlite3_aggregate_context() for the same aggregate function index,
3364
** the same buffer is returned. The implementation of the aggregate can use
3365
** the returned buffer to accumulate data.
3367
** SQLite automatically frees the allocated buffer when the aggregate
3370
** The first parameter should be a copy of the
3307
** CAPI3REF: Obtain Aggregate Function Context
3309
** Implementions of aggregate SQL functions use this
3310
** routine to allocate memory for storing their state.
3312
** ^The first time the sqlite3_aggregate_context(C,N) routine is called
3313
** for a particular aggregate function, SQLite
3314
** allocates N of memory, zeroes out that memory, and returns a pointer
3315
** to the new memory. ^On second and subsequent calls to
3316
** sqlite3_aggregate_context() for the same aggregate function instance,
3317
** the same buffer is returned. Sqlite3_aggregate_context() is normally
3318
** called once for each invocation of the xStep callback and then one
3319
** last time when the xFinal callback is invoked. ^(When no rows match
3320
** an aggregate query, the xStep() callback of the aggregate function
3321
** implementation is never called and xFinal() is called exactly once.
3322
** In those cases, sqlite3_aggregate_context() might be called for the
3323
** first time from within xFinal().)^
3325
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is
3326
** less than or equal to zero or if a memory allocate error occurs.
3328
** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
3329
** determined by the N parameter on first successful call. Changing the
3330
** value of N in subsequent call to sqlite3_aggregate_context() within
3331
** the same aggregate function instance will not resize the memory
3334
** ^SQLite automatically frees the memory allocated by
3335
** sqlite3_aggregate_context() when the aggregate query concludes.
3337
** The first parameter must be a copy of the
3371
3338
** [sqlite3_context | SQL function context] that is the first parameter
3372
** to the callback routine that implements the aggregate function.
3339
** to the xStep or xFinal callback routine that implements the aggregate
3374
3342
** This routine must be called from the same thread in which
3375
3343
** the aggregate SQL function is running.
3378
** [H16211] [H16213] [H16215] [H16217]
3380
3345
SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
3383
** CAPI3REF: User Data For Functions {H16240} <S20200>
3348
** CAPI3REF: User Data For Functions
3385
** The sqlite3_user_data() interface returns a copy of
3350
** ^The sqlite3_user_data() interface returns a copy of
3386
3351
** the pointer that was the pUserData parameter (the 5th parameter)
3387
3352
** of the [sqlite3_create_function()]
3388
3353
** and [sqlite3_create_function16()] routines that originally
3389
** registered the application defined function. {END}
3354
** registered the application defined function.
3391
3356
** This routine must be called from the same thread in which
3392
3357
** the application-defined function is running.
3397
3359
SQLITE_API void *sqlite3_user_data(sqlite3_context*);
3400
** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200>
3362
** CAPI3REF: Database Connection For Functions
3402
** The sqlite3_context_db_handle() interface returns a copy of
3364
** ^The sqlite3_context_db_handle() interface returns a copy of
3403
3365
** the pointer to the [database connection] (the 1st parameter)
3404
3366
** of the [sqlite3_create_function()]
3405
3367
** and [sqlite3_create_function16()] routines that originally
3406
3368
** registered the application defined function.
3411
3370
SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
3414
** CAPI3REF: Function Auxiliary Data {H16270} <S20200>
3373
** CAPI3REF: Function Auxiliary Data
3416
3375
** The following two functions may be used by scalar SQL functions to
3417
3376
** associate metadata with argument values. If the same value is passed to
3424
3383
** invocations of the same function so that the original pattern string
3425
3384
** does not need to be recompiled on each invocation.
3427
** The sqlite3_get_auxdata() interface returns a pointer to the metadata
3386
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
3428
3387
** associated by the sqlite3_set_auxdata() function with the Nth argument
3429
** value to the application-defined function. If no metadata has been ever
3388
** value to the application-defined function. ^If no metadata has been ever
3430
3389
** been set for the Nth argument of the function, or if the corresponding
3431
3390
** function parameter has changed since the meta-data was set,
3432
3391
** then sqlite3_get_auxdata() returns a NULL pointer.
3434
** The sqlite3_set_auxdata() interface saves the metadata
3393
** ^The sqlite3_set_auxdata() interface saves the metadata
3435
3394
** pointed to by its 3rd parameter as the metadata for the N-th
3436
3395
** argument of the application-defined function. Subsequent
3437
3396
** calls to sqlite3_get_auxdata() might return this data, if it has
3438
3397
** not been destroyed.
3439
** If it is not NULL, SQLite will invoke the destructor
3398
** ^If it is not NULL, SQLite will invoke the destructor
3440
3399
** function given by the 4th parameter to sqlite3_set_auxdata() on
3441
3400
** the metadata when the corresponding function parameter changes
3442
3401
** or when the SQL statement completes, whichever comes first.
3444
3403
** SQLite is free to call the destructor and drop metadata on any
3445
** parameter of any function at any time. The only guarantee is that
3404
** parameter of any function at any time. ^The only guarantee is that
3446
3405
** the destructor will be called before the metadata is dropped.
3448
** In practice, metadata is preserved between function calls for
3407
** ^(In practice, metadata is preserved between function calls for
3449
3408
** expressions that are constant at compile time. This includes literal
3450
** values and SQL variables.
3409
** values and [parameters].)^
3452
3411
** These routines must be called from the same thread in which
3453
3412
** the SQL function is running.
3456
** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279]
3458
3414
SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
3459
3415
SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
3463
** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100>
3419
** CAPI3REF: Constants Defining Special Destructor Behavior
3465
3421
** These are special values for the destructor that is passed in as the
3466
** final argument to routines like [sqlite3_result_blob()]. If the destructor
3422
** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
3467
3423
** argument is SQLITE_STATIC, it means that the content pointer is constant
3468
** and will never change. It does not need to be destroyed. The
3424
** and will never change. It does not need to be destroyed. ^The
3469
3425
** SQLITE_TRANSIENT value means that the content will likely change in
3470
3426
** the near future and that SQLite should make its own private copy of
3471
3427
** the content before returning.
3489
3445
** functions used to bind values to host parameters in prepared statements.
3490
3446
** Refer to the [SQL parameter] documentation for additional information.
3492
** The sqlite3_result_blob() interface sets the result from
3448
** ^The sqlite3_result_blob() interface sets the result from
3493
3449
** an application-defined function to be the BLOB whose content is pointed
3494
3450
** to by the second parameter and which is N bytes long where N is the
3495
3451
** third parameter.
3497
** The sqlite3_result_zeroblob() interfaces set the result of
3453
** ^The sqlite3_result_zeroblob() interfaces set the result of
3498
3454
** the application-defined function to be a BLOB containing all zero
3499
3455
** bytes and N bytes in size, where N is the value of the 2nd parameter.
3501
** The sqlite3_result_double() interface sets the result from
3457
** ^The sqlite3_result_double() interface sets the result from
3502
3458
** an application-defined function to be a floating point value specified
3503
3459
** by its 2nd argument.
3505
** The sqlite3_result_error() and sqlite3_result_error16() functions
3461
** ^The sqlite3_result_error() and sqlite3_result_error16() functions
3506
3462
** cause the implemented SQL function to throw an exception.
3507
** SQLite uses the string pointed to by the
3463
** ^SQLite uses the string pointed to by the
3508
3464
** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
3509
** as the text of an error message. SQLite interprets the error
3510
** message string from sqlite3_result_error() as UTF-8. SQLite
3465
** as the text of an error message. ^SQLite interprets the error
3466
** message string from sqlite3_result_error() as UTF-8. ^SQLite
3511
3467
** interprets the string from sqlite3_result_error16() as UTF-16 in native
3512
** byte order. If the third parameter to sqlite3_result_error()
3468
** byte order. ^If the third parameter to sqlite3_result_error()
3513
3469
** or sqlite3_result_error16() is negative then SQLite takes as the error
3514
3470
** message all text up through the first zero character.
3515
** If the third parameter to sqlite3_result_error() or
3471
** ^If the third parameter to sqlite3_result_error() or
3516
3472
** sqlite3_result_error16() is non-negative then SQLite takes that many
3517
3473
** bytes (not characters) from the 2nd parameter as the error message.
3518
** The sqlite3_result_error() and sqlite3_result_error16()
3474
** ^The sqlite3_result_error() and sqlite3_result_error16()
3519
3475
** routines make a private copy of the error message text before
3520
3476
** they return. Hence, the calling function can deallocate or
3521
3477
** modify the text after they return without harm.
3522
** The sqlite3_result_error_code() function changes the error code
3523
** returned by SQLite as a result of an error in a function. By default,
3524
** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
3478
** ^The sqlite3_result_error_code() function changes the error code
3479
** returned by SQLite as a result of an error in a function. ^By default,
3480
** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
3525
3481
** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
3527
** The sqlite3_result_toobig() interface causes SQLite to throw an error
3528
** indicating that a string or BLOB is to long to represent.
3483
** ^The sqlite3_result_toobig() interface causes SQLite to throw an error
3484
** indicating that a string or BLOB is too long to represent.
3530
** The sqlite3_result_nomem() interface causes SQLite to throw an error
3486
** ^The sqlite3_result_nomem() interface causes SQLite to throw an error
3531
3487
** indicating that a memory allocation failed.
3533
** The sqlite3_result_int() interface sets the return value
3489
** ^The sqlite3_result_int() interface sets the return value
3534
3490
** of the application-defined function to be the 32-bit signed integer
3535
3491
** value given in the 2nd argument.
3536
** The sqlite3_result_int64() interface sets the return value
3492
** ^The sqlite3_result_int64() interface sets the return value
3537
3493
** of the application-defined function to be the 64-bit signed integer
3538
3494
** value given in the 2nd argument.
3540
** The sqlite3_result_null() interface sets the return value
3496
** ^The sqlite3_result_null() interface sets the return value
3541
3497
** of the application-defined function to be NULL.
3543
** The sqlite3_result_text(), sqlite3_result_text16(),
3499
** ^The sqlite3_result_text(), sqlite3_result_text16(),
3544
3500
** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
3545
3501
** set the return value of the application-defined function to be
3546
3502
** a text string which is represented as UTF-8, UTF-16 native byte order,
3547
3503
** UTF-16 little endian, or UTF-16 big endian, respectively.
3548
** SQLite takes the text result from the application from
3504
** ^SQLite takes the text result from the application from
3549
3505
** the 2nd parameter of the sqlite3_result_text* interfaces.
3550
** If the 3rd parameter to the sqlite3_result_text* interfaces
3506
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
3551
3507
** is negative, then SQLite takes result text from the 2nd parameter
3552
3508
** through the first zero character.
3553
** If the 3rd parameter to the sqlite3_result_text* interfaces
3509
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
3554
3510
** is non-negative, then as many bytes (not characters) of the text
3555
3511
** pointed to by the 2nd parameter are taken as the application-defined
3556
3512
** function result.
3557
** If the 4th parameter to the sqlite3_result_text* interfaces
3513
** ^If the 4th parameter to the sqlite3_result_text* interfaces
3558
3514
** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
3559
3515
** function as the destructor on the text or BLOB result when it has
3560
3516
** finished using that result.
3561
** If the 4th parameter to the sqlite3_result_text* interfaces or to
3517
** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
3562
3518
** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
3563
3519
** assumes that the text or BLOB result is in constant space and does not
3564
3520
** copy the content of the parameter nor call a destructor on the content
3565
3521
** when it has finished using that result.
3566
** If the 4th parameter to the sqlite3_result_text* interfaces
3522
** ^If the 4th parameter to the sqlite3_result_text* interfaces
3567
3523
** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
3568
3524
** then SQLite makes a copy of the result into space obtained from
3569
3525
** from [sqlite3_malloc()] before it returns.
3571
** The sqlite3_result_value() interface sets the result of
3527
** ^The sqlite3_result_value() interface sets the result of
3572
3528
** the application-defined function to be a copy the
3573
** [unprotected sqlite3_value] object specified by the 2nd parameter. The
3529
** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
3574
3530
** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
3575
3531
** so that the [sqlite3_value] specified in the parameter may change or
3576
3532
** be deallocated after sqlite3_result_value() returns without harm.
3577
** A [protected sqlite3_value] object may always be used where an
3533
** ^A [protected sqlite3_value] object may always be used where an
3578
3534
** [unprotected sqlite3_value] object is required, so either
3579
3535
** kind of [sqlite3_value] object can be used with this interface.
3581
3537
** If these routines are called from within the different thread
3582
3538
** than the one containing the application-defined function that received
3583
3539
** the [sqlite3_context] pointer, the results are undefined.
3586
** [H16403] [H16406] [H16409] [H16412] [H16415] [H16418] [H16421] [H16424]
3587
** [H16427] [H16430] [H16433] [H16436] [H16439] [H16442] [H16445] [H16448]
3588
** [H16451] [H16454] [H16457] [H16460] [H16463]
3590
3541
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
3591
3542
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
3810
3753
** If another thread changes the autocommit status of the database
3811
3754
** connection while this routine is running, then the return value
3812
3755
** is undefined.
3814
** Requirements: [H12931] [H12932] [H12933] [H12934]
3816
3757
SQLITE_API int sqlite3_get_autocommit(sqlite3*);
3819
** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600>
3760
** CAPI3REF: Find The Database Handle Of A Prepared Statement
3821
** The sqlite3_db_handle interface returns the [database connection] handle
3822
** to which a [prepared statement] belongs. The [database connection]
3823
** returned by sqlite3_db_handle is the same [database connection] that was the first argument
3762
** ^The sqlite3_db_handle interface returns the [database connection] handle
3763
** to which a [prepared statement] belongs. ^The [database connection]
3764
** returned by sqlite3_db_handle is the same [database connection]
3765
** that was the first argument
3824
3766
** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
3825
3767
** create the statement in the first place.
3827
** Requirements: [H13123]
3829
3769
SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
3832
** CAPI3REF: Find the next prepared statement {H13140} <S60600>
3772
** CAPI3REF: Find the next prepared statement
3834
** This interface returns a pointer to the next [prepared statement] after
3835
** pStmt associated with the [database connection] pDb. If pStmt is NULL
3774
** ^This interface returns a pointer to the next [prepared statement] after
3775
** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
3836
3776
** then this interface returns a pointer to the first prepared statement
3837
** associated with the database connection pDb. If no prepared statement
3777
** associated with the database connection pDb. ^If no prepared statement
3838
3778
** satisfies the conditions of this routine, it returns NULL.
3840
3780
** The [database connection] pointer D in a call to
3841
3781
** [sqlite3_next_stmt(D,S)] must refer to an open database
3842
3782
** connection and in particular must not be a NULL pointer.
3844
** Requirements: [H13143] [H13146] [H13149] [H13152]
3846
3784
SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
3849
** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
3787
** CAPI3REF: Commit And Rollback Notification Callbacks
3851
** The sqlite3_commit_hook() interface registers a callback
3789
** ^The sqlite3_commit_hook() interface registers a callback
3852
3790
** function to be invoked whenever a transaction is [COMMIT | committed].
3853
** Any callback set by a previous call to sqlite3_commit_hook()
3791
** ^Any callback set by a previous call to sqlite3_commit_hook()
3854
3792
** for the same database connection is overridden.
3855
** The sqlite3_rollback_hook() interface registers a callback
3793
** ^The sqlite3_rollback_hook() interface registers a callback
3856
3794
** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
3857
** Any callback set by a previous call to sqlite3_commit_hook()
3795
** ^Any callback set by a previous call to sqlite3_rollback_hook()
3858
3796
** for the same database connection is overridden.
3859
** The pArg argument is passed through to the callback.
3860
** If the callback on a commit hook function returns non-zero,
3797
** ^The pArg argument is passed through to the callback.
3798
** ^If the callback on a commit hook function returns non-zero,
3861
3799
** then the commit is converted into a rollback.
3863
** If another function was previously registered, its
3864
** pArg value is returned. Otherwise NULL is returned.
3801
** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
3802
** return the P argument from the previous call of the same function
3803
** on the same [database connection] D, or NULL for
3804
** the first call for each function on D.
3866
3806
** The callback implementation must not do anything that will modify
3867
3807
** the database connection that invoked the callback. Any actions
3871
3811
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3872
3812
** database connections for the meaning of "modify" in this paragraph.
3874
** Registering a NULL function disables the callback.
3814
** ^Registering a NULL function disables the callback.
3876
** When the commit hook callback routine returns zero, the [COMMIT]
3877
** operation is allowed to continue normally. If the commit hook
3816
** ^When the commit hook callback routine returns zero, the [COMMIT]
3817
** operation is allowed to continue normally. ^If the commit hook
3878
3818
** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
3879
** The rollback hook is invoked on a rollback that results from a commit
3819
** ^The rollback hook is invoked on a rollback that results from a commit
3880
3820
** hook returning non-zero, just as it would be with any other rollback.
3882
** For the purposes of this API, a transaction is said to have been
3822
** ^For the purposes of this API, a transaction is said to have been
3883
3823
** rolled back if an explicit "ROLLBACK" statement is executed, or
3884
3824
** an error or constraint causes an implicit rollback to occur.
3885
** The rollback callback is not invoked if a transaction is
3825
** ^The rollback callback is not invoked if a transaction is
3886
3826
** automatically rolled back because the database connection is closed.
3887
** The rollback callback is not invoked if a transaction is
3827
** ^The rollback callback is not invoked if a transaction is
3888
3828
** rolled back because a commit callback returned non-zero.
3889
** <todo> Check on this </todo>
3891
3830
** See also the [sqlite3_update_hook()] interface.
3894
** [H12951] [H12952] [H12953] [H12954] [H12955]
3895
** [H12961] [H12962] [H12963] [H12964]
3897
3832
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
3898
3833
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
3901
** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400>
3836
** CAPI3REF: Data Change Notification Callbacks
3903
** The sqlite3_update_hook() interface registers a callback function
3838
** ^The sqlite3_update_hook() interface registers a callback function
3904
3839
** with the [database connection] identified by the first argument
3905
3840
** to be invoked whenever a row is updated, inserted or deleted.
3906
** Any callback set by a previous call to this function
3841
** ^Any callback set by a previous call to this function
3907
3842
** for the same database connection is overridden.
3909
** The second argument is a pointer to the function to invoke when a
3844
** ^The second argument is a pointer to the function to invoke when a
3910
3845
** row is updated, inserted or deleted.
3911
** The first argument to the callback is a copy of the third argument
3846
** ^The first argument to the callback is a copy of the third argument
3912
3847
** to sqlite3_update_hook().
3913
** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
3848
** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
3914
3849
** or [SQLITE_UPDATE], depending on the operation that caused the callback
3915
3850
** to be invoked.
3916
** The third and fourth arguments to the callback contain pointers to the
3851
** ^The third and fourth arguments to the callback contain pointers to the
3917
3852
** database and table name containing the affected row.
3918
** The final callback parameter is the [rowid] of the row.
3919
** In the case of an update, this is the [rowid] after the update takes place.
3921
** The update hook is not invoked when internal system tables are
3922
** modified (i.e. sqlite_master and sqlite_sequence).
3924
** In the current implementation, the update hook
3853
** ^The final callback parameter is the [rowid] of the row.
3854
** ^In the case of an update, this is the [rowid] after the update takes place.
3856
** ^(The update hook is not invoked when internal system tables are
3857
** modified (i.e. sqlite_master and sqlite_sequence).)^
3859
** ^In the current implementation, the update hook
3925
3860
** is not invoked when duplication rows are deleted because of an
3926
** [ON CONFLICT | ON CONFLICT REPLACE] clause. Nor is the update hook
3861
** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
3927
3862
** invoked when rows are deleted using the [truncate optimization].
3928
3863
** The exceptions defined in this paragraph might change in a future
3929
3864
** release of SQLite.
3954
** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900>
3888
** CAPI3REF: Enable Or Disable Shared Pager Cache
3955
3889
** KEYWORDS: {shared cache}
3957
** This routine enables or disables the sharing of the database cache
3891
** ^(This routine enables or disables the sharing of the database cache
3958
3892
** and schema data structures between [database connection | connections]
3959
3893
** to the same database. Sharing is enabled if the argument is true
3960
** and disabled if the argument is false.
3894
** and disabled if the argument is false.)^
3962
** Cache sharing is enabled and disabled for an entire process.
3896
** ^Cache sharing is enabled and disabled for an entire process.
3963
3897
** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
3964
3898
** sharing was enabled or disabled for each thread separately.
3966
** The cache sharing mode set by this interface effects all subsequent
3900
** ^(The cache sharing mode set by this interface effects all subsequent
3967
3901
** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
3968
3902
** Existing database connections continue use the sharing mode
3969
** that was in effect at the time they were opened.
3971
** Virtual tables cannot be used with a shared cache. When shared
3972
** cache is enabled, the [sqlite3_create_module()] API used to register
3973
** virtual tables will always return an error.
3975
** This routine returns [SQLITE_OK] if shared cache was enabled or disabled
3976
** successfully. An [error code] is returned otherwise.
3978
** Shared cache is disabled by default. But this might change in
3903
** that was in effect at the time they were opened.)^
3905
** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
3906
** successfully. An [error code] is returned otherwise.)^
3908
** ^Shared cache is disabled by default. But this might change in
3979
3909
** future releases of SQLite. Applications that care about shared
3980
3910
** cache setting should set it explicitly.
3982
3912
** See Also: [SQLite Shared-Cache Mode]
3984
** Requirements: [H10331] [H10336] [H10337] [H10339]
3986
3914
SQLITE_API int sqlite3_enable_shared_cache(int);
3989
** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220>
3917
** CAPI3REF: Attempt To Free Heap Memory
3991
** The sqlite3_release_memory() interface attempts to free N bytes
3919
** ^The sqlite3_release_memory() interface attempts to free N bytes
3992
3920
** of heap memory by deallocating non-essential memory allocations
3993
** held by the database library. {END} Memory used to cache database
3921
** held by the database library. Memory used to cache database
3994
3922
** pages to improve performance is an example of non-essential memory.
3995
** sqlite3_release_memory() returns the number of bytes actually freed,
3923
** ^sqlite3_release_memory() returns the number of bytes actually freed,
3996
3924
** which might be more or less than the amount requested.
3998
** Requirements: [H17341] [H17342]
4000
3926
SQLITE_API int sqlite3_release_memory(int);
4003
** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220>
3929
** CAPI3REF: Impose A Limit On Heap Size
4005
** The sqlite3_soft_heap_limit() interface places a "soft" limit
3931
** ^The sqlite3_soft_heap_limit() interface places a "soft" limit
4006
3932
** on the amount of heap memory that may be allocated by SQLite.
4007
** If an internal allocation is requested that would exceed the
3933
** ^If an internal allocation is requested that would exceed the
4008
3934
** soft heap limit, [sqlite3_release_memory()] is invoked one or
4009
3935
** more times to free up some space before the allocation is performed.
4011
** The limit is called "soft", because if [sqlite3_release_memory()]
3937
** ^The limit is called "soft" because if [sqlite3_release_memory()]
4012
3938
** cannot free sufficient memory to prevent the limit from being exceeded,
4013
3939
** the memory is allocated anyway and the current operation proceeds.
4015
** A negative or zero value for N means that there is no soft heap limit and
3941
** ^A negative or zero value for N means that there is no soft heap limit and
4016
3942
** [sqlite3_release_memory()] will only be called when memory is exhausted.
4017
** The default value for the soft heap limit is zero.
3943
** ^The default value for the soft heap limit is zero.
4019
** SQLite makes a best effort to honor the soft heap limit.
3945
** ^(SQLite makes a best effort to honor the soft heap limit.
4020
3946
** But if the soft heap limit cannot be honored, execution will
4021
** continue without error or notification. This is why the limit is
3947
** continue without error or notification.)^ This is why the limit is
4022
3948
** called a "soft" limit. It is advisory only.
4024
3950
** Prior to SQLite version 3.5.0, this routine only constrained the memory
4145
** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500>
4067
** CAPI3REF: Enable Or Disable Extension Loading
4147
** So as not to open security holes in older applications that are
4069
** ^So as not to open security holes in older applications that are
4148
4070
** unprepared to deal with extension loading, and as a means of disabling
4149
4071
** extension loading while evaluating user-entered SQL, the following API
4150
4072
** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
4152
** Extension loading is off by default. See ticket #1863.
4154
** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1
4155
** to turn extension loading on and call it with onoff==0 to turn
4156
** it back off again.
4158
** {H12622} Extension loading is off by default.
4074
** ^Extension loading is off by default. See ticket #1863.
4075
** ^Call the sqlite3_enable_load_extension() routine with onoff==1
4076
** to turn extension loading on and call it with onoff==0 to turn
4077
** it back off again.
4160
4079
SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
4163
** CAPI3REF: Automatically Load An Extensions {H12640} <S20500>
4082
** CAPI3REF: Automatically Load An Extensions
4165
** This API can be invoked at program startup in order to register
4084
** ^This API can be invoked at program startup in order to register
4166
4085
** one or more statically linked extensions that will be available
4167
** to all new [database connections]. {END}
4169
** This routine stores a pointer to the extension in an array that is
4170
** obtained from [sqlite3_malloc()]. If you run a memory leak checker
4171
** on your program and it reports a leak because of this array, invoke
4172
** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
4174
** {H12641} This function registers an extension entry point that is
4175
** automatically invoked whenever a new [database connection]
4176
** is opened using [sqlite3_open()], [sqlite3_open16()],
4177
** or [sqlite3_open_v2()].
4179
** {H12642} Duplicate extensions are detected so calling this routine
4180
** multiple times with the same extension is harmless.
4182
** {H12643} This routine stores a pointer to the extension in an array
4183
** that is obtained from [sqlite3_malloc()].
4185
** {H12644} Automatic extensions apply across all threads.
4086
** to all new [database connections].
4088
** ^(This routine stores a pointer to the extension entry point
4089
** in an array that is obtained from [sqlite3_malloc()]. That memory
4090
** is deallocated by [sqlite3_reset_auto_extension()].)^
4092
** ^This function registers an extension entry point that is
4093
** automatically invoked whenever a new [database connection]
4094
** is opened using [sqlite3_open()], [sqlite3_open16()],
4095
** or [sqlite3_open_v2()].
4096
** ^Duplicate extensions are detected so calling this routine
4097
** multiple times with the same extension is harmless.
4098
** ^Automatic extensions apply across all threads.
4187
4100
SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
4190
** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500>
4192
** This function disables all previously registered automatic
4193
** extensions. {END} It undoes the effect of all prior
4194
** [sqlite3_auto_extension()] calls.
4196
** {H12661} This function disables all previously registered
4197
** automatic extensions.
4199
** {H12662} This function disables automatic extensions in all threads.
4103
** CAPI3REF: Reset Automatic Extension Loading
4105
** ^(This function disables all previously registered automatic
4106
** extensions. It undoes the effect of all prior
4107
** [sqlite3_auto_extension()] calls.)^
4109
** ^This function disables automatic extensions in all threads.
4201
4111
SQLITE_API void sqlite3_reset_auto_extension(void);
4277
4187
** inputs to xBestIndex and are read-only. xBestIndex inserts its
4278
4188
** results into the **Outputs** fields.
4280
** The aConstraint[] array records WHERE clause constraints of the form:
4190
** ^(The aConstraint[] array records WHERE clause constraints of the form:
4282
4192
** <pre>column OP expr</pre>
4284
** where OP is =, <, <=, >, or >=. The particular operator is
4285
** stored in aConstraint[].op. The index of the column is stored in
4286
** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
4194
** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
4195
** stored in aConstraint[].op.)^ ^(The index of the column is stored in
4196
** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
4287
4197
** expr on the right-hand side can be evaluated (and thus the constraint
4288
** is usable) and false if it cannot.
4198
** is usable) and false if it cannot.)^
4290
** The optimizer automatically inverts terms of the form "expr OP column"
4200
** ^The optimizer automatically inverts terms of the form "expr OP column"
4291
4201
** and makes other simplifications to the WHERE clause in an attempt to
4292
4202
** get as many WHERE clause terms into the form shown above as possible.
4293
** The aConstraint[] array only reports WHERE clause terms in the correct
4294
** form that refer to the particular virtual table being queried.
4203
** ^The aConstraint[] array only reports WHERE clause terms that are
4204
** relevant to the particular virtual table being queried.
4296
** Information about the ORDER BY clause is stored in aOrderBy[].
4297
** Each term of aOrderBy records a column of the ORDER BY clause.
4206
** ^Information about the ORDER BY clause is stored in aOrderBy[].
4207
** ^Each term of aOrderBy records a column of the ORDER BY clause.
4299
4209
** The [xBestIndex] method must fill aConstraintUsage[] with information
4300
** about what parameters to pass to xFilter. If argvIndex>0 then
4210
** about what parameters to pass to xFilter. ^If argvIndex>0 then
4301
4211
** the right-hand side of the corresponding aConstraint[] is evaluated
4302
** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
4212
** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
4303
4213
** is true, then the constraint is assumed to be fully handled by the
4304
** virtual table and is not checked again by SQLite.
4214
** virtual table and is not checked again by SQLite.)^
4306
** The idxNum and idxPtr values are recorded and passed into the
4216
** ^The idxNum and idxPtr values are recorded and passed into the
4307
4217
** [xFilter] method.
4308
** [sqlite3_free()] is used to free idxPtr if and only iff
4218
** ^[sqlite3_free()] is used to free idxPtr if and only if
4309
4219
** needToFreeIdxPtr is true.
4311
** The orderByConsumed means that output from [xFilter]/[xNext] will occur in
4221
** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
4312
4222
** the correct order to satisfy the ORDER BY clause so that no separate
4313
4223
** sorting step is required.
4315
** The estimatedCost value is an estimate of the cost of doing the
4225
** ^The estimatedCost value is an estimate of the cost of doing the
4316
4226
** particular lookup. A full scan of a table with N entries should have
4317
4227
** a cost of N. A binary search of a table of N entries should have a
4318
4228
** cost of approximately log(N).
4489
** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230>
4392
** CAPI3REF: A Handle To An Open BLOB
4490
4393
** KEYWORDS: {BLOB handle} {BLOB handles}
4492
4395
** An instance of this object represents an open BLOB on which
4493
4396
** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
4494
** Objects of this type are created by [sqlite3_blob_open()]
4397
** ^Objects of this type are created by [sqlite3_blob_open()]
4495
4398
** and destroyed by [sqlite3_blob_close()].
4496
** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
4399
** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
4497
4400
** can be used to read or write small subsections of the BLOB.
4498
** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
4401
** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
4500
4403
typedef struct sqlite3_blob sqlite3_blob;
4503
** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230>
4406
** CAPI3REF: Open A BLOB For Incremental I/O
4505
** This interfaces opens a [BLOB handle | handle] to the BLOB located
4408
** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
4506
4409
** in row iRow, column zColumn, table zTable in database zDb;
4507
4410
** in other words, the same BLOB that would be selected by:
4510
4413
** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
4513
** If the flags parameter is non-zero, then the BLOB is opened for read
4514
** and write access. If it is zero, the BLOB is opened for read access.
4515
** It is not possible to open a column that is part of an index or primary
4416
** ^If the flags parameter is non-zero, then the BLOB is opened for read
4417
** and write access. ^If it is zero, the BLOB is opened for read access.
4418
** ^It is not possible to open a column that is part of an index or primary
4516
4419
** key for writing. ^If [foreign key constraints] are enabled, it is
4517
4420
** not possible to open a column that is part of a [child key] for writing.
4519
** Note that the database name is not the filename that contains
4422
** ^Note that the database name is not the filename that contains
4520
4423
** the database but rather the symbolic name of the database that
4521
** is assigned when the database is connected using [ATTACH].
4522
** For the main database file, the database name is "main".
4523
** For TEMP tables, the database name is "temp".
4424
** appears after the AS keyword when the database is connected using [ATTACH].
4425
** ^For the main database file, the database name is "main".
4426
** ^For TEMP tables, the database name is "temp".
4525
** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
4428
** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
4526
4429
** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
4527
** to be a null pointer.
4528
** This function sets the [database connection] error code and message
4430
** to be a null pointer.)^
4431
** ^This function sets the [database connection] error code and message
4529
4432
** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
4530
** functions. Note that the *ppBlob variable is always initialized in a
4433
** functions. ^Note that the *ppBlob variable is always initialized in a
4531
4434
** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
4532
4435
** regardless of the success or failure of this routine.
4534
** If the row that a BLOB handle points to is modified by an
4437
** ^(If the row that a BLOB handle points to is modified by an
4535
4438
** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
4536
4439
** then the BLOB handle is marked as "expired".
4537
4440
** This is true if any column of the row is changed, even a column
4538
** other than the one the BLOB handle is open on.
4539
** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
4441
** other than the one the BLOB handle is open on.)^
4442
** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
4540
4443
** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
4541
** Changes written into a BLOB prior to the BLOB expiring are not
4542
** rollback by the expiration of the BLOB. Such changes will eventually
4543
** commit if the transaction continues to completion.
4444
** ^(Changes written into a BLOB prior to the BLOB expiring are not
4445
** rolled back by the expiration of the BLOB. Such changes will eventually
4446
** commit if the transaction continues to completion.)^
4545
** Use the [sqlite3_blob_bytes()] interface to determine the size of
4546
** the opened blob. The size of a blob may not be changed by this
4448
** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
4449
** the opened blob. ^The size of a blob may not be changed by this
4547
4450
** interface. Use the [UPDATE] SQL command to change the size of a
4550
** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
4453
** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
4551
4454
** and the built-in [zeroblob] SQL function can be used, if desired,
4552
4455
** to create an empty, zero-filled blob in which to read or write using
4553
4456
** this interface.
4555
4458
** To avoid a resource leak, every open [BLOB handle] should eventually
4556
4459
** be released by a call to [sqlite3_blob_close()].
4559
** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
4561
4461
SQLITE_API int sqlite3_blob_open(
4771
4655
** <li> SQLITE_MUTEX_STATIC_PRNG
4772
4656
** <li> SQLITE_MUTEX_STATIC_LRU
4773
4657
** <li> SQLITE_MUTEX_STATIC_LRU2
4776
** {H17015} The first two constants cause sqlite3_mutex_alloc() to create
4777
** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
4778
** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
4660
** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
4661
** cause sqlite3_mutex_alloc() to create
4662
** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
4663
** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
4779
4664
** The mutex implementation does not need to make a distinction
4780
4665
** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
4781
** not want to. {H17016} But SQLite will only request a recursive mutex in
4782
** cases where it really needs one. {END} If a faster non-recursive mutex
4666
** not want to. ^SQLite will only request a recursive mutex in
4667
** cases where it really needs one. ^If a faster non-recursive mutex
4783
4668
** implementation is available on the host platform, the mutex subsystem
4784
4669
** might return such a mutex in response to SQLITE_MUTEX_FAST.
4786
** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return
4787
** a pointer to a static preexisting mutex. {END} Six static mutexes are
4671
** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
4672
** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
4673
** a pointer to a static preexisting mutex. ^Six static mutexes are
4788
4674
** used by the current version of SQLite. Future versions of SQLite
4789
4675
** may add additional static mutexes. Static mutexes are for internal
4790
4676
** use by SQLite only. Applications that use SQLite mutexes should
4791
4677
** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
4792
4678
** SQLITE_MUTEX_RECURSIVE.
4794
** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
4680
** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
4795
4681
** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
4796
** returns a different mutex on every call. {H17034} But for the static
4682
** returns a different mutex on every call. ^But for the static
4797
4683
** mutex types, the same mutex is returned on every call that has
4798
4684
** the same type number.
4800
** {H17019} The sqlite3_mutex_free() routine deallocates a previously
4801
** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every
4802
** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in
4803
** use when they are deallocated. {A17022} Attempting to deallocate a static
4804
** mutex results in undefined behavior. {H17023} SQLite never deallocates
4805
** a static mutex. {END}
4686
** ^The sqlite3_mutex_free() routine deallocates a previously
4687
** allocated dynamic mutex. ^SQLite is careful to deallocate every
4688
** dynamic mutex that it allocates. The dynamic mutexes must not be in
4689
** use when they are deallocated. Attempting to deallocate a static
4690
** mutex results in undefined behavior. ^SQLite never deallocates
4807
** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
4808
** to enter a mutex. {H17024} If another thread is already within the mutex,
4693
** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
4694
** to enter a mutex. ^If another thread is already within the mutex,
4809
4695
** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
4810
** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK]
4811
** upon successful entry. {H17026} Mutexes created using
4696
** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
4697
** upon successful entry. ^(Mutexes created using
4812
4698
** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
4813
** {H17027} In such cases the,
4699
** In such cases the,
4814
4700
** mutex must be exited an equal number of times before another thread
4815
** can enter. {A17028} If the same thread tries to enter any other
4701
** can enter.)^ ^(If the same thread tries to enter any other
4816
4702
** kind of mutex more than once, the behavior is undefined.
4817
** {H17029} SQLite will never exhibit
4818
** such behavior in its own use of mutexes.
4703
** SQLite will never exhibit
4704
** such behavior in its own use of mutexes.)^
4820
** Some systems (for example, Windows 95) do not support the operation
4706
** ^(Some systems (for example, Windows 95) do not support the operation
4821
4707
** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
4822
** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses
4823
** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
4708
** will always return SQLITE_BUSY. The SQLite core only ever uses
4709
** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
4825
** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was
4826
** previously entered by the same thread. {A17032} The behavior
4711
** ^The sqlite3_mutex_leave() routine exits a mutex that was
4712
** previously entered by the same thread. ^(The behavior
4827
4713
** is undefined if the mutex is not currently entered by the
4828
** calling thread or is not currently allocated. {H17033} SQLite will
4829
** never do either. {END}
4714
** calling thread or is not currently allocated. SQLite will
4715
** never do either.)^
4831
** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
4717
** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
4832
4718
** sqlite3_mutex_leave() is a NULL pointer, then all three routines
4833
4719
** behave as no-ops.
4972
4860
#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
4975
** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000>
4863
** CAPI3REF: Retrieve the mutex for a database connection
4977
** This interface returns a pointer the [sqlite3_mutex] object that
4865
** ^This interface returns a pointer the [sqlite3_mutex] object that
4978
4866
** serializes access to the [database connection] given in the argument
4979
4867
** when the [threading mode] is Serialized.
4980
** If the [threading mode] is Single-thread or Multi-thread then this
4868
** ^If the [threading mode] is Single-thread or Multi-thread then this
4981
4869
** routine returns a NULL pointer.
4983
4871
SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
4986
** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800>
4874
** CAPI3REF: Low-Level Control Of Database Files
4988
** {H11301} The [sqlite3_file_control()] interface makes a direct call to the
4876
** ^The [sqlite3_file_control()] interface makes a direct call to the
4989
4877
** xFileControl method for the [sqlite3_io_methods] object associated
4990
** with a particular database identified by the second argument. {H11302} The
4991
** name of the database is the name assigned to the database by the
4992
** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
4993
** database. {H11303} To control the main database file, use the name "main"
4994
** or a NULL pointer. {H11304} The third and fourth parameters to this routine
4878
** with a particular database identified by the second argument. ^The
4879
** name of the database "main" for the main database or "temp" for the
4880
** TEMP database, or the name that appears after the AS keyword for
4881
** databases that are added using the [ATTACH] SQL command.
4882
** ^A NULL pointer can be used in place of "main" to refer to the
4883
** main database file.
4884
** ^The third and fourth parameters to this routine
4995
4885
** are passed directly through to the second and third parameters of
4996
** the xFileControl method. {H11305} The return value of the xFileControl
4886
** the xFileControl method. ^The return value of the xFileControl
4997
4887
** method becomes the return value of this routine.
4999
** {H11306} If the second parameter (zDbName) does not match the name of any
5000
** open database file, then SQLITE_ERROR is returned. {H11307} This error
4889
** ^If the second parameter (zDbName) does not match the name of any
4890
** open database file, then SQLITE_ERROR is returned. ^This error
5001
4891
** code is not remembered and will not be recalled by [sqlite3_errcode()]
5002
** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might
5003
** also return SQLITE_ERROR. {A11309} There is no way to distinguish between
4892
** or [sqlite3_errmsg()]. The underlying xFileControl method might
4893
** also return SQLITE_ERROR. There is no way to distinguish between
5004
4894
** an incorrect zDbName and an SQLITE_ERROR return from the underlying
5005
** xFileControl method. {END}
4895
** xFileControl method.
5007
4897
** See also: [SQLITE_FCNTL_LOCKSTATE]
5009
4899
SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
5012
** CAPI3REF: Testing Interface {H11400} <S30800>
4902
** CAPI3REF: Testing Interface
5014
** The sqlite3_test_control() interface is used to read out internal
4904
** ^The sqlite3_test_control() interface is used to read out internal
5015
4905
** state of SQLite and to inject faults into SQLite for testing
5016
** purposes. The first parameter is an operation code that determines
4906
** purposes. ^The first parameter is an operation code that determines
5017
4907
** the number, meaning, and operation of all subsequent parameters.
5019
4909
** This interface is not for use by applications. It exists solely
5098
4992
** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
5099
4993
** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
5100
4994
** this parameter. The amount returned is the sum of the allocation
5101
** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>
4995
** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
5103
** <dt>SQLITE_STATUS_MALLOC_SIZE</dt>
4997
** ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
5104
4998
** <dd>This parameter records the largest memory allocation request
5105
4999
** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
5106
5000
** internal equivalents). Only the value returned in the
5107
5001
** *pHighwater parameter to [sqlite3_status()] is of interest.
5108
** The value written into the *pCurrent parameter is undefined.</dd>
5002
** The value written into the *pCurrent parameter is undefined.</dd>)^
5110
** <dt>SQLITE_STATUS_PAGECACHE_USED</dt>
5004
** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
5111
5005
** <dd>This parameter returns the number of pages used out of the
5112
5006
** [pagecache memory allocator] that was configured using
5113
5007
** [SQLITE_CONFIG_PAGECACHE]. The
5114
** value returned is in pages, not in bytes.</dd>
5008
** value returned is in pages, not in bytes.</dd>)^
5116
** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
5010
** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
5117
5011
** <dd>This parameter returns the number of bytes of page cache
5118
5012
** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE]
5119
5013
** buffer and where forced to overflow to [sqlite3_malloc()]. The
5120
5014
** returned value includes allocations that overflowed because they
5121
5015
** where too large (they were larger than the "sz" parameter to
5122
5016
** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
5123
** no space was left in the page cache.</dd>
5017
** no space was left in the page cache.</dd>)^
5125
** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
5019
** ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
5126
5020
** <dd>This parameter records the largest memory allocation request
5127
5021
** handed to [pagecache memory allocator]. Only the value returned in the
5128
5022
** *pHighwater parameter to [sqlite3_status()] is of interest.
5129
** The value written into the *pCurrent parameter is undefined.</dd>
5023
** The value written into the *pCurrent parameter is undefined.</dd>)^
5131
** <dt>SQLITE_STATUS_SCRATCH_USED</dt>
5025
** ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
5132
5026
** <dd>This parameter returns the number of allocations used out of the
5133
5027
** [scratch memory allocator] configured using
5134
5028
** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
5135
5029
** in bytes. Since a single thread may only have one scratch allocation
5136
5030
** outstanding at time, this parameter also reports the number of threads
5137
** using scratch memory at the same time.</dd>
5031
** using scratch memory at the same time.</dd>)^
5139
** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
5033
** ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
5140
5034
** <dd>This parameter returns the number of bytes of scratch memory
5141
5035
** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH]
5142
5036
** buffer and where forced to overflow to [sqlite3_malloc()]. The values
5292
5186
** determine exactly which parts of a database file are cached and for
5295
** The contents of the sqlite3_pcache_methods structure are copied to an
5189
** ^(The contents of the sqlite3_pcache_methods structure are copied to an
5296
5190
** internal buffer by SQLite within the call to [sqlite3_config]. Hence
5297
5191
** the application may discard the parameter after the call to
5298
** [sqlite3_config()] returns.
5300
** The xInit() method is called once for each call to [sqlite3_initialize()]
5301
** (usually only once during the lifetime of the process). It is passed
5302
** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
5303
** up global structures and mutexes required by the custom page cache
5306
** The xShutdown() method is called from within [sqlite3_shutdown()],
5192
** [sqlite3_config()] returns.)^
5194
** ^The xInit() method is called once for each call to [sqlite3_initialize()]
5195
** (usually only once during the lifetime of the process). ^(The xInit()
5196
** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
5197
** ^The xInit() method can set up up global structures and/or any mutexes
5198
** required by the custom page cache implementation.
5200
** ^The xShutdown() method is called from within [sqlite3_shutdown()],
5307
5201
** if the application invokes this API. It can be used to clean up
5308
5202
** any outstanding resources before process shutdown, if required.
5310
** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
5311
** the xInit method, so the xInit method need not be threadsafe. The
5204
** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
5205
** the xInit method, so the xInit method need not be threadsafe. ^The
5312
5206
** xShutdown method is only called from [sqlite3_shutdown()] so it does
5313
5207
** not need to be threadsafe either. All other methods must be threadsafe
5314
5208
** in multithreaded applications.
5316
** SQLite will never invoke xInit() more than once without an intervening
5210
** ^SQLite will never invoke xInit() more than once without an intervening
5317
5211
** call to xShutdown().
5319
** The xCreate() method is used to construct a new cache instance. SQLite
5213
** ^The xCreate() method is used to construct a new cache instance. SQLite
5320
5214
** will typically create one cache instance for each open database file,
5321
** though this is not guaranteed. The
5215
** though this is not guaranteed. ^The
5322
5216
** first parameter, szPage, is the size in bytes of the pages that must
5323
** be allocated by the cache. szPage will not be a power of two. szPage
5217
** be allocated by the cache. ^szPage will not be a power of two. ^szPage
5324
5218
** will the page size of the database file that is to be cached plus an
5325
** increment (here called "R") of about 100 or 200. SQLite will use the
5219
** increment (here called "R") of about 100 or 200. ^SQLite will use the
5326
5220
** extra R bytes on each page to store metadata about the underlying
5327
5221
** database page on disk. The value of R depends
5328
5222
** on the SQLite version, the target platform, and how SQLite was compiled.
5329
** R is constant for a particular build of SQLite. The second argument to
5223
** ^R is constant for a particular build of SQLite. ^The second argument to
5330
5224
** xCreate(), bPurgeable, is true if the cache being created will
5331
5225
** be used to cache database pages of a file stored on disk, or
5332
** false if it is used for an in-memory database. The cache implementation
5226
** false if it is used for an in-memory database. ^The cache implementation
5333
5227
** does not have to do anything special based with the value of bPurgeable;
5334
** it is purely advisory. On a cache where bPurgeable is false, SQLite will
5228
** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
5335
5229
** never invoke xUnpin() except to deliberately delete a page.
5336
** In other words, a cache created with bPurgeable set to false will
5230
** ^In other words, a cache created with bPurgeable set to false will
5337
5231
** never contain any unpinned pages.
5339
** The xCachesize() method may be called at any time by SQLite to set the
5233
** ^(The xCachesize() method may be called at any time by SQLite to set the
5340
5234
** suggested maximum cache-size (number of pages stored by) the cache
5341
5235
** instance passed as the first argument. This is the value configured using
5342
** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
5343
** the implementation is not required to do anything with this
5236
** the SQLite "[PRAGMA cache_size]" command.)^ ^As with the bPurgeable
5237
** parameter, the implementation is not required to do anything with this
5344
5238
** value; it is advisory only.
5346
** The xPagecount() method should return the number of pages currently
5240
** ^The xPagecount() method should return the number of pages currently
5347
5241
** stored in the cache.
5349
** The xFetch() method is used to fetch a page and return a pointer to it.
5350
** A 'page', in this context, is a buffer of szPage bytes aligned at an
5351
** 8-byte boundary. The page to be fetched is determined by the key. The
5243
** ^The xFetch() method is used to fetch a page and return a pointer to it.
5244
** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
5245
** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
5352
5246
** mimimum key value is 1. After it has been retrieved using xFetch, the page
5353
5247
** is considered to be "pinned".
5355
** If the requested page is already in the page cache, then the page cache
5249
** ^If the requested page is already in the page cache, then the page cache
5356
5250
** implementation must return a pointer to the page buffer with its content
5357
** intact. If the requested page is not already in the cache, then the
5251
** intact. ^(If the requested page is not already in the cache, then the
5358
5252
** behavior of the cache implementation is determined by the value of the
5359
5253
** createFlag parameter passed to xFetch, according to the following table:
5457
5351
** the data between the two databases, and finally
5458
5352
** <li><b>sqlite3_backup_finish()</b> is called to release all resources
5459
5353
** associated with the backup operation.
5461
5355
** There should be exactly one call to sqlite3_backup_finish() for each
5462
5356
** successful call to sqlite3_backup_init().
5464
5358
** <b>sqlite3_backup_init()</b>
5466
** The first two arguments passed to [sqlite3_backup_init()] are the database
5467
** handle associated with the destination database and the database name
5468
** used to attach the destination database to the handle. The database name
5469
** is "main" for the main database, "temp" for the temporary database, or
5470
** the name specified as part of the [ATTACH] statement if the destination is
5471
** an attached database. The third and fourth arguments passed to
5472
** sqlite3_backup_init() identify the [database connection]
5473
** and database name used
5474
** to access the source database. The values passed for the source and
5475
** destination [database connection] parameters must not be the same.
5360
** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
5361
** [database connection] associated with the destination database
5362
** and the database name, respectively.
5363
** ^The database name is "main" for the main database, "temp" for the
5364
** temporary database, or the name specified after the AS keyword in
5365
** an [ATTACH] statement for an attached database.
5366
** ^The S and M arguments passed to
5367
** sqlite3_backup_init(D,N,S,M) identify the [database connection]
5368
** and database name of the source database, respectively.
5369
** ^The source and destination [database connections] (parameters S and D)
5370
** must be different or else sqlite3_backup_init(D,N,S,M) will file with
5477
** If an error occurs within sqlite3_backup_init(), then NULL is returned
5478
** and an error code and error message written into the [database connection]
5479
** passed as the first argument. They may be retrieved using the
5480
** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions.
5481
** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
5482
** returned. This pointer may be used with the sqlite3_backup_step() and
5373
** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
5374
** returned and an error code and error message are store3d in the
5375
** destination [database connection] D.
5376
** ^The error code and message for the failed call to sqlite3_backup_init()
5377
** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
5378
** [sqlite3_errmsg16()] functions.
5379
** ^A successful call to sqlite3_backup_init() returns a pointer to an
5380
** [sqlite3_backup] object.
5381
** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
5483
5382
** sqlite3_backup_finish() functions to perform the specified backup
5486
5385
** <b>sqlite3_backup_step()</b>
5488
** Function [sqlite3_backup_step()] is used to copy up to nPage pages between
5489
** the source and destination databases, where nPage is the value of the
5490
** second parameter passed to sqlite3_backup_step(). If nPage is a negative
5491
** value, all remaining source pages are copied. If the required pages are
5492
** succesfully copied, but there are still more pages to copy before the
5493
** backup is complete, it returns [SQLITE_OK]. If no error occured and there
5494
** are no more pages to copy, then [SQLITE_DONE] is returned. If an error
5495
** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and
5387
** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
5388
** the source and destination databases specified by [sqlite3_backup] object B.
5389
** ^If N is negative, all remaining source pages are copied.
5390
** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
5391
** are still more pages to be copied, then the function resturns [SQLITE_OK].
5392
** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
5393
** from source to destination, then it returns [SQLITE_DONE].
5394
** ^If an error occurs while running sqlite3_backup_step(B,N),
5395
** then an [error code] is returned. ^As well as [SQLITE_OK] and
5496
5396
** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5497
5397
** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5498
5398
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5500
** As well as the case where the destination database file was opened for
5501
** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if
5400
** ^The sqlite3_backup_step() might return [SQLITE_READONLY] if the destination
5401
** database was opened read-only or if
5502
5402
** the destination is an in-memory database with a different page size
5503
5403
** from the source database.
5505
** If sqlite3_backup_step() cannot obtain a required file-system lock, then
5405
** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
5506
5406
** the [sqlite3_busy_handler | busy-handler function]
5507
** is invoked (if one is specified). If the
5407
** is invoked (if one is specified). ^If the
5508
5408
** busy-handler returns non-zero before the lock is available, then
5509
** [SQLITE_BUSY] is returned to the caller. In this case the call to
5510
** sqlite3_backup_step() can be retried later. If the source
5409
** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
5410
** sqlite3_backup_step() can be retried later. ^If the source
5511
5411
** [database connection]
5512
5412
** is being used to write to the source database when sqlite3_backup_step()
5513
** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this
5514
** case the call to sqlite3_backup_step() can be retried later on. If
5413
** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
5414
** case the call to sqlite3_backup_step() can be retried later on. ^(If
5515
5415
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
5516
5416
** [SQLITE_READONLY] is returned, then
5517
5417
** there is no point in retrying the call to sqlite3_backup_step(). These
5518
** errors are considered fatal. At this point the application must accept
5418
** errors are considered fatal.)^ The application must accept
5519
5419
** that the backup operation has failed and pass the backup operation handle
5520
5420
** to the sqlite3_backup_finish() to release associated resources.
5522
** Following the first call to sqlite3_backup_step(), an exclusive lock is
5523
** obtained on the destination file. It is not released until either
5422
** ^The first call to sqlite3_backup_step() obtains an exclusive lock
5423
** on the destination file. ^The exclusive lock is not released until either
5524
5424
** sqlite3_backup_finish() is called or the backup operation is complete
5525
** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time
5526
** a call to sqlite3_backup_step() is made a [shared lock] is obtained on
5527
** the source database file. This lock is released before the
5528
** sqlite3_backup_step() call returns. Because the source database is not
5529
** locked between calls to sqlite3_backup_step(), it may be modified mid-way
5530
** through the backup procedure. If the source database is modified by an
5425
** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
5426
** sqlite3_backup_step() obtains a [shared lock] on the source database that
5427
** lasts for the duration of the sqlite3_backup_step() call.
5428
** ^Because the source database is not locked between calls to
5429
** sqlite3_backup_step(), the source database may be modified mid-way
5430
** through the backup process. ^If the source database is modified by an
5531
5431
** external process or via a database connection other than the one being
5532
** used by the backup operation, then the backup will be transparently
5533
** restarted by the next call to sqlite3_backup_step(). If the source
5432
** used by the backup operation, then the backup will be automatically
5433
** restarted by the next call to sqlite3_backup_step(). ^If the source
5534
5434
** database is modified by the using the same database connection as is used
5535
** by the backup operation, then the backup database is transparently
5435
** by the backup operation, then the backup database is automatically
5536
5436
** updated at the same time.
5538
5438
** <b>sqlite3_backup_finish()</b>
5540
** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the
5541
** application wishes to abandon the backup operation, the [sqlite3_backup]
5542
** object should be passed to sqlite3_backup_finish(). This releases all
5543
** resources associated with the backup operation. If sqlite3_backup_step()
5544
** has not yet returned [SQLITE_DONE], then any active write-transaction on the
5545
** destination database is rolled back. The [sqlite3_backup] object is invalid
5440
** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
5441
** application wishes to abandon the backup operation, the application
5442
** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
5443
** ^The sqlite3_backup_finish() interfaces releases all
5444
** resources associated with the [sqlite3_backup] object.
5445
** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
5446
** active write-transaction on the destination database is rolled back.
5447
** The [sqlite3_backup] object is invalid
5546
5448
** and may not be used following a call to sqlite3_backup_finish().
5548
** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error
5549
** occurred, regardless or whether or not sqlite3_backup_step() was called
5550
** a sufficient number of times to complete the backup operation. Or, if
5551
** an out-of-memory condition or IO error occured during a call to
5552
** sqlite3_backup_step() then [SQLITE_NOMEM] or an
5553
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code
5554
** is returned. In this case the error code and an error message are
5555
** written to the destination [database connection].
5450
** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
5451
** sqlite3_backup_step() errors occurred, regardless or whether or not
5452
** sqlite3_backup_step() completed.
5453
** ^If an out-of-memory condition or IO error occurred during any prior
5454
** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
5455
** sqlite3_backup_finish() returns the corresponding [error code].
5557
** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is
5558
** not a permanent error and does not affect the return value of
5457
** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
5458
** is not a permanent error and does not affect the return value of
5559
5459
** sqlite3_backup_finish().
5561
5461
** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
5563
** Each call to sqlite3_backup_step() sets two values stored internally
5564
** by an [sqlite3_backup] object. The number of pages still to be backed
5565
** up, which may be queried by sqlite3_backup_remaining(), and the total
5566
** number of pages in the source database file, which may be queried by
5567
** sqlite3_backup_pagecount().
5463
** ^Each call to sqlite3_backup_step() sets two values inside
5464
** the [sqlite3_backup] object: the number of pages still to be backed
5465
** up and the total number of pages in the source databae file.
5466
** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
5467
** retrieve these two values, respectively.
5569
** The values returned by these functions are only updated by
5570
** sqlite3_backup_step(). If the source database is modified during a backup
5469
** ^The values returned by these functions are only updated by
5470
** sqlite3_backup_step(). ^If the source database is modified during a backup
5571
5471
** operation, then the values are not updated to account for any extra
5572
5472
** pages that need to be updated or the size of the source database file
5575
5475
** <b>Concurrent Usage of Database Handles</b>
5577
** The source [database connection] may be used by the application for other
5477
** ^The source [database connection] may be used by the application for other
5578
5478
** purposes while a backup operation is underway or being initialized.
5579
** If SQLite is compiled and configured to support threadsafe database
5479
** ^If SQLite is compiled and configured to support threadsafe database
5580
5480
** connections, then the source database connection may be used concurrently
5581
5481
** from within other threads.
5583
** However, the application must guarantee that the destination database
5584
** connection handle is not passed to any other API (by any thread) after
5483
** However, the application must guarantee that the destination
5484
** [database connection] is not passed to any other API (by any thread) after
5585
5485
** sqlite3_backup_init() is called and before the corresponding call to
5586
** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
5587
** for this, if the application does use the destination [database connection]
5588
** for some other purpose during a backup operation, things may appear to
5589
** work correctly but in fact be subtly malfunctioning. Use of the
5590
** destination database connection while a backup is in progress might
5591
** also cause a mutex deadlock.
5486
** sqlite3_backup_finish(). SQLite does not currently check to see
5487
** if the application incorrectly accesses the destination [database connection]
5488
** and so no error code is reported, but the operations may malfunction
5489
** nevertheless. Use of the destination database connection while a
5490
** backup is in progress might also also cause a mutex deadlock.
5593
** Furthermore, if running in [shared cache mode], the application must
5492
** If running in [shared cache mode], the application must
5594
5493
** guarantee that the shared cache used by the destination database
5595
5494
** is not accessed while the backup is running. In practice this means
5596
** that the application must guarantee that the file-system file being
5495
** that the application must guarantee that the disk file being
5597
5496
** backed up to is not accessed by any connection within the process,
5598
5497
** not just the specific connection that was passed to sqlite3_backup_init().
5619
5518
** CAPI3REF: Unlock Notification
5620
5519
** EXPERIMENTAL
5622
** When running in shared-cache mode, a database operation may fail with
5521
** ^When running in shared-cache mode, a database operation may fail with
5623
5522
** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
5624
5523
** individual tables within the shared-cache cannot be obtained. See
5625
5524
** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
5626
** This API may be used to register a callback that SQLite will invoke
5525
** ^This API may be used to register a callback that SQLite will invoke
5627
5526
** when the connection currently holding the required lock relinquishes it.
5628
** This API is only available if the library was compiled with the
5527
** ^This API is only available if the library was compiled with the
5629
5528
** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
5631
5530
** See Also: [Using the SQLite Unlock Notification Feature].
5633
** Shared-cache locks are released when a database connection concludes
5532
** ^Shared-cache locks are released when a database connection concludes
5634
5533
** its current transaction, either by committing it or rolling it back.
5636
** When a connection (known as the blocked connection) fails to obtain a
5535
** ^When a connection (known as the blocked connection) fails to obtain a
5637
5536
** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
5638
5537
** identity of the database connection (the blocking connection) that
5639
** has locked the required resource is stored internally. After an
5538
** has locked the required resource is stored internally. ^After an
5640
5539
** application receives an SQLITE_LOCKED error, it may call the
5641
5540
** sqlite3_unlock_notify() method with the blocked connection handle as
5642
5541
** the first argument to register for a callback that will be invoked
5643
** when the blocking connections current transaction is concluded. The
5542
** when the blocking connections current transaction is concluded. ^The
5644
5543
** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
5645
5544
** call that concludes the blocking connections transaction.
5647
** If sqlite3_unlock_notify() is called in a multi-threaded application,
5546
** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
5648
5547
** there is a chance that the blocking connection will have already
5649
5548
** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
5650
5549
** If this happens, then the specified callback is invoked immediately,
5651
** from within the call to sqlite3_unlock_notify().
5550
** from within the call to sqlite3_unlock_notify().)^
5653
** If the blocked connection is attempting to obtain a write-lock on a
5552
** ^If the blocked connection is attempting to obtain a write-lock on a
5654
5553
** shared-cache table, and more than one other connection currently holds
5655
5554
** a read-lock on the same table, then SQLite arbitrarily selects one of
5656
5555
** the other connections to use as the blocking connection.
5658
** There may be at most one unlock-notify callback registered by a
5557
** ^(There may be at most one unlock-notify callback registered by a
5659
5558
** blocked connection. If sqlite3_unlock_notify() is called when the
5660
5559
** blocked connection already has a registered unlock-notify callback,
5661
** then the new callback replaces the old. If sqlite3_unlock_notify() is
5560
** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
5662
5561
** called with a NULL pointer as its second argument, then any existing
5663
** unlock-notify callback is cancelled. The blocked connections
5562
** unlock-notify callback is cancelled. ^The blocked connections
5664
5563
** unlock-notify callback may also be canceled by closing the blocked
5665
5564
** connection using [sqlite3_close()].
added
removed
ext/sqlite3/libsqlite/sqlite3.h
