amalgalite 0.9.0-x86-mswin32-60 → 0.10.0-x86-mswin32-60

Sign up to get free protection for your applications and to get access to all the features.
Files changed (41) hide show
  1. data/HISTORY +10 -1
  2. data/bin/amalgalite-pack +1 -1
  3. data/examples/bootstrap.rb +1 -1
  4. data/ext/{amalgalite3.c → amalgalite/amalgalite3.c} +0 -0
  5. data/ext/{amalgalite3.h → amalgalite/amalgalite3.h} +0 -0
  6. data/ext/{amalgalite3_blob.c → amalgalite/amalgalite3_blob.c} +0 -0
  7. data/ext/{amalgalite3_constants.c → amalgalite/amalgalite3_constants.c} +0 -0
  8. data/ext/{amalgalite3_database.c → amalgalite/amalgalite3_database.c} +28 -2
  9. data/ext/{amalgalite3_requires_bootstrap.c → amalgalite/amalgalite3_requires_bootstrap.c} +0 -0
  10. data/ext/{amalgalite3_statement.c → amalgalite/amalgalite3_statement.c} +0 -0
  11. data/ext/amalgalite/extconf.rb +36 -0
  12. data/ext/{gen_constants.rb → amalgalite/gen_constants.rb} +0 -0
  13. data/ext/{sqlite3.c → amalgalite/sqlite3.c} +9529 -7297
  14. data/ext/{sqlite3.h → amalgalite/sqlite3.h} +305 -166
  15. data/ext/{sqlite3_options.h → amalgalite/sqlite3_options.h} +0 -0
  16. data/ext/{sqlite3ext.h → amalgalite/sqlite3ext.h} +0 -0
  17. data/gemspec.rb +1 -1
  18. data/lib/amalgalite.rb +6 -0
  19. data/lib/amalgalite/1.8/amalgalite3.so +0 -0
  20. data/lib/amalgalite/1.9/amalgalite3.so +0 -0
  21. data/lib/amalgalite/database.rb +0 -1
  22. data/lib/amalgalite/sqlite3.rb +0 -1
  23. data/lib/amalgalite/sqlite3/constants.rb +0 -2
  24. data/lib/amalgalite/sqlite3/database/status.rb +0 -1
  25. data/lib/amalgalite/sqlite3/status.rb +0 -1
  26. data/lib/amalgalite/sqlite3/version.rb +0 -1
  27. data/lib/amalgalite/statement.rb +0 -1
  28. data/lib/amalgalite/type_maps/default_map.rb +0 -1
  29. data/lib/amalgalite/type_maps/storage_map.rb +0 -1
  30. data/lib/amalgalite/type_maps/text_map.rb +0 -1
  31. data/lib/amalgalite/version.rb +1 -1
  32. data/spec/aggregate_spec.rb +1 -1
  33. data/spec/function_spec.rb +8 -0
  34. data/spec/sqlite3/version_spec.rb +2 -2
  35. data/tasks/announce.rake +10 -6
  36. data/tasks/config.rb +2 -2
  37. data/tasks/distribution.rake +30 -9
  38. data/tasks/extension.rake +30 -25
  39. metadata +27 -22
  40. data/ext/extconf.rb +0 -23
  41. data/lib/amalgalite3.so +0 -0
@@ -30,7 +30,7 @@
30
30
  ** the version number) and changes its name to "sqlite3.h" as
31
31
  ** part of the build process.
32
32
  **
33
- ** @(#) $Id: sqlite.h.in,v 1.436 2009/03/20 13:15:30 drh Exp $
33
+ ** @(#) $Id: sqlite.h.in,v 1.458 2009/06/19 22:50:31 drh Exp $
34
34
  */
35
35
  #ifndef _SQLITE3_H_
36
36
  #define _SQLITE3_H_
@@ -99,8 +99,8 @@ extern "C" {
99
99
  **
100
100
  ** Requirements: [H10011] [H10014]
101
101
  */
102
- #define SQLITE_VERSION "3.6.12"
103
- #define SQLITE_VERSION_NUMBER 3006012
102
+ #define SQLITE_VERSION "3.6.16"
103
+ #define SQLITE_VERSION_NUMBER 3006016
104
104
 
105
105
  /*
106
106
  ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
@@ -382,7 +382,6 @@ int sqlite3_exec(
382
382
  #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
383
383
  #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
384
384
  #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
385
-
386
385
  #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8) )
387
386
 
388
387
  /*
@@ -393,20 +392,20 @@ int sqlite3_exec(
393
392
  ** in the 4th parameter to the xOpen method of the
394
393
  ** [sqlite3_vfs] object.
395
394
  */
396
- #define SQLITE_OPEN_READONLY 0x00000001
397
- #define SQLITE_OPEN_READWRITE 0x00000002
398
- #define SQLITE_OPEN_CREATE 0x00000004
399
- #define SQLITE_OPEN_DELETEONCLOSE 0x00000008
400
- #define SQLITE_OPEN_EXCLUSIVE 0x00000010
401
- #define SQLITE_OPEN_MAIN_DB 0x00000100
402
- #define SQLITE_OPEN_TEMP_DB 0x00000200
403
- #define SQLITE_OPEN_TRANSIENT_DB 0x00000400
404
- #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
405
- #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
406
- #define SQLITE_OPEN_SUBJOURNAL 0x00002000
407
- #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
408
- #define SQLITE_OPEN_NOMUTEX 0x00008000
409
- #define SQLITE_OPEN_FULLMUTEX 0x00010000
395
+ #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
396
+ #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
397
+ #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
398
+ #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
399
+ #define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
400
+ #define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
401
+ #define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
402
+ #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
403
+ #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
404
+ #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
405
+ #define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
406
+ #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
407
+ #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
408
+ #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
410
409
 
411
410
  /*
412
411
  ** CAPI3REF: Device Characteristics {H10240} <H11120>
@@ -462,8 +461,9 @@ int sqlite3_exec(
462
461
  **
463
462
  ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
464
463
  ** sync operation only needs to flush data to mass storage. Inode
465
- ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means
466
- ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
464
+ ** information need not be flushed. If the lower four bits of the flag
465
+ ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
466
+ ** If the lower four bits equal SQLITE_SYNC_FULL, that means
467
467
  ** to use Mac OS X style fullsync instead of fsync().
468
468
  */
469
469
  #define SQLITE_SYNC_NORMAL 0x00002
@@ -494,6 +494,12 @@ struct sqlite3_file {
494
494
  ** This object defines the methods used to perform various operations
495
495
  ** against the open file represented by the [sqlite3_file] object.
496
496
  **
497
+ ** If the xOpen method sets the sqlite3_file.pMethods element
498
+ ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
499
+ ** may be invoked even if the xOpen reported that it failed. The
500
+ ** only way to prevent a call to xClose following a failed xOpen
501
+ ** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
502
+ **
497
503
  ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
498
504
  ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
499
505
  ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
@@ -654,11 +660,11 @@ typedef struct sqlite3_mutex sqlite3_mutex;
654
660
  ** is either a NULL pointer or string obtained
655
661
  ** from xFullPathname(). SQLite further guarantees that
656
662
  ** the string will be valid and unchanged until xClose() is
657
- ** called. Because of the previous sentense,
663
+ ** called. Because of the previous sentence,
658
664
  ** the [sqlite3_file] can safely store a pointer to the
659
665
  ** filename if it needs to remember the filename for some reason.
660
666
  ** If the zFilename parameter is xOpen is a NULL pointer then xOpen
661
- ** must invite its own temporary name for the file. Whenever the
667
+ ** must invent its own temporary name for the file. Whenever the
662
668
  ** xFilename parameter is NULL it will also be the case that the
663
669
  ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
664
670
  **
@@ -702,14 +708,24 @@ typedef struct sqlite3_mutex sqlite3_mutex;
702
708
  ** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE]
703
709
  ** will be set for TEMP databases, journals and for subjournals.
704
710
  **
705
- ** The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
706
- ** for exclusive access. This flag is set for all files except
707
- ** for the main database file.
711
+ ** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
712
+ ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
713
+ ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
714
+ ** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
715
+ ** SQLITE_OPEN_CREATE, is used to indicate that file should always
716
+ ** be created, and that it is an error if it already exists.
717
+ ** It is <i>not</i> used to indicate the file should be opened
718
+ ** for exclusive access.
708
719
  **
709
720
  ** At least szOsFile bytes of memory are allocated by SQLite
710
721
  ** to hold the [sqlite3_file] structure passed as the third
711
722
  ** argument to xOpen. The xOpen method does not have to
712
- ** allocate the structure; it should just fill it in.
723
+ ** allocate the structure; it should just fill it in. Note that
724
+ ** the xOpen method must set the sqlite3_file.pMethods to either
725
+ ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
726
+ ** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
727
+ ** element will be valid after xOpen returns regardless of the success
728
+ ** or failure of the xOpen call.
713
729
  **
714
730
  ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
715
731
  ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
@@ -791,6 +807,11 @@ struct sqlite3_vfs {
791
807
  ** of sqlite3_initialize() does any initialization. All other calls
792
808
  ** are harmless no-ops.
793
809
  **
810
+ ** A call to sqlite3_shutdown() is an "effective" call if it is the first
811
+ ** call to sqlite3_shutdown() since the last sqlite3_initialize(). Only
812
+ ** an effective call to sqlite3_shutdown() does any deinitialization.
813
+ ** All other calls to sqlite3_shutdown() are harmless no-ops.
814
+ **
794
815
  ** Among other things, sqlite3_initialize() shall invoke
795
816
  ** sqlite3_os_init(). Similarly, sqlite3_shutdown()
796
817
  ** shall invoke sqlite3_os_end().
@@ -1026,12 +1047,14 @@ struct sqlite3_mem_methods {
1026
1047
  **
1027
1048
  ** <dt>SQLITE_CONFIG_SCRATCH</dt>
1028
1049
  ** <dd>This option specifies a static memory buffer that SQLite can use for
1029
- ** scratch memory. There are three arguments: A pointer to the memory, the
1030
- ** size of each scratch buffer (sz), and the number of buffers (N). The sz
1050
+ ** scratch memory. There are three arguments: A pointer an 8-byte
1051
+ ** aligned memory buffer from which the scrach allocations will be
1052
+ ** drawn, the size of each scratch allocation (sz),
1053
+ ** and the maximum number of scratch allocations (N). The sz
1031
1054
  ** argument must be a multiple of 16. The sz parameter should be a few bytes
1032
- ** larger than the actual scratch space required due internal overhead.
1033
- ** The first
1034
- ** argument should point to an allocation of at least sz*N bytes of memory.
1055
+ ** larger than the actual scratch space required due to internal overhead.
1056
+ ** The first argument should pointer to an 8-byte aligned buffer
1057
+ ** of at least sz*N bytes of memory.
1035
1058
  ** SQLite will use no more than one scratch buffer at once per thread, so
1036
1059
  ** N should be set to the expected maximum number of threads. The sz
1037
1060
  ** parameter should be 6 times the size of the largest database page size.
@@ -1045,29 +1068,37 @@ struct sqlite3_mem_methods {
1045
1068
  ** the database page cache with the default page cache implemenation.
1046
1069
  ** This configuration should not be used if an application-define page
1047
1070
  ** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1048
- ** There are three arguments to this option: A pointer to the
1071
+ ** There are three arguments to this option: A pointer to 8-byte aligned
1049
1072
  ** memory, the size of each page buffer (sz), and the number of pages (N).
1050
- ** The sz argument must be a power of two between 512 and 32768. The first
1073
+ ** The sz argument should be the size of the largest database page
1074
+ ** (a power of two between 512 and 32768) plus a little extra for each
1075
+ ** page header. The page header size is 20 to 40 bytes depending on
1076
+ ** the host architecture. It is harmless, apart from the wasted memory,
1077
+ ** to make sz a little too large. The first
1051
1078
  ** argument should point to an allocation of at least sz*N bytes of memory.
1052
1079
  ** SQLite will use the memory provided by the first argument to satisfy its
1053
1080
  ** memory needs for the first N pages that it adds to cache. If additional
1054
1081
  ** page cache memory is needed beyond what is provided by this option, then
1055
1082
  ** SQLite goes to [sqlite3_malloc()] for the additional storage space.
1056
1083
  ** The implementation might use one or more of the N buffers to hold
1057
- ** memory accounting information. </dd>
1084
+ ** memory accounting information. The pointer in the first argument must
1085
+ ** be aligned to an 8-byte boundary or subsequent behavior of SQLite
1086
+ ** will be undefined.</dd>
1058
1087
  **
1059
1088
  ** <dt>SQLITE_CONFIG_HEAP</dt>
1060
1089
  ** <dd>This option specifies a static memory buffer that SQLite will use
1061
1090
  ** for all of its dynamic memory allocation needs beyond those provided
1062
1091
  ** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
1063
- ** There are three arguments: A pointer to the memory, the number of
1064
- ** bytes in the memory buffer, and the minimum allocation size. If
1065
- ** the first pointer (the memory pointer) is NULL, then SQLite reverts
1092
+ ** There are three arguments: An 8-byte aligned pointer to the memory,
1093
+ ** the number of bytes in the memory buffer, and the minimum allocation size.
1094
+ ** If the first pointer (the memory pointer) is NULL, then SQLite reverts
1066
1095
  ** to using its default memory allocator (the system malloc() implementation),
1067
1096
  ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. If the
1068
1097
  ** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
1069
1098
  ** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
1070
- ** allocator is engaged to handle all of SQLites memory allocation needs.</dd>
1099
+ ** allocator is engaged to handle all of SQLites memory allocation needs.
1100
+ ** The first pointer (the memory pointer) must be aligned to an 8-byte
1101
+ ** boundary or subsequent behavior of SQLite will be undefined.</dd>
1071
1102
  **
1072
1103
  ** <dt>SQLITE_CONFIG_MUTEX</dt>
1073
1104
  ** <dd>This option takes a single argument which is a pointer to an
@@ -1138,9 +1169,9 @@ struct sqlite3_mem_methods {
1138
1169
  ** <dd>This option takes three additional arguments that determine the
1139
1170
  ** [lookaside memory allocator] configuration for the [database connection].
1140
1171
  ** The first argument (the third parameter to [sqlite3_db_config()] is a
1141
- ** pointer to a memory buffer to use for lookaside memory. The first
1142
- ** argument may be NULL in which case SQLite will allocate the lookaside
1143
- ** buffer itself using [sqlite3_malloc()]. The second argument is the
1172
+ ** pointer to an 8-byte aligned memory buffer to use for lookaside memory.
1173
+ ** The first argument may be NULL in which case SQLite will allocate the
1174
+ ** lookaside buffer itself using [sqlite3_malloc()]. The second argument is the
1144
1175
  ** size of each lookaside buffer slot and the third argument is the number of
1145
1176
  ** slots. The size of the buffer in the first argument must be greater than
1146
1177
  ** or equal to the product of the second and third arguments.</dd>
@@ -1218,14 +1249,18 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1218
1249
  ** triggers are not counted. Use the [sqlite3_total_changes()] function
1219
1250
  ** to find the total number of changes including changes caused by triggers.
1220
1251
  **
1252
+ ** Changes to a view that are simulated by an [INSTEAD OF trigger]
1253
+ ** are not counted. Only real table changes are counted.
1254
+ **
1221
1255
  ** A "row change" is a change to a single row of a single table
1222
1256
  ** caused by an INSERT, DELETE, or UPDATE statement. Rows that
1223
- ** are changed as side effects of REPLACE constraint resolution,
1224
- ** rollback, ABORT processing, DROP TABLE, or by any other
1257
+ ** are changed as side effects of [REPLACE] constraint resolution,
1258
+ ** rollback, ABORT processing, [DROP TABLE], or by any other
1225
1259
  ** mechanisms do not count as direct row changes.
1226
1260
  **
1227
1261
  ** A "trigger context" is a scope of execution that begins and
1228
- ** ends with the script of a trigger. Most SQL statements are
1262
+ ** ends with the script of a [CREATE TRIGGER | trigger].
1263
+ ** Most SQL statements are
1229
1264
  ** evaluated outside of any trigger. This is the "top level"
1230
1265
  ** trigger context. If a trigger fires from the top level, a
1231
1266
  ** new trigger context is entered for the duration of that one
@@ -1247,16 +1282,8 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1247
1282
  ** However, the number returned does not include changes
1248
1283
  ** caused by subtriggers since those have their own context.
1249
1284
  **
1250
- ** SQLite implements the command "DELETE FROM table" without a WHERE clause
1251
- ** by dropping and recreating the table. Doing so is much faster than going
1252
- ** through and deleting individual elements from the table. Because of this
1253
- ** optimization, the deletions in "DELETE FROM table" are not row changes and
1254
- ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1255
- ** functions, regardless of the number of elements that were originally
1256
- ** in the table. To get an accurate count of the number of rows deleted, use
1257
- ** "DELETE FROM table WHERE 1" instead. Or recompile using the
1258
- ** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
1259
- ** optimization on all queries.
1285
+ ** See also the [sqlite3_total_changes()] interface and the
1286
+ ** [count_changes pragma].
1260
1287
  **
1261
1288
  ** Requirements:
1262
1289
  ** [H12241] [H12243]
@@ -1270,27 +1297,21 @@ int sqlite3_changes(sqlite3*);
1270
1297
  /*
1271
1298
  ** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600>
1272
1299
  **
1273
- ** This function returns the number of row changes caused by INSERT,
1274
- ** UPDATE or DELETE statements since the [database connection] was opened.
1275
- ** The count includes all changes from all trigger contexts. However,
1276
- ** the count does not include changes used to implement REPLACE constraints,
1277
- ** do rollbacks or ABORT processing, or DROP table processing.
1300
+ ** This function returns the number of row changes caused by [INSERT],
1301
+ ** [UPDATE] or [DELETE] statements since the [database connection] was opened.
1302
+ ** The count includes all changes from all
1303
+ ** [CREATE TRIGGER | trigger] contexts. However,
1304
+ ** the count does not include changes used to implement [REPLACE] constraints,
1305
+ ** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
1306
+ ** count does not include rows of views that fire an [INSTEAD OF trigger],
1307
+ ** though if the INSTEAD OF trigger makes changes of its own, those changes
1308
+ ** are counted.
1278
1309
  ** The changes are counted as soon as the statement that makes them is
1279
1310
  ** completed (when the statement handle is passed to [sqlite3_reset()] or
1280
1311
  ** [sqlite3_finalize()]).
1281
1312
  **
1282
- ** SQLite implements the command "DELETE FROM table" without a WHERE clause
1283
- ** by dropping and recreating the table. (This is much faster than going
1284
- ** through and deleting individual elements from the table.) Because of this
1285
- ** optimization, the deletions in "DELETE FROM table" are not row changes and
1286
- ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1287
- ** functions, regardless of the number of elements that were originally
1288
- ** in the table. To get an accurate count of the number of rows deleted, use
1289
- ** "DELETE FROM table WHERE 1" instead. Or recompile using the
1290
- ** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
1291
- ** optimization on all queries.
1292
- **
1293
- ** See also the [sqlite3_changes()] interface.
1313
+ ** See also the [sqlite3_changes()] interface and the
1314
+ ** [count_changes pragma].
1294
1315
  **
1295
1316
  ** Requirements:
1296
1317
  ** [H12261] [H12263]
@@ -1324,8 +1345,16 @@ int sqlite3_total_changes(sqlite3*);
1324
1345
  ** that is inside an explicit transaction, then the entire transaction
1325
1346
  ** will be rolled back automatically.
1326
1347
  **
1327
- ** A call to sqlite3_interrupt() has no effect on SQL statements
1328
- ** that are started after sqlite3_interrupt() returns.
1348
+ ** The sqlite3_interrupt(D) call is in effect until all currently running
1349
+ ** SQL statements on [database connection] D complete. Any new SQL statements
1350
+ ** that are started after the sqlite3_interrupt() call and before the
1351
+ ** running statements reaches zero are interrupted as if they had been
1352
+ ** running prior to the sqlite3_interrupt() call. New SQL statements
1353
+ ** that are started after the running statement count reaches zero are
1354
+ ** not effected by the sqlite3_interrupt().
1355
+ ** A call to sqlite3_interrupt(D) that occurs when there are no running
1356
+ ** SQL statements is a no-op and has no effect on SQL statements
1357
+ ** that are started after the sqlite3_interrupt() call returns.
1329
1358
  **
1330
1359
  ** Requirements:
1331
1360
  ** [H12271] [H12272]
@@ -1338,20 +1367,30 @@ void sqlite3_interrupt(sqlite3*);
1338
1367
  /*
1339
1368
  ** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
1340
1369
  **
1341
- ** These routines are useful for command-line input to determine if the
1342
- ** currently entered text seems to form complete a SQL statement or
1370
+ ** These routines are useful during command-line input to determine if the
1371
+ ** currently entered text seems to form a complete SQL statement or
1343
1372
  ** if additional input is needed before sending the text into
1344
- ** SQLite for parsing. These routines return true if the input string
1373
+ ** SQLite for parsing. These routines return 1 if the input string
1345
1374
  ** appears to be a complete SQL statement. A statement is judged to be
1346
- ** complete if it ends with a semicolon token and is not a fragment of a
1347
- ** CREATE TRIGGER statement. Semicolons that are embedded within
1375
+ ** complete if it ends with a semicolon token and is not a prefix of a
1376
+ ** well-formed CREATE TRIGGER statement. Semicolons that are embedded within
1348
1377
  ** string literals or quoted identifier names or comments are not
1349
1378
  ** independent tokens (they are part of the token in which they are
1350
- ** embedded) and thus do not count as a statement terminator.
1379
+ ** embedded) and thus do not count as a statement terminator. Whitespace
1380
+ ** and comments that follow the final semicolon are ignored.
1381
+ **
1382
+ ** These routines return 0 if the statement is incomplete. If a
1383
+ ** memory allocation fails, then SQLITE_NOMEM is returned.
1351
1384
  **
1352
1385
  ** These routines do not parse the SQL statements thus
1353
1386
  ** will not detect syntactically incorrect SQL.
1354
1387
  **
1388
+ ** If SQLite has not been initialized using [sqlite3_initialize()] prior
1389
+ ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
1390
+ ** automatically by sqlite3_complete16(). If that initialization fails,
1391
+ ** then the return value from sqlite3_complete16() will be non-zero
1392
+ ** regardless of whether or not the input SQL is complete.
1393
+ **
1355
1394
  ** Requirements: [H10511] [H10512]
1356
1395
  **
1357
1396
  ** The input to [sqlite3_complete()] must be a zero-terminated
@@ -1779,13 +1818,7 @@ void sqlite3_randomness(int N, void *P);
1779
1818
  ** requested is ok. When the callback returns [SQLITE_DENY], the
1780
1819
  ** [sqlite3_prepare_v2()] or equivalent call that triggered the
1781
1820
  ** authorizer will fail with an error message explaining that
1782
- ** access is denied. If the authorizer code is [SQLITE_READ]
1783
- ** and the callback returns [SQLITE_IGNORE] then the
1784
- ** [prepared statement] statement is constructed to substitute
1785
- ** a NULL value in place of the table column that would have
1786
- ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
1787
- ** return can be used to deny an untrusted user access to individual
1788
- ** columns of a table.
1821
+ ** access is denied.
1789
1822
  **
1790
1823
  ** The first parameter to the authorizer callback is a copy of the third
1791
1824
  ** parameter to the sqlite3_set_authorizer() interface. The second parameter
@@ -1794,6 +1827,17 @@ void sqlite3_randomness(int N, void *P);
1794
1827
  ** to the callback are zero-terminated strings that contain additional
1795
1828
  ** details about the action to be authorized.
1796
1829
  **
1830
+ ** If the action code is [SQLITE_READ]
1831
+ ** and the callback returns [SQLITE_IGNORE] then the
1832
+ ** [prepared statement] statement is constructed to substitute
1833
+ ** a NULL value in place of the table column that would have
1834
+ ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
1835
+ ** return can be used to deny an untrusted user access to individual
1836
+ ** columns of a table.
1837
+ ** If the action code is [SQLITE_DELETE] and the callback returns
1838
+ ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
1839
+ ** [truncate optimization] is disabled and all rows are deleted individually.
1840
+ **
1797
1841
  ** An authorizer is used when [sqlite3_prepare | preparing]
1798
1842
  ** SQL statements from an untrusted source, to ensure that the SQL statements
1799
1843
  ** do not try to access data they are not allowed to see, or that they do not
@@ -1827,7 +1871,9 @@ void sqlite3_randomness(int N, void *P);
1827
1871
  **
1828
1872
  ** Note that the authorizer callback is invoked only during
1829
1873
  ** [sqlite3_prepare()] or its variants. Authorization is not
1830
- ** performed during statement evaluation in [sqlite3_step()].
1874
+ ** performed during statement evaluation in [sqlite3_step()], unless
1875
+ ** as stated in the previous paragraph, sqlite3_step() invokes
1876
+ ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
1831
1877
  **
1832
1878
  ** Requirements:
1833
1879
  ** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510]
@@ -2229,7 +2275,8 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2229
2275
  ** program using one of these routines.
2230
2276
  **
2231
2277
  ** The first argument, "db", is a [database connection] obtained from a
2232
- ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()].
2278
+ ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
2279
+ ** [sqlite3_open16()]. The database connection must not have been closed.
2233
2280
  **
2234
2281
  ** The second argument, "zSql", is the statement to be compiled, encoded
2235
2282
  ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
@@ -2246,17 +2293,18 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2246
2293
  ** is equal to the number of bytes in the input string <i>including</i>
2247
2294
  ** the nul-terminator bytes.
2248
2295
  **
2249
- ** *pzTail is made to point to the first byte past the end of the
2250
- ** first SQL statement in zSql. These routines only compile the first
2251
- ** statement in zSql, so *pzTail is left pointing to what remains
2252
- ** uncompiled.
2296
+ ** If pzTail is not NULL then *pzTail is made to point to the first byte
2297
+ ** past the end of the first SQL statement in zSql. These routines only
2298
+ ** compile the first statement in zSql, so *pzTail is left pointing to
2299
+ ** what remains uncompiled.
2253
2300
  **
2254
2301
  ** *ppStmt is left pointing to a compiled [prepared statement] that can be
2255
2302
  ** executed using [sqlite3_step()]. If there is an error, *ppStmt is set
2256
2303
  ** to NULL. If the input text contains no SQL (if the input is an empty
2257
2304
  ** string or a comment) then *ppStmt is set to NULL.
2258
- ** {A13018} The calling procedure is responsible for deleting the compiled
2305
+ ** The calling procedure is responsible for deleting the compiled
2259
2306
  ** SQL statement using [sqlite3_finalize()] after it has finished with it.
2307
+ ** ppStmt may not be NULL.
2260
2308
  **
2261
2309
  ** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned.
2262
2310
  **
@@ -3047,8 +3095,11 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
3047
3095
  **
3048
3096
  ** The third parameter (nArg)
3049
3097
  ** is the number of arguments that the SQL function or
3050
- ** aggregate takes. If this parameter is negative, then the SQL function or
3051
- ** aggregate may take any number of arguments.
3098
+ ** aggregate takes. If this parameter is -1, then the SQL function or
3099
+ ** aggregate may take any number of arguments between 0 and the limit
3100
+ ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
3101
+ ** parameter is less than -1 or greater than 127 then the behavior is
3102
+ ** undefined.
3052
3103
  **
3053
3104
  ** The fourth parameter, eTextRep, specifies what
3054
3105
  ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
@@ -3099,7 +3150,7 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
3099
3150
  ** statement in which the function is running.
3100
3151
  **
3101
3152
  ** Requirements:
3102
- ** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16124] [H16127]
3153
+ ** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16127]
3103
3154
  ** [H16130] [H16133] [H16136] [H16139] [H16142]
3104
3155
  */
3105
3156
  int sqlite3_create_function(
@@ -3481,12 +3532,14 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n);
3481
3532
  ** the name is passed as the second function argument.
3482
3533
  **
3483
3534
  ** The third argument may be one of the constants [SQLITE_UTF8],
3484
- ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
3535
+ ** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied
3485
3536
  ** routine expects to be passed pointers to strings encoded using UTF-8,
3486
3537
  ** UTF-16 little-endian, or UTF-16 big-endian, respectively. The
3487
- ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
3538
+ ** third argument might also be [SQLITE_UTF16] to indicate that the routine
3539
+ ** expects pointers to be UTF-16 strings in the native byte order, or the
3540
+ ** argument can be [SQLITE_UTF16_ALIGNED] if the
3488
3541
  ** the routine expects pointers to 16-bit word aligned strings
3489
- ** of UTF-16 in the native byte order of the host computer.
3542
+ ** of UTF-16 in the native byte order.
3490
3543
  **
3491
3544
  ** A pointer to the user supplied routine must be passed as the fifth
3492
3545
  ** argument. If it is NULL, this is the same as deleting the collation
@@ -3511,6 +3564,8 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n);
3511
3564
  ** collation creation functions or when the [database connection] is closed
3512
3565
  ** using [sqlite3_close()].
3513
3566
  **
3567
+ ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
3568
+ **
3514
3569
  ** Requirements:
3515
3570
  ** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621]
3516
3571
  ** [H16624] [H16627] [H16630]
@@ -3630,10 +3685,24 @@ int sqlite3_sleep(int);
3630
3685
  ** is a NULL pointer, then SQLite performs a search for an appropriate
3631
3686
  ** temporary file directory.
3632
3687
  **
3633
- ** It is not safe to modify this variable once a [database connection]
3634
- ** has been opened. It is intended that this variable be set once
3688
+ ** It is not safe to read or modify this variable in more than one
3689
+ ** thread at a time. It is not safe to read or modify this variable
3690
+ ** if a [database connection] is being used at the same time in a separate
3691
+ ** thread.
3692
+ ** It is intended that this variable be set once
3635
3693
  ** as part of process initialization and before any SQLite interface
3636
- ** routines have been call and remain unchanged thereafter.
3694
+ ** routines have been called and that this variable remain unchanged
3695
+ ** thereafter.
3696
+ **
3697
+ ** The [temp_store_directory pragma] may modify this variable and cause
3698
+ ** it to point to memory obtained from [sqlite3_malloc]. Furthermore,
3699
+ ** the [temp_store_directory pragma] always assumes that any string
3700
+ ** that this variable points to is held in memory obtained from
3701
+ ** [sqlite3_malloc] and the pragma may attempt to free that memory
3702
+ ** using [sqlite3_free].
3703
+ ** Hence, if this variable is modified directly, either it should be
3704
+ ** made NULL or made to point to memory obtained from [sqlite3_malloc]
3705
+ ** or else the use of the [temp_store_directory pragma] should be avoided.
3637
3706
  */
3638
3707
  SQLITE_EXTERN char *sqlite3_temp_directory;
3639
3708
 
@@ -3696,11 +3765,11 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
3696
3765
  ** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
3697
3766
  **
3698
3767
  ** The sqlite3_commit_hook() interface registers a callback
3699
- ** function to be invoked whenever a transaction is committed.
3768
+ ** function to be invoked whenever a transaction is [COMMIT | committed].
3700
3769
  ** Any callback set by a previous call to sqlite3_commit_hook()
3701
3770
  ** for the same database connection is overridden.
3702
3771
  ** The sqlite3_rollback_hook() interface registers a callback
3703
- ** function to be invoked whenever a transaction is committed.
3772
+ ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
3704
3773
  ** Any callback set by a previous call to sqlite3_commit_hook()
3705
3774
  ** for the same database connection is overridden.
3706
3775
  ** The pArg argument is passed through to the callback.
@@ -3720,6 +3789,12 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
3720
3789
  **
3721
3790
  ** Registering a NULL function disables the callback.
3722
3791
  **
3792
+ ** When the commit hook callback routine returns zero, the [COMMIT]
3793
+ ** operation is allowed to continue normally. If the commit hook
3794
+ ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
3795
+ ** The rollback hook is invoked on a rollback that results from a commit
3796
+ ** hook returning non-zero, just as it would be with any other rollback.
3797
+ **
3723
3798
  ** For the purposes of this API, a transaction is said to have been
3724
3799
  ** rolled back if an explicit "ROLLBACK" statement is executed, or
3725
3800
  ** an error or constraint causes an implicit rollback to occur.
@@ -3729,6 +3804,8 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
3729
3804
  ** rolled back because a commit callback returned non-zero.
3730
3805
  ** <todo> Check on this </todo>
3731
3806
  **
3807
+ ** See also the [sqlite3_update_hook()] interface.
3808
+ **
3732
3809
  ** Requirements:
3733
3810
  ** [H12951] [H12952] [H12953] [H12954] [H12955]
3734
3811
  ** [H12961] [H12962] [H12963] [H12964]
@@ -3760,6 +3837,13 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
3760
3837
  ** The update hook is not invoked when internal system tables are
3761
3838
  ** modified (i.e. sqlite_master and sqlite_sequence).
3762
3839
  **
3840
+ ** In the current implementation, the update hook
3841
+ ** is not invoked when duplication rows are deleted because of an
3842
+ ** [ON CONFLICT | ON CONFLICT REPLACE] clause. Nor is the update hook
3843
+ ** invoked when rows are deleted using the [truncate optimization].
3844
+ ** The exceptions defined in this paragraph might change in a future
3845
+ ** release of SQLite.
3846
+ **
3763
3847
  ** The update hook implementation must not do anything that will modify
3764
3848
  ** the database connection that invoked the update hook. Any actions
3765
3849
  ** to modify the database connection must be deferred until after the
@@ -3770,6 +3854,9 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
3770
3854
  ** If another function was previously registered, its pArg value
3771
3855
  ** is returned. Otherwise NULL is returned.
3772
3856
  **
3857
+ ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
3858
+ ** interfaces.
3859
+ **
3773
3860
  ** Requirements:
3774
3861
  ** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986]
3775
3862
  */
@@ -4050,15 +4137,20 @@ typedef struct sqlite3_module sqlite3_module;
4050
4137
 
4051
4138
  /*
4052
4139
  ** CAPI3REF: Virtual Table Object {H18000} <S20400>
4053
- ** KEYWORDS: sqlite3_module
4140
+ ** KEYWORDS: sqlite3_module {virtual table module}
4054
4141
  ** EXPERIMENTAL
4055
4142
  **
4056
- ** A module is a class of virtual tables. Each module is defined
4057
- ** by an instance of the following structure. This structure consists
4058
- ** mostly of methods for the module.
4143
+ ** This structure, sometimes called a a "virtual table module",
4144
+ ** defines the implementation of a [virtual tables].
4145
+ ** This structure consists mostly of methods for the module.
4059
4146
  **
4060
- ** This interface is experimental and is subject to change or
4061
- ** removal in future releases of SQLite.
4147
+ ** A virtual table module is created by filling in a persistent
4148
+ ** instance of this structure and passing a pointer to that instance
4149
+ ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
4150
+ ** The registration remains valid until it is replaced by a different
4151
+ ** module or until the [database connection] closes. The content
4152
+ ** of this structure must not change while it is registered with
4153
+ ** any database connection.
4062
4154
  */
4063
4155
  struct sqlite3_module {
4064
4156
  int iVersion;
@@ -4096,8 +4188,8 @@ struct sqlite3_module {
4096
4188
  ** EXPERIMENTAL
4097
4189
  **
4098
4190
  ** The sqlite3_index_info structure and its substructures is used to
4099
- ** pass information into and receive the reply from the xBestIndex
4100
- ** method of an sqlite3_module. The fields under **Inputs** are the
4191
+ ** pass information into and receive the reply from the [xBestIndex]
4192
+ ** method of a [virtual table module]. The fields under **Inputs** are the
4101
4193
  ** inputs to xBestIndex and are read-only. xBestIndex inserts its
4102
4194
  ** results into the **Outputs** fields.
4103
4195
  **
@@ -4120,17 +4212,19 @@ struct sqlite3_module {
4120
4212
  ** Information about the ORDER BY clause is stored in aOrderBy[].
4121
4213
  ** Each term of aOrderBy records a column of the ORDER BY clause.
4122
4214
  **
4123
- ** The xBestIndex method must fill aConstraintUsage[] with information
4215
+ ** The [xBestIndex] method must fill aConstraintUsage[] with information
4124
4216
  ** about what parameters to pass to xFilter. If argvIndex>0 then
4125
4217
  ** the right-hand side of the corresponding aConstraint[] is evaluated
4126
4218
  ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
4127
4219
  ** is true, then the constraint is assumed to be fully handled by the
4128
4220
  ** virtual table and is not checked again by SQLite.
4129
4221
  **
4130
- ** The idxNum and idxPtr values are recorded and passed into xFilter.
4131
- ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
4222
+ ** The idxNum and idxPtr values are recorded and passed into the
4223
+ ** [xFilter] method.
4224
+ ** [sqlite3_free()] is used to free idxPtr if and only iff
4225
+ ** needToFreeIdxPtr is true.
4132
4226
  **
4133
- ** The orderByConsumed means that output from xFilter will occur in
4227
+ ** The orderByConsumed means that output from [xFilter]/[xNext] will occur in
4134
4228
  ** the correct order to satisfy the ORDER BY clause so that no separate
4135
4229
  ** sorting step is required.
4136
4230
  **
@@ -4138,9 +4232,6 @@ struct sqlite3_module {
4138
4232
  ** particular lookup. A full scan of a table with N entries should have
4139
4233
  ** a cost of N. A binary search of a table of N entries should have a
4140
4234
  ** cost of approximately log(N).
4141
- **
4142
- ** This interface is experimental and is subject to change or
4143
- ** removal in future releases of SQLite.
4144
4235
  */
4145
4236
  struct sqlite3_index_info {
4146
4237
  /* Inputs */
@@ -4178,34 +4269,44 @@ struct sqlite3_index_info {
4178
4269
  ** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400>
4179
4270
  ** EXPERIMENTAL
4180
4271
  **
4181
- ** This routine is used to register a new module name with a
4182
- ** [database connection]. Module names must be registered before
4183
- ** creating new virtual tables on the module, or before using
4184
- ** preexisting virtual tables of the module.
4272
+ ** This routine is used to register a new [virtual table module] name.
4273
+ ** Module names must be registered before
4274
+ ** creating a new [virtual table] using the module, or before using a
4275
+ ** preexisting [virtual table] for the module.
4276
+ **
4277
+ ** The module name is registered on the [database connection] specified
4278
+ ** by the first parameter. The name of the module is given by the
4279
+ ** second parameter. The third parameter is a pointer to
4280
+ ** the implementation of the [virtual table module]. The fourth
4281
+ ** parameter is an arbitrary client data pointer that is passed through
4282
+ ** into the [xCreate] and [xConnect] methods of the virtual table module
4283
+ ** when a new virtual table is be being created or reinitialized.
4185
4284
  **
4186
- ** This interface is experimental and is subject to change or
4187
- ** removal in future releases of SQLite.
4285
+ ** This interface has exactly the same effect as calling
4286
+ ** [sqlite3_create_module_v2()] with a NULL client data destructor.
4188
4287
  */
4189
4288
  SQLITE_EXPERIMENTAL int sqlite3_create_module(
4190
4289
  sqlite3 *db, /* SQLite connection to register module with */
4191
4290
  const char *zName, /* Name of the module */
4192
- const sqlite3_module *, /* Methods for the module */
4193
- void * /* Client data for xCreate/xConnect */
4291
+ const sqlite3_module *p, /* Methods for the module */
4292
+ void *pClientData /* Client data for xCreate/xConnect */
4194
4293
  );
4195
4294
 
4196
4295
  /*
4197
4296
  ** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400>
4198
4297
  ** EXPERIMENTAL
4199
4298
  **
4200
- ** This routine is identical to the [sqlite3_create_module()] method above,
4201
- ** except that it allows a destructor function to be specified. It is
4202
- ** even more experimental than the rest of the virtual tables API.
4299
+ ** This routine is identical to the [sqlite3_create_module()] method,
4300
+ ** except that it has an extra parameter to specify
4301
+ ** a destructor function for the client data pointer. SQLite will
4302
+ ** invoke the destructor function (if it is not NULL) when SQLite
4303
+ ** no longer needs the pClientData pointer.
4203
4304
  */
4204
4305
  SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
4205
4306
  sqlite3 *db, /* SQLite connection to register module with */
4206
4307
  const char *zName, /* Name of the module */
4207
- const sqlite3_module *, /* Methods for the module */
4208
- void *, /* Client data for xCreate/xConnect */
4308
+ const sqlite3_module *p, /* Methods for the module */
4309
+ void *pClientData, /* Client data for xCreate/xConnect */
4209
4310
  void(*xDestroy)(void*) /* Module destructor function */
4210
4311
  );
4211
4312
 
@@ -4214,8 +4315,9 @@ SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
4214
4315
  ** KEYWORDS: sqlite3_vtab
4215
4316
  ** EXPERIMENTAL
4216
4317
  **
4217
- ** Every module implementation uses a subclass of the following structure
4218
- ** to describe a particular instance of the module. Each subclass will
4318
+ ** Every [virtual table module] implementation uses a subclass
4319
+ ** of the following structure to describe a particular instance
4320
+ ** of the [virtual table]. Each subclass will
4219
4321
  ** be tailored to the specific needs of the module implementation.
4220
4322
  ** The purpose of this superclass is to define certain fields that are
4221
4323
  ** common to all module implementations.
@@ -4225,13 +4327,7 @@ SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
4225
4327
  ** take care that any prior string is freed by a call to [sqlite3_free()]
4226
4328
  ** prior to assigning a new string to zErrMsg. After the error message
4227
4329
  ** is delivered up to the client application, the string will be automatically
4228
- ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
4229
- ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
4230
- ** since virtual tables are commonly implemented in loadable extensions which
4231
- ** do not have access to sqlite3MPrintf() or sqlite3Free().
4232
- **
4233
- ** This interface is experimental and is subject to change or
4234
- ** removal in future releases of SQLite.
4330
+ ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
4235
4331
  */
4236
4332
  struct sqlite3_vtab {
4237
4333
  const sqlite3_module *pModule; /* The module for this virtual table */
@@ -4242,20 +4338,21 @@ struct sqlite3_vtab {
4242
4338
 
4243
4339
  /*
4244
4340
  ** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400>
4245
- ** KEYWORDS: sqlite3_vtab_cursor
4341
+ ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
4246
4342
  ** EXPERIMENTAL
4247
4343
  **
4248
- ** Every module implementation uses a subclass of the following structure
4249
- ** to describe cursors that point into the virtual table and are used
4344
+ ** Every [virtual table module] implementation uses a subclass of the
4345
+ ** following structure to describe cursors that point into the
4346
+ ** [virtual table] and are used
4250
4347
  ** to loop through the virtual table. Cursors are created using the
4251
- ** xOpen method of the module. Each module implementation will define
4348
+ ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
4349
+ ** by the [sqlite3_module.xClose | xClose] method. Cussors are used
4350
+ ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
4351
+ ** of the module. Each module implementation will define
4252
4352
  ** the content of a cursor structure to suit its own needs.
4253
4353
  **
4254
4354
  ** This superclass exists in order to define fields of the cursor that
4255
4355
  ** are common to all implementations.
4256
- **
4257
- ** This interface is experimental and is subject to change or
4258
- ** removal in future releases of SQLite.
4259
4356
  */
4260
4357
  struct sqlite3_vtab_cursor {
4261
4358
  sqlite3_vtab *pVtab; /* Virtual table of this cursor */
@@ -4266,21 +4363,20 @@ struct sqlite3_vtab_cursor {
4266
4363
  ** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400>
4267
4364
  ** EXPERIMENTAL
4268
4365
  **
4269
- ** The xCreate and xConnect methods of a module use the following API
4366
+ ** The [xCreate] and [xConnect] methods of a
4367
+ ** [virtual table module] call this interface
4270
4368
  ** to declare the format (the names and datatypes of the columns) of
4271
4369
  ** the virtual tables they implement.
4272
- **
4273
- ** This interface is experimental and is subject to change or
4274
- ** removal in future releases of SQLite.
4275
4370
  */
4276
- SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
4371
+ SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
4277
4372
 
4278
4373
  /*
4279
4374
  ** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400>
4280
4375
  ** EXPERIMENTAL
4281
4376
  **
4282
4377
  ** Virtual tables can provide alternative implementations of functions
4283
- ** using the xFindFunction method. But global versions of those functions
4378
+ ** using the [xFindFunction] method of the [virtual table module].
4379
+ ** But global versions of those functions
4284
4380
  ** must exist in order to be overloaded.
4285
4381
  **
4286
4382
  ** This API makes sure a global version of a function with a particular
@@ -4289,10 +4385,7 @@ SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable)
4289
4385
  ** of the new function always causes an exception to be thrown. So
4290
4386
  ** the new function is not good for anything by itself. Its only
4291
4387
  ** purpose is to be a placeholder function that can be overloaded
4292
- ** by virtual tables.
4293
- **
4294
- ** This API should be considered part of the virtual table interface,
4295
- ** which is experimental and subject to change.
4388
+ ** by a [virtual table].
4296
4389
  */
4297
4390
  SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
4298
4391
 
@@ -4333,7 +4426,7 @@ typedef struct sqlite3_blob sqlite3_blob;
4333
4426
  ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
4334
4427
  ** </pre> {END}
4335
4428
  **
4336
- ** If the flags parameter is non-zero, the the BLOB is opened for read
4429
+ ** If the flags parameter is non-zero, then the BLOB is opened for read
4337
4430
  ** and write access. If it is zero, the BLOB is opened for read access.
4338
4431
  **
4339
4432
  ** Note that the database name is not the filename that contains
@@ -4343,10 +4436,13 @@ typedef struct sqlite3_blob sqlite3_blob;
4343
4436
  ** For TEMP tables, the database name is "temp".
4344
4437
  **
4345
4438
  ** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
4346
- ** to *ppBlob. Otherwise an [error code] is returned and any value written
4347
- ** to *ppBlob should not be used by the caller.
4439
+ ** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
4440
+ ** to be a null pointer.
4348
4441
  ** This function sets the [database connection] error code and message
4349
- ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
4442
+ ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
4443
+ ** functions. Note that the *ppBlob variable is always initialized in a
4444
+ ** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
4445
+ ** regardless of the success or failure of this routine.
4350
4446
  **
4351
4447
  ** If the row that a BLOB handle points to is modified by an
4352
4448
  ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
@@ -4359,6 +4455,19 @@ typedef struct sqlite3_blob sqlite3_blob;
4359
4455
  ** rollback by the expiration of the BLOB. Such changes will eventually
4360
4456
  ** commit if the transaction continues to completion.
4361
4457
  **
4458
+ ** Use the [sqlite3_blob_bytes()] interface to determine the size of
4459
+ ** the opened blob. The size of a blob may not be changed by this
4460
+ ** underface. Use the [UPDATE] SQL command to change the size of a
4461
+ ** blob.
4462
+ **
4463
+ ** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
4464
+ ** and the built-in [zeroblob] SQL function can be used, if desired,
4465
+ ** to create an empty, zero-filled blob in which to read or write using
4466
+ ** this interface.
4467
+ **
4468
+ ** To avoid a resource leak, every open [BLOB handle] should eventually
4469
+ ** be released by a call to [sqlite3_blob_close()].
4470
+ **
4362
4471
  ** Requirements:
4363
4472
  ** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
4364
4473
  */
@@ -4381,16 +4490,19 @@ int sqlite3_blob_open(
4381
4490
  ** if there are no other BLOBs, no pending prepared statements, and the
4382
4491
  ** database connection is in [autocommit mode].
4383
4492
  ** If any writes were made to the BLOB, they might be held in cache
4384
- ** until the close operation if they will fit. {END}
4493
+ ** until the close operation if they will fit.
4385
4494
  **
4386
4495
  ** Closing the BLOB often forces the changes
4387
4496
  ** out to disk and so if any I/O errors occur, they will likely occur
4388
- ** at the time when the BLOB is closed. {H17833} Any errors that occur during
4497
+ ** at the time when the BLOB is closed. Any errors that occur during
4389
4498
  ** closing are reported as a non-zero return value.
4390
4499
  **
4391
4500
  ** The BLOB is closed unconditionally. Even if this routine returns
4392
4501
  ** an error code, the BLOB is still closed.
4393
4502
  **
4503
+ ** Calling this routine with a null pointer (which as would be returned
4504
+ ** by failed call to [sqlite3_blob_open()]) is a harmless no-op.
4505
+ **
4394
4506
  ** Requirements:
4395
4507
  ** [H17833] [H17836] [H17839]
4396
4508
  */
@@ -4399,8 +4511,15 @@ int sqlite3_blob_close(sqlite3_blob *);
4399
4511
  /*
4400
4512
  ** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230>
4401
4513
  **
4402
- ** Returns the size in bytes of the BLOB accessible via the open
4403
- ** []BLOB handle] in its only argument.
4514
+ ** Returns the size in bytes of the BLOB accessible via the
4515
+ ** successfully opened [BLOB handle] in its only argument. The
4516
+ ** incremental blob I/O routines can only read or overwriting existing
4517
+ ** blob content; they cannot change the size of a blob.
4518
+ **
4519
+ ** This routine only works on a [BLOB handle] which has been created
4520
+ ** by a prior successful call to [sqlite3_blob_open()] and which has not
4521
+ ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
4522
+ ** to this routine results in undefined and probably undesirable behavior.
4404
4523
  **
4405
4524
  ** Requirements:
4406
4525
  ** [H17843]
@@ -4417,6 +4536,8 @@ int sqlite3_blob_bytes(sqlite3_blob *);
4417
4536
  ** If offset iOffset is less than N bytes from the end of the BLOB,
4418
4537
  ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is
4419
4538
  ** less than zero, [SQLITE_ERROR] is returned and no data is read.
4539
+ ** The size of the blob (and hence the maximum value of N+iOffset)
4540
+ ** can be determined using the [sqlite3_blob_bytes()] interface.
4420
4541
  **
4421
4542
  ** An attempt to read from an expired [BLOB handle] fails with an
4422
4543
  ** error code of [SQLITE_ABORT].
@@ -4424,6 +4545,13 @@ int sqlite3_blob_bytes(sqlite3_blob *);
4424
4545
  ** On success, SQLITE_OK is returned.
4425
4546
  ** Otherwise, an [error code] or an [extended error code] is returned.
4426
4547
  **
4548
+ ** This routine only works on a [BLOB handle] which has been created
4549
+ ** by a prior successful call to [sqlite3_blob_open()] and which has not
4550
+ ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
4551
+ ** to this routine results in undefined and probably undesirable behavior.
4552
+ **
4553
+ ** See also: [sqlite3_blob_write()].
4554
+ **
4427
4555
  ** Requirements:
4428
4556
  ** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868]
4429
4557
  */
@@ -4445,6 +4573,8 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
4445
4573
  ** If offset iOffset is less than N bytes from the end of the BLOB,
4446
4574
  ** [SQLITE_ERROR] is returned and no data is written. If N is
4447
4575
  ** less than zero [SQLITE_ERROR] is returned and no data is written.
4576
+ ** The size of the BLOB (and hence the maximum value of N+iOffset)
4577
+ ** can be determined using the [sqlite3_blob_bytes()] interface.
4448
4578
  **
4449
4579
  ** An attempt to write to an expired [BLOB handle] fails with an
4450
4580
  ** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred
@@ -4456,6 +4586,13 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
4456
4586
  ** On success, SQLITE_OK is returned.
4457
4587
  ** Otherwise, an [error code] or an [extended error code] is returned.
4458
4588
  **
4589
+ ** This routine only works on a [BLOB handle] which has been created
4590
+ ** by a prior successful call to [sqlite3_blob_open()] and which has not
4591
+ ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
4592
+ ** to this routine results in undefined and probably undesirable behavior.
4593
+ **
4594
+ ** See also: [sqlite3_blob_read()].
4595
+ **
4459
4596
  ** Requirements:
4460
4597
  ** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885]
4461
4598
  ** [H17888]
@@ -4806,6 +4943,8 @@ int sqlite3_test_control(int op, ...);
4806
4943
  #define SQLITE_TESTCTRL_FAULT_INSTALL 9
4807
4944
  #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
4808
4945
  #define SQLITE_TESTCTRL_PENDING_BYTE 11
4946
+ #define SQLITE_TESTCTRL_ASSERT 12
4947
+ #define SQLITE_TESTCTRL_ALWAYS 13
4809
4948
 
4810
4949
  /*
4811
4950
  ** CAPI3REF: SQLite Runtime Status {H17200} <S60200>