amalgalite 1.3.0 → 1.4.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +6 -14
- data/HISTORY.md +6 -0
- data/Rakefile +7 -7
- data/TODO.md +0 -1
- data/ext/amalgalite/c/extconf.rb +2 -1
- data/ext/amalgalite/c/sqlite3.c +33693 -19401
- data/ext/amalgalite/c/sqlite3.h +596 -213
- data/ext/amalgalite/c/sqlite3ext.h +74 -4
- data/lib/amalgalite/version.rb +1 -1
- data/spec/database_spec.rb +3 -3
- data/spec/spec_helper.rb +5 -0
- data/spec/sqlite3/version_spec.rb +10 -10
- data/spec/version_spec.rb +1 -1
- data/tasks/custom.rake +11 -8
- data/tasks/default.rake +33 -63
- data/tasks/extension.rake +2 -2
- data/tasks/this.rb +17 -20
- metadata +43 -43
data/ext/amalgalite/c/sqlite3.h
CHANGED
@@ -107,9 +107,9 @@ extern "C" {
|
|
107
107
|
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
|
108
108
|
** [sqlite_version()] and [sqlite_source_id()].
|
109
109
|
*/
|
110
|
-
#define SQLITE_VERSION "3.7.
|
111
|
-
#define SQLITE_VERSION_NUMBER
|
112
|
-
#define SQLITE_SOURCE_ID "
|
110
|
+
#define SQLITE_VERSION "3.8.7.4"
|
111
|
+
#define SQLITE_VERSION_NUMBER 3008007
|
112
|
+
#define SQLITE_SOURCE_ID "2014-12-09 01:34:36 f66f7a17b78ba617acde90fc810107f34f1a1f2e"
|
113
113
|
|
114
114
|
/*
|
115
115
|
** CAPI3REF: Run-Time Library Version Numbers
|
@@ -269,7 +269,7 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
269
269
|
**
|
270
270
|
** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
|
271
271
|
** for the [sqlite3] object.
|
272
|
-
** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
|
272
|
+
** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
|
273
273
|
** the [sqlite3] object is successfully destroyed and all associated
|
274
274
|
** resources are deallocated.
|
275
275
|
**
|
@@ -277,7 +277,7 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
277
277
|
** statements or unfinished sqlite3_backup objects then sqlite3_close()
|
278
278
|
** will leave the database connection open and return [SQLITE_BUSY].
|
279
279
|
** ^If sqlite3_close_v2() is called with unfinalized prepared statements
|
280
|
-
** and unfinished sqlite3_backups, then the database connection becomes
|
280
|
+
** and/or unfinished sqlite3_backups, then the database connection becomes
|
281
281
|
** an unusable "zombie" which will automatically be deallocated when the
|
282
282
|
** last prepared statement is finalized or the last sqlite3_backup is
|
283
283
|
** finished. The sqlite3_close_v2() interface is intended for use with
|
@@ -288,9 +288,9 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
288
288
|
** [sqlite3_blob_close | close] all [BLOB handles], and
|
289
289
|
** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
|
290
290
|
** with the [sqlite3] object prior to attempting to close the object. ^If
|
291
|
-
**
|
291
|
+
** sqlite3_close_v2() is called on a [database connection] that still has
|
292
292
|
** outstanding [prepared statements], [BLOB handles], and/or
|
293
|
-
** [sqlite3_backup] objects then it returns SQLITE_OK
|
293
|
+
** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
|
294
294
|
** of resources is deferred until all [prepared statements], [BLOB handles],
|
295
295
|
** and [sqlite3_backup] objects are also destroyed.
|
296
296
|
**
|
@@ -370,7 +370,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
|
370
370
|
** <ul>
|
371
371
|
** <li> The application must insure that the 1st parameter to sqlite3_exec()
|
372
372
|
** is a valid and open [database connection].
|
373
|
-
** <li> The application must not close [database connection] specified by
|
373
|
+
** <li> The application must not close the [database connection] specified by
|
374
374
|
** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
|
375
375
|
** <li> The application must not modify the SQL statement text passed into
|
376
376
|
** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
|
@@ -386,16 +386,14 @@ SQLITE_API int sqlite3_exec(
|
|
386
386
|
|
387
387
|
/*
|
388
388
|
** CAPI3REF: Result Codes
|
389
|
-
** KEYWORDS:
|
390
|
-
** KEYWORDS: {result code} {result codes}
|
389
|
+
** KEYWORDS: {result code definitions}
|
391
390
|
**
|
392
391
|
** Many SQLite functions return an integer result code from the set shown
|
393
392
|
** here in order to indicate success or failure.
|
394
393
|
**
|
395
394
|
** New error codes may be added in future versions of SQLite.
|
396
395
|
**
|
397
|
-
** See also: [
|
398
|
-
** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
|
396
|
+
** See also: [extended result code definitions]
|
399
397
|
*/
|
400
398
|
#define SQLITE_OK 0 /* Successful result */
|
401
399
|
/* beginning-of-error-codes */
|
@@ -425,32 +423,27 @@ SQLITE_API int sqlite3_exec(
|
|
425
423
|
#define SQLITE_FORMAT 24 /* Auxiliary database format error */
|
426
424
|
#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
|
427
425
|
#define SQLITE_NOTADB 26 /* File opened that is not a database file */
|
426
|
+
#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
|
427
|
+
#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
|
428
428
|
#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
|
429
429
|
#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
|
430
430
|
/* end-of-error-codes */
|
431
431
|
|
432
432
|
/*
|
433
433
|
** CAPI3REF: Extended Result Codes
|
434
|
-
** KEYWORDS: {extended
|
435
|
-
** KEYWORDS: {extended result code} {extended result codes}
|
434
|
+
** KEYWORDS: {extended result code definitions}
|
436
435
|
**
|
437
|
-
** In its default configuration, SQLite API routines return one of
|
438
|
-
** [
|
436
|
+
** In its default configuration, SQLite API routines return one of 30 integer
|
437
|
+
** [result codes]. However, experience has shown that many of
|
439
438
|
** these result codes are too coarse-grained. They do not provide as
|
440
439
|
** much information about problems as programmers might like. In an effort to
|
441
440
|
** address this, newer versions of SQLite (version 3.3.8 and later) include
|
442
441
|
** support for additional result codes that provide more detailed information
|
443
|
-
** about errors.
|
442
|
+
** about errors. These [extended result codes] are enabled or disabled
|
444
443
|
** on a per database connection basis using the
|
445
|
-
** [sqlite3_extended_result_codes()] API.
|
446
|
-
**
|
447
|
-
**
|
448
|
-
** One may expect the number of extended result codes will be expand
|
449
|
-
** over time. Software that uses extended result codes should expect
|
450
|
-
** to see new result codes in future releases of SQLite.
|
451
|
-
**
|
452
|
-
** The SQLITE_OK result code will never be extended. It will always
|
453
|
-
** be exactly zero.
|
444
|
+
** [sqlite3_extended_result_codes()] API. Or, the extended code for
|
445
|
+
** the most recent error can be obtained using
|
446
|
+
** [sqlite3_extended_errcode()].
|
454
447
|
*/
|
455
448
|
#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
|
456
449
|
#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
|
@@ -475,15 +468,36 @@ SQLITE_API int sqlite3_exec(
|
|
475
468
|
#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
|
476
469
|
#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
|
477
470
|
#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
|
471
|
+
#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
|
472
|
+
#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
|
473
|
+
#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
|
478
474
|
#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
|
479
475
|
#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
|
476
|
+
#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
|
480
477
|
#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
|
481
478
|
#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
|
482
479
|
#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
|
480
|
+
#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
|
483
481
|
#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
|
484
482
|
#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
|
485
483
|
#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
|
484
|
+
#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
|
485
|
+
#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
|
486
486
|
#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
|
487
|
+
#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
|
488
|
+
#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
|
489
|
+
#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
|
490
|
+
#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
|
491
|
+
#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
|
492
|
+
#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
|
493
|
+
#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
|
494
|
+
#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
|
495
|
+
#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
|
496
|
+
#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
|
497
|
+
#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
|
498
|
+
#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
|
499
|
+
#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
|
500
|
+
#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
|
487
501
|
|
488
502
|
/*
|
489
503
|
** CAPI3REF: Flags For File Open Operations
|
@@ -537,7 +551,11 @@ SQLITE_API int sqlite3_exec(
|
|
537
551
|
** after reboot following a crash or power loss, the only bytes in a
|
538
552
|
** file that were written at the application level might have changed
|
539
553
|
** and that adjacent bytes, even bytes within the same sector are
|
540
|
-
** guaranteed to be unchanged.
|
554
|
+
** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
|
555
|
+
** flag indicate that a file cannot be deleted when open. The
|
556
|
+
** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
|
557
|
+
** read-only media and cannot be changed even by processes with
|
558
|
+
** elevated privileges.
|
541
559
|
*/
|
542
560
|
#define SQLITE_IOCAP_ATOMIC 0x00000001
|
543
561
|
#define SQLITE_IOCAP_ATOMIC512 0x00000002
|
@@ -552,6 +570,7 @@ SQLITE_API int sqlite3_exec(
|
|
552
570
|
#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
|
553
571
|
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
|
554
572
|
#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
|
573
|
+
#define SQLITE_IOCAP_IMMUTABLE 0x00002000
|
555
574
|
|
556
575
|
/*
|
557
576
|
** CAPI3REF: File Locking Levels
|
@@ -658,7 +677,7 @@ struct sqlite3_file {
|
|
658
677
|
** locking strategy (for example to use dot-file locks), to inquire
|
659
678
|
** about the status of a lock, or to break stale locks. The SQLite
|
660
679
|
** core reserves all opcodes less than 100 for its own use.
|
661
|
-
** A [
|
680
|
+
** A [file control opcodes | list of opcodes] less than 100 is available.
|
662
681
|
** Applications that define a custom xFileControl method should use opcodes
|
663
682
|
** greater than 100 to avoid conflicts. VFS implementations should
|
664
683
|
** return [SQLITE_NOTFOUND] for file control opcodes that they do not
|
@@ -723,11 +742,15 @@ struct sqlite3_io_methods {
|
|
723
742
|
void (*xShmBarrier)(sqlite3_file*);
|
724
743
|
int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
|
725
744
|
/* Methods above are valid for version 2 */
|
745
|
+
int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
|
746
|
+
int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
|
747
|
+
/* Methods above are valid for version 3 */
|
726
748
|
/* Additional methods may be added in future releases */
|
727
749
|
};
|
728
750
|
|
729
751
|
/*
|
730
752
|
** CAPI3REF: Standard File Control Opcodes
|
753
|
+
** KEYWORDS: {file control opcodes} {file control opcode}
|
731
754
|
**
|
732
755
|
** These integer constants are opcodes for the xFileControl method
|
733
756
|
** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
|
@@ -765,15 +788,29 @@ struct sqlite3_io_methods {
|
|
765
788
|
** additional information.
|
766
789
|
**
|
767
790
|
** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
|
768
|
-
**
|
769
|
-
**
|
770
|
-
**
|
771
|
-
**
|
772
|
-
**
|
773
|
-
**
|
774
|
-
**
|
775
|
-
**
|
776
|
-
**
|
791
|
+
** No longer in use.
|
792
|
+
**
|
793
|
+
** <li>[[SQLITE_FCNTL_SYNC]]
|
794
|
+
** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
|
795
|
+
** sent to the VFS immediately before the xSync method is invoked on a
|
796
|
+
** database file descriptor. Or, if the xSync method is not invoked
|
797
|
+
** because the user has configured SQLite with
|
798
|
+
** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
|
799
|
+
** of the xSync method. In most cases, the pointer argument passed with
|
800
|
+
** this file-control is NULL. However, if the database file is being synced
|
801
|
+
** as part of a multi-database commit, the argument points to a nul-terminated
|
802
|
+
** string containing the transactions master-journal file name. VFSes that
|
803
|
+
** do not need this signal should silently ignore this opcode. Applications
|
804
|
+
** should not call [sqlite3_file_control()] with this opcode as doing so may
|
805
|
+
** disrupt the operation of the specialized VFSes that do require it.
|
806
|
+
**
|
807
|
+
** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
|
808
|
+
** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
|
809
|
+
** and sent to the VFS after a transaction has been committed immediately
|
810
|
+
** but before the database is unlocked. VFSes that do not need this signal
|
811
|
+
** should silently ignore this opcode. Applications should not call
|
812
|
+
** [sqlite3_file_control()] with this opcode as doing so may disrupt the
|
813
|
+
** operation of the specialized VFSes that do require it.
|
777
814
|
**
|
778
815
|
** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
|
779
816
|
** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
|
@@ -859,7 +896,8 @@ struct sqlite3_io_methods {
|
|
859
896
|
** it is able to override built-in [PRAGMA] statements.
|
860
897
|
**
|
861
898
|
** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
|
862
|
-
** ^
|
899
|
+
** ^The [SQLITE_FCNTL_BUSYHANDLER]
|
900
|
+
** file-control may be invoked by SQLite on the database file handle
|
863
901
|
** shortly after it is opened in order to provide a custom VFS with access
|
864
902
|
** to the connections busy-handler callback. The argument is of type (void **)
|
865
903
|
** - an array of two (void *) values. The first (void *) actually points
|
@@ -870,13 +908,44 @@ struct sqlite3_io_methods {
|
|
870
908
|
** current operation.
|
871
909
|
**
|
872
910
|
** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
|
873
|
-
** ^Application can invoke
|
911
|
+
** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
|
912
|
+
** to have SQLite generate a
|
874
913
|
** temporary filename using the same algorithm that is followed to generate
|
875
914
|
** temporary filenames for TEMP tables and other internal uses. The
|
876
915
|
** argument should be a char** which will be filled with the filename
|
877
916
|
** written into memory obtained from [sqlite3_malloc()]. The caller should
|
878
917
|
** invoke [sqlite3_free()] on the result to avoid a memory leak.
|
879
918
|
**
|
919
|
+
** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
|
920
|
+
** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
|
921
|
+
** maximum number of bytes that will be used for memory-mapped I/O.
|
922
|
+
** The argument is a pointer to a value of type sqlite3_int64 that
|
923
|
+
** is an advisory maximum number of bytes in the file to memory map. The
|
924
|
+
** pointer is overwritten with the old value. The limit is not changed if
|
925
|
+
** the value originally pointed to is negative, and so the current limit
|
926
|
+
** can be queried by passing in a pointer to a negative number. This
|
927
|
+
** file-control is used internally to implement [PRAGMA mmap_size].
|
928
|
+
**
|
929
|
+
** <li>[[SQLITE_FCNTL_TRACE]]
|
930
|
+
** The [SQLITE_FCNTL_TRACE] file control provides advisory information
|
931
|
+
** to the VFS about what the higher layers of the SQLite stack are doing.
|
932
|
+
** This file control is used by some VFS activity tracing [shims].
|
933
|
+
** The argument is a zero-terminated string. Higher layers in the
|
934
|
+
** SQLite stack may generate instances of this file control if
|
935
|
+
** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
|
936
|
+
**
|
937
|
+
** <li>[[SQLITE_FCNTL_HAS_MOVED]]
|
938
|
+
** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
|
939
|
+
** pointer to an integer and it writes a boolean into that integer depending
|
940
|
+
** on whether or not the file has been renamed, moved, or deleted since it
|
941
|
+
** was first opened.
|
942
|
+
**
|
943
|
+
** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
|
944
|
+
** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
|
945
|
+
** opcode causes the xFileControl method to swap the file handle with the one
|
946
|
+
** pointed to by the pArg argument. This capability is used during testing
|
947
|
+
** and only needs to be supported when SQLITE_TEST is defined.
|
948
|
+
**
|
880
949
|
** </ul>
|
881
950
|
*/
|
882
951
|
#define SQLITE_FCNTL_LOCKSTATE 1
|
@@ -895,6 +964,12 @@ struct sqlite3_io_methods {
|
|
895
964
|
#define SQLITE_FCNTL_PRAGMA 14
|
896
965
|
#define SQLITE_FCNTL_BUSYHANDLER 15
|
897
966
|
#define SQLITE_FCNTL_TEMPFILENAME 16
|
967
|
+
#define SQLITE_FCNTL_MMAP_SIZE 18
|
968
|
+
#define SQLITE_FCNTL_TRACE 19
|
969
|
+
#define SQLITE_FCNTL_HAS_MOVED 20
|
970
|
+
#define SQLITE_FCNTL_SYNC 21
|
971
|
+
#define SQLITE_FCNTL_COMMIT_PHASETWO 22
|
972
|
+
#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
|
898
973
|
|
899
974
|
/*
|
900
975
|
** CAPI3REF: Mutex Handle
|
@@ -1339,7 +1414,7 @@ SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
|
|
1339
1414
|
** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
|
1340
1415
|
** that causes the corresponding memory allocation to fail.
|
1341
1416
|
**
|
1342
|
-
** The xInit method initializes the memory allocator.
|
1417
|
+
** The xInit method initializes the memory allocator. For example,
|
1343
1418
|
** it might allocate any require mutexes or initialize internal data
|
1344
1419
|
** structures. The xShutdown method is invoked (indirectly) by
|
1345
1420
|
** [sqlite3_shutdown()] and should deallocate any resources acquired
|
@@ -1561,7 +1636,9 @@ struct sqlite3_mem_methods {
|
|
1561
1636
|
** page cache implementation into that object.)^ </dd>
|
1562
1637
|
**
|
1563
1638
|
** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
|
1564
|
-
** <dd>
|
1639
|
+
** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
|
1640
|
+
** global [error log].
|
1641
|
+
** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
|
1565
1642
|
** function with a call signature of void(*)(void*,int,const char*),
|
1566
1643
|
** and a pointer to void. ^If the function pointer is not NULL, it is
|
1567
1644
|
** invoked by [sqlite3_log()] to process each logging event. ^If the
|
@@ -1579,27 +1656,27 @@ struct sqlite3_mem_methods {
|
|
1579
1656
|
** function must be threadsafe. </dd>
|
1580
1657
|
**
|
1581
1658
|
** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
|
1582
|
-
** <dd
|
1659
|
+
** <dd>^(This option takes a single argument of type int. If non-zero, then
|
1583
1660
|
** URI handling is globally enabled. If the parameter is zero, then URI handling
|
1584
|
-
** is globally disabled. If URI handling is globally enabled, all filenames
|
1661
|
+
** is globally disabled.)^ ^If URI handling is globally enabled, all filenames
|
1585
1662
|
** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
|
1586
1663
|
** specified as part of [ATTACH] commands are interpreted as URIs, regardless
|
1587
1664
|
** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
|
1588
|
-
** connection is opened. If it is globally disabled, filenames are
|
1665
|
+
** connection is opened. ^If it is globally disabled, filenames are
|
1589
1666
|
** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
|
1590
|
-
** database connection is opened. By default, URI handling is globally
|
1667
|
+
** database connection is opened. ^(By default, URI handling is globally
|
1591
1668
|
** disabled. The default value may be changed by compiling with the
|
1592
|
-
** [SQLITE_USE_URI] symbol defined.
|
1669
|
+
** [SQLITE_USE_URI] symbol defined.)^
|
1593
1670
|
**
|
1594
1671
|
** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
|
1595
|
-
** <dd
|
1672
|
+
** <dd>^This option takes a single integer argument which is interpreted as
|
1596
1673
|
** a boolean in order to enable or disable the use of covering indices for
|
1597
|
-
** full table scans in the query optimizer. The default setting is determined
|
1674
|
+
** full table scans in the query optimizer. ^The default setting is determined
|
1598
1675
|
** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
|
1599
1676
|
** if that compile-time option is omitted.
|
1600
1677
|
** The ability to disable the use of covering indices for full table scans
|
1601
1678
|
** is because some incorrectly coded legacy applications might malfunction
|
1602
|
-
**
|
1679
|
+
** when the optimization is enabled. Providing the ability to
|
1603
1680
|
** disable the optimization allows the older, buggy application code to work
|
1604
1681
|
** without change even with newer versions of SQLite.
|
1605
1682
|
**
|
@@ -1607,12 +1684,12 @@ struct sqlite3_mem_methods {
|
|
1607
1684
|
** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
|
1608
1685
|
** <dd> These options are obsolete and should not be used by new code.
|
1609
1686
|
** They are retained for backwards compatibility but are now no-ops.
|
1610
|
-
** </
|
1687
|
+
** </dd>
|
1611
1688
|
**
|
1612
1689
|
** [[SQLITE_CONFIG_SQLLOG]]
|
1613
1690
|
** <dt>SQLITE_CONFIG_SQLLOG
|
1614
1691
|
** <dd>This option is only available if sqlite is compiled with the
|
1615
|
-
** SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first argument should
|
1692
|
+
** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
|
1616
1693
|
** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
|
1617
1694
|
** The second should be of type (void*). The callback is invoked by the library
|
1618
1695
|
** in three separate circumstances, identified by the value passed as the
|
@@ -1622,7 +1699,30 @@ struct sqlite3_mem_methods {
|
|
1622
1699
|
** fourth parameter is 1, then the SQL statement that the third parameter
|
1623
1700
|
** points to has just been executed. Or, if the fourth parameter is 2, then
|
1624
1701
|
** the connection being passed as the second parameter is being closed. The
|
1625
|
-
** third parameter is passed NULL In this case.
|
1702
|
+
** third parameter is passed NULL In this case. An example of using this
|
1703
|
+
** configuration option can be seen in the "test_sqllog.c" source file in
|
1704
|
+
** the canonical SQLite source tree.</dd>
|
1705
|
+
**
|
1706
|
+
** [[SQLITE_CONFIG_MMAP_SIZE]]
|
1707
|
+
** <dt>SQLITE_CONFIG_MMAP_SIZE
|
1708
|
+
** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
|
1709
|
+
** that are the default mmap size limit (the default setting for
|
1710
|
+
** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
|
1711
|
+
** ^The default setting can be overridden by each database connection using
|
1712
|
+
** either the [PRAGMA mmap_size] command, or by using the
|
1713
|
+
** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
|
1714
|
+
** cannot be changed at run-time. Nor may the maximum allowed mmap size
|
1715
|
+
** exceed the compile-time maximum mmap size set by the
|
1716
|
+
** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
|
1717
|
+
** ^If either argument to this option is negative, then that argument is
|
1718
|
+
** changed to its compile-time default.
|
1719
|
+
**
|
1720
|
+
** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
|
1721
|
+
** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
|
1722
|
+
** <dd>^This option is only available if SQLite is compiled for Windows
|
1723
|
+
** with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
|
1724
|
+
** SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
|
1725
|
+
** that specifies the maximum size of the created heap.
|
1626
1726
|
** </dl>
|
1627
1727
|
*/
|
1628
1728
|
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
|
@@ -1646,6 +1746,8 @@ struct sqlite3_mem_methods {
|
|
1646
1746
|
#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
|
1647
1747
|
#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
|
1648
1748
|
#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
|
1749
|
+
#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
|
1750
|
+
#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
|
1649
1751
|
|
1650
1752
|
/*
|
1651
1753
|
** CAPI3REF: Database Connection Configuration Options
|
@@ -1722,19 +1824,21 @@ SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
|
1722
1824
|
/*
|
1723
1825
|
** CAPI3REF: Last Insert Rowid
|
1724
1826
|
**
|
1725
|
-
** ^Each entry in
|
1827
|
+
** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
|
1828
|
+
** has a unique 64-bit signed
|
1726
1829
|
** integer key called the [ROWID | "rowid"]. ^The rowid is always available
|
1727
1830
|
** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
|
1728
1831
|
** names are not also used by explicitly declared columns. ^If
|
1729
1832
|
** the table has a column of type [INTEGER PRIMARY KEY] then that column
|
1730
1833
|
** is another alias for the rowid.
|
1731
1834
|
**
|
1732
|
-
** ^
|
1733
|
-
** successful [INSERT] into
|
1734
|
-
**
|
1735
|
-
**
|
1736
|
-
** ^If no successful [INSERT]s
|
1737
|
-
** have ever occurred on
|
1835
|
+
** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the
|
1836
|
+
** most recent successful [INSERT] into a rowid table or [virtual table]
|
1837
|
+
** on database connection D.
|
1838
|
+
** ^Inserts into [WITHOUT ROWID] tables are not recorded.
|
1839
|
+
** ^If no successful [INSERT]s into rowid tables
|
1840
|
+
** have ever occurred on the database connection D,
|
1841
|
+
** then sqlite3_last_insert_rowid(D) returns zero.
|
1738
1842
|
**
|
1739
1843
|
** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
|
1740
1844
|
** method, then this routine will return the [rowid] of the inserted
|
@@ -1926,27 +2030,33 @@ SQLITE_API int sqlite3_complete16(const void *sql);
|
|
1926
2030
|
/*
|
1927
2031
|
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
|
1928
2032
|
**
|
1929
|
-
** ^
|
1930
|
-
**
|
1931
|
-
**
|
2033
|
+
** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
|
2034
|
+
** that might be invoked with argument P whenever
|
2035
|
+
** an attempt is made to access a database table associated with
|
2036
|
+
** [database connection] D when another thread
|
2037
|
+
** or process has the table locked.
|
2038
|
+
** The sqlite3_busy_handler() interface is used to implement
|
2039
|
+
** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
|
1932
2040
|
**
|
1933
|
-
** ^If the busy callback is NULL, then [SQLITE_BUSY]
|
2041
|
+
** ^If the busy callback is NULL, then [SQLITE_BUSY]
|
1934
2042
|
** is returned immediately upon encountering the lock. ^If the busy callback
|
1935
2043
|
** is not NULL, then the callback might be invoked with two arguments.
|
1936
2044
|
**
|
1937
2045
|
** ^The first argument to the busy handler is a copy of the void* pointer which
|
1938
2046
|
** is the third argument to sqlite3_busy_handler(). ^The second argument to
|
1939
2047
|
** the busy handler callback is the number of times that the busy handler has
|
1940
|
-
** been invoked for
|
2048
|
+
** been invoked for the same locking event. ^If the
|
1941
2049
|
** busy callback returns 0, then no additional attempts are made to
|
1942
|
-
** access the database and [SQLITE_BUSY]
|
2050
|
+
** access the database and [SQLITE_BUSY] is returned
|
2051
|
+
** to the application.
|
1943
2052
|
** ^If the callback returns non-zero, then another attempt
|
1944
|
-
** is made to
|
2053
|
+
** is made to access the database and the cycle repeats.
|
1945
2054
|
**
|
1946
2055
|
** The presence of a busy handler does not guarantee that it will be invoked
|
1947
2056
|
** when there is lock contention. ^If SQLite determines that invoking the busy
|
1948
2057
|
** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
|
1949
|
-
**
|
2058
|
+
** to the application instead of invoking the
|
2059
|
+
** busy handler.
|
1950
2060
|
** Consider a scenario where one process is holding a read lock that
|
1951
2061
|
** it is trying to promote to a reserved lock and
|
1952
2062
|
** a second process is holding a reserved lock that it is trying
|
@@ -1960,28 +2070,15 @@ SQLITE_API int sqlite3_complete16(const void *sql);
|
|
1960
2070
|
**
|
1961
2071
|
** ^The default busy callback is NULL.
|
1962
2072
|
**
|
1963
|
-
** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
|
1964
|
-
** when SQLite is in the middle of a large transaction where all the
|
1965
|
-
** changes will not fit into the in-memory cache. SQLite will
|
1966
|
-
** already hold a RESERVED lock on the database file, but it needs
|
1967
|
-
** to promote this lock to EXCLUSIVE so that it can spill cache
|
1968
|
-
** pages into the database file without harm to concurrent
|
1969
|
-
** readers. ^If it is unable to promote the lock, then the in-memory
|
1970
|
-
** cache will be left in an inconsistent state and so the error
|
1971
|
-
** code is promoted from the relatively benign [SQLITE_BUSY] to
|
1972
|
-
** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion
|
1973
|
-
** forces an automatic rollback of the changes. See the
|
1974
|
-
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
|
1975
|
-
** CorruptionFollowingBusyError</a> wiki page for a discussion of why
|
1976
|
-
** this is important.
|
1977
|
-
**
|
1978
2073
|
** ^(There can only be a single busy handler defined for each
|
1979
2074
|
** [database connection]. Setting a new busy handler clears any
|
1980
2075
|
** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
|
1981
|
-
**
|
2076
|
+
** or evaluating [PRAGMA busy_timeout=N] will change the
|
2077
|
+
** busy handler and thus clear any previously set busy handler.
|
1982
2078
|
**
|
1983
2079
|
** The busy callback should not take any actions which modify the
|
1984
|
-
** database connection that invoked the busy handler.
|
2080
|
+
** database connection that invoked the busy handler. In other words,
|
2081
|
+
** the busy handler is not reentrant. Any such actions
|
1985
2082
|
** result in undefined behavior.
|
1986
2083
|
**
|
1987
2084
|
** A busy handler must not close the database connection
|
@@ -1997,15 +2094,17 @@ SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
|
1997
2094
|
** will sleep multiple times until at least "ms" milliseconds of sleeping
|
1998
2095
|
** have accumulated. ^After at least "ms" milliseconds of sleeping,
|
1999
2096
|
** the handler returns 0 which causes [sqlite3_step()] to return
|
2000
|
-
** [SQLITE_BUSY]
|
2097
|
+
** [SQLITE_BUSY].
|
2001
2098
|
**
|
2002
2099
|
** ^Calling this routine with an argument less than or equal to zero
|
2003
2100
|
** turns off all busy handlers.
|
2004
2101
|
**
|
2005
2102
|
** ^(There can only be a single busy handler for a particular
|
2006
|
-
** [database connection]
|
2103
|
+
** [database connection] at any given moment. If another busy handler
|
2007
2104
|
** was defined (using [sqlite3_busy_handler()]) prior to calling
|
2008
2105
|
** this routine, that other busy handler is cleared.)^
|
2106
|
+
**
|
2107
|
+
** See also: [PRAGMA busy_timeout]
|
2009
2108
|
*/
|
2010
2109
|
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
|
2011
2110
|
|
@@ -2205,6 +2304,10 @@ SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
|
|
2205
2304
|
** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
|
2206
2305
|
** a NULL pointer.
|
2207
2306
|
**
|
2307
|
+
** ^The sqlite3_malloc64(N) routine works just like
|
2308
|
+
** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
|
2309
|
+
** of a signed 32-bit integer.
|
2310
|
+
**
|
2208
2311
|
** ^Calling sqlite3_free() with a pointer previously returned
|
2209
2312
|
** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
|
2210
2313
|
** that it might be reused. ^The sqlite3_free() routine is
|
@@ -2216,24 +2319,38 @@ SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
|
|
2216
2319
|
** might result if sqlite3_free() is called with a non-NULL pointer that
|
2217
2320
|
** was not obtained from sqlite3_malloc() or sqlite3_realloc().
|
2218
2321
|
**
|
2219
|
-
** ^
|
2220
|
-
** prior memory allocation to be at least N bytes
|
2221
|
-
**
|
2222
|
-
** parameter.)^ ^ If the first parameter to sqlite3_realloc()
|
2322
|
+
** ^The sqlite3_realloc(X,N) interface attempts to resize a
|
2323
|
+
** prior memory allocation X to be at least N bytes.
|
2324
|
+
** ^If the X parameter to sqlite3_realloc(X,N)
|
2223
2325
|
** is a NULL pointer then its behavior is identical to calling
|
2224
|
-
** sqlite3_malloc(N)
|
2225
|
-
** ^If the
|
2326
|
+
** sqlite3_malloc(N).
|
2327
|
+
** ^If the N parameter to sqlite3_realloc(X,N) is zero or
|
2226
2328
|
** negative then the behavior is exactly the same as calling
|
2227
|
-
** sqlite3_free(
|
2228
|
-
** ^sqlite3_realloc() returns a pointer to a memory allocation
|
2229
|
-
** of at least N bytes in size or NULL if
|
2329
|
+
** sqlite3_free(X).
|
2330
|
+
** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
|
2331
|
+
** of at least N bytes in size or NULL if insufficient memory is available.
|
2230
2332
|
** ^If M is the size of the prior allocation, then min(N,M) bytes
|
2231
2333
|
** of the prior allocation are copied into the beginning of buffer returned
|
2232
|
-
** by sqlite3_realloc() and the prior allocation is freed.
|
2233
|
-
** ^If sqlite3_realloc() returns NULL, then the
|
2234
|
-
** is not freed.
|
2235
|
-
**
|
2236
|
-
** ^The
|
2334
|
+
** by sqlite3_realloc(X,N) and the prior allocation is freed.
|
2335
|
+
** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
|
2336
|
+
** prior allocation is not freed.
|
2337
|
+
**
|
2338
|
+
** ^The sqlite3_realloc64(X,N) interfaces works the same as
|
2339
|
+
** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
|
2340
|
+
** of a 32-bit signed integer.
|
2341
|
+
**
|
2342
|
+
** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
|
2343
|
+
** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
|
2344
|
+
** sqlite3_msize(X) returns the size of that memory allocation in bytes.
|
2345
|
+
** ^The value returned by sqlite3_msize(X) might be larger than the number
|
2346
|
+
** of bytes requested when X was allocated. ^If X is a NULL pointer then
|
2347
|
+
** sqlite3_msize(X) returns zero. If X points to something that is not
|
2348
|
+
** the beginning of memory allocation, or if it points to a formerly
|
2349
|
+
** valid memory allocation that has now been freed, then the behavior
|
2350
|
+
** of sqlite3_msize(X) is undefined and possibly harmful.
|
2351
|
+
**
|
2352
|
+
** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
|
2353
|
+
** sqlite3_malloc64(), and sqlite3_realloc64()
|
2237
2354
|
** is always aligned to at least an 8 byte boundary, or to a
|
2238
2355
|
** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
|
2239
2356
|
** option is used.
|
@@ -2261,8 +2378,11 @@ SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
|
|
2261
2378
|
** [sqlite3_free()] or [sqlite3_realloc()].
|
2262
2379
|
*/
|
2263
2380
|
SQLITE_API void *sqlite3_malloc(int);
|
2381
|
+
SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
|
2264
2382
|
SQLITE_API void *sqlite3_realloc(void*, int);
|
2383
|
+
SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
|
2265
2384
|
SQLITE_API void sqlite3_free(void*);
|
2385
|
+
SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
|
2266
2386
|
|
2267
2387
|
/*
|
2268
2388
|
** CAPI3REF: Memory Allocator Statistics
|
@@ -2300,11 +2420,13 @@ SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
|
2300
2420
|
** applications to access the same PRNG for other purposes.
|
2301
2421
|
**
|
2302
2422
|
** ^A call to this routine stores N bytes of randomness into buffer P.
|
2423
|
+
** ^If N is less than one, then P can be a NULL pointer.
|
2303
2424
|
**
|
2304
|
-
** ^
|
2305
|
-
**
|
2306
|
-
** from the xRandomness method of the default [sqlite3_vfs] object.
|
2307
|
-
** ^
|
2425
|
+
** ^If this routine has not been previously called or if the previous
|
2426
|
+
** call had N less than one, then the PRNG is seeded using randomness
|
2427
|
+
** obtained from the xRandomness method of the default [sqlite3_vfs] object.
|
2428
|
+
** ^If the previous call to this routine had an N of 1 or more then
|
2429
|
+
** the pseudo-randomness is generated
|
2308
2430
|
** internally and without recourse to the [sqlite3_vfs] xRandomness
|
2309
2431
|
** method.
|
2310
2432
|
*/
|
@@ -2405,8 +2527,8 @@ SQLITE_API int sqlite3_set_authorizer(
|
|
2405
2527
|
** [sqlite3_set_authorizer | authorizer documentation] for additional
|
2406
2528
|
** information.
|
2407
2529
|
**
|
2408
|
-
** Note that SQLITE_IGNORE is also used as a [
|
2409
|
-
** from the [sqlite3_vtab_on_conflict()] interface.
|
2530
|
+
** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
|
2531
|
+
** returned from the [sqlite3_vtab_on_conflict()] interface.
|
2410
2532
|
*/
|
2411
2533
|
#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
|
2412
2534
|
#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
|
@@ -2464,6 +2586,7 @@ SQLITE_API int sqlite3_set_authorizer(
|
|
2464
2586
|
#define SQLITE_FUNCTION 31 /* NULL Function Name */
|
2465
2587
|
#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
|
2466
2588
|
#define SQLITE_COPY 0 /* No longer used */
|
2589
|
+
#define SQLITE_RECURSIVE 33 /* NULL NULL */
|
2467
2590
|
|
2468
2591
|
/*
|
2469
2592
|
** CAPI3REF: Tracing And Profiling Functions
|
@@ -2479,6 +2602,9 @@ SQLITE_API int sqlite3_set_authorizer(
|
|
2479
2602
|
** as each triggered subprogram is entered. The callbacks for triggers
|
2480
2603
|
** contain a UTF-8 SQL comment that identifies the trigger.)^
|
2481
2604
|
**
|
2605
|
+
** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
|
2606
|
+
** the length of [bound parameter] expansion in the output of sqlite3_trace().
|
2607
|
+
**
|
2482
2608
|
** ^The callback function registered by sqlite3_profile() is invoked
|
2483
2609
|
** as each SQL statement finishes. ^The profile callback contains
|
2484
2610
|
** the original statement text and an estimate of wall-clock time
|
@@ -2504,9 +2630,10 @@ SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
|
|
2504
2630
|
** interface is to keep a GUI updated during a large query.
|
2505
2631
|
**
|
2506
2632
|
** ^The parameter P is passed through as the only parameter to the
|
2507
|
-
** callback function X. ^The parameter N is the number of
|
2633
|
+
** callback function X. ^The parameter N is the approximate number of
|
2508
2634
|
** [virtual machine instructions] that are evaluated between successive
|
2509
|
-
** invocations of the callback X.
|
2635
|
+
** invocations of the callback X. ^If N is less than one then the progress
|
2636
|
+
** handler is disabled.
|
2510
2637
|
**
|
2511
2638
|
** ^Only a single progress handler may be defined at one time per
|
2512
2639
|
** [database connection]; setting a new progress handler cancels the
|
@@ -2542,9 +2669,9 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
2542
2669
|
** an English language description of the error following a failure of any
|
2543
2670
|
** of the sqlite3_open() routines.
|
2544
2671
|
**
|
2545
|
-
** ^The default encoding
|
2546
|
-
** sqlite3_open() or sqlite3_open_v2()
|
2547
|
-
** UTF-16 in the native byte order
|
2672
|
+
** ^The default encoding will be UTF-8 for databases created using
|
2673
|
+
** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
|
2674
|
+
** created using sqlite3_open16() will be UTF-16 in the native byte order.
|
2548
2675
|
**
|
2549
2676
|
** Whether or not an error occurs when it is opened, resources
|
2550
2677
|
** associated with the [database connection] handle should be released by
|
@@ -2632,13 +2759,14 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
2632
2759
|
** then it is interpreted as an absolute path. ^If the path does not begin
|
2633
2760
|
** with a '/' (meaning that the authority section is omitted from the URI)
|
2634
2761
|
** then the path is interpreted as a relative path.
|
2635
|
-
** ^On windows, the first component of an absolute path
|
2636
|
-
** is a drive specification (e.g. "C:").
|
2762
|
+
** ^(On windows, the first component of an absolute path
|
2763
|
+
** is a drive specification (e.g. "C:").)^
|
2637
2764
|
**
|
2638
2765
|
** [[core URI query parameters]]
|
2639
2766
|
** The query component of a URI may contain parameters that are interpreted
|
2640
2767
|
** either by SQLite itself, or by a [VFS | custom VFS implementation].
|
2641
|
-
** SQLite
|
2768
|
+
** SQLite and its built-in [VFSes] interpret the
|
2769
|
+
** following query parameters:
|
2642
2770
|
**
|
2643
2771
|
** <ul>
|
2644
2772
|
** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
|
@@ -2670,8 +2798,30 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
2670
2798
|
** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
|
2671
2799
|
** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
|
2672
2800
|
** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
|
2673
|
-
** a URI filename, its value overrides any
|
2801
|
+
** a URI filename, its value overrides any behavior requested by setting
|
2674
2802
|
** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
|
2803
|
+
**
|
2804
|
+
** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
|
2805
|
+
** [powersafe overwrite] property does or does not apply to the
|
2806
|
+
** storage media on which the database file resides.
|
2807
|
+
**
|
2808
|
+
** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
|
2809
|
+
** which if set disables file locking in rollback journal modes. This
|
2810
|
+
** is useful for accessing a database on a filesystem that does not
|
2811
|
+
** support locking. Caution: Database corruption might result if two
|
2812
|
+
** or more processes write to the same database and any one of those
|
2813
|
+
** processes uses nolock=1.
|
2814
|
+
**
|
2815
|
+
** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
|
2816
|
+
** parameter that indicates that the database file is stored on
|
2817
|
+
** read-only media. ^When immutable is set, SQLite assumes that the
|
2818
|
+
** database file cannot be changed, even by a process with higher
|
2819
|
+
** privilege, and so the database is opened read-only and all locking
|
2820
|
+
** and change detection is disabled. Caution: Setting the immutable
|
2821
|
+
** property on a database file that does in fact change can result
|
2822
|
+
** in incorrect query results and/or [SQLITE_CORRUPT] errors.
|
2823
|
+
** See also: [SQLITE_IOCAP_IMMUTABLE].
|
2824
|
+
**
|
2675
2825
|
** </ul>
|
2676
2826
|
**
|
2677
2827
|
** ^Specifying an unknown parameter in the query component of a URI is not an
|
@@ -2701,8 +2851,9 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
2701
2851
|
** Open file "data.db" in the current directory for read-only access.
|
2702
2852
|
** Regardless of whether or not shared-cache mode is enabled by
|
2703
2853
|
** default, use a private cache.
|
2704
|
-
** <tr><td> file:/home/fred/data.db?vfs=unix-
|
2705
|
-
** Open file "/home/fred/data.db". Use the special VFS "unix-
|
2854
|
+
** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
|
2855
|
+
** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
|
2856
|
+
** that uses dot-files in place of posix advisory locking.
|
2706
2857
|
** <tr><td> file:data.db?mode=readonly <td>
|
2707
2858
|
** An error. "readonly" is not a valid option for the "mode" parameter.
|
2708
2859
|
** </table>
|
@@ -2948,6 +3099,10 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
|
2948
3099
|
**
|
2949
3100
|
** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
|
2950
3101
|
** <dd>The maximum depth of recursion for triggers.</dd>)^
|
3102
|
+
**
|
3103
|
+
** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
|
3104
|
+
** <dd>The maximum number of auxiliary worker threads that a single
|
3105
|
+
** [prepared statement] may start.</dd>)^
|
2951
3106
|
** </dl>
|
2952
3107
|
*/
|
2953
3108
|
#define SQLITE_LIMIT_LENGTH 0
|
@@ -2961,6 +3116,7 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
|
2961
3116
|
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
|
2962
3117
|
#define SQLITE_LIMIT_VARIABLE_NUMBER 9
|
2963
3118
|
#define SQLITE_LIMIT_TRIGGER_DEPTH 10
|
3119
|
+
#define SQLITE_LIMIT_WORKER_THREADS 11
|
2964
3120
|
|
2965
3121
|
/*
|
2966
3122
|
** CAPI3REF: Compiling An SQL Statement
|
@@ -3017,7 +3173,8 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3017
3173
|
** <li>
|
3018
3174
|
** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
|
3019
3175
|
** always used to do, [sqlite3_step()] will automatically recompile the SQL
|
3020
|
-
** statement and try to run it again.
|
3176
|
+
** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
|
3177
|
+
** retries will occur before sqlite3_step() gives up and returns an error.
|
3021
3178
|
** </li>
|
3022
3179
|
**
|
3023
3180
|
** <li>
|
@@ -3039,7 +3196,6 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3039
3196
|
** choice of query plan if the parameter is the left-hand side of a [LIKE]
|
3040
3197
|
** or [GLOB] operator or if the parameter is compared to an indexed column
|
3041
3198
|
** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
|
3042
|
-
** the
|
3043
3199
|
** </li>
|
3044
3200
|
** </ol>
|
3045
3201
|
*/
|
@@ -3221,6 +3377,9 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3221
3377
|
** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
|
3222
3378
|
**
|
3223
3379
|
** ^The third argument is the value to bind to the parameter.
|
3380
|
+
** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
|
3381
|
+
** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
|
3382
|
+
** is ignored and the end result is the same as sqlite3_bind_null().
|
3224
3383
|
**
|
3225
3384
|
** ^(In those routines that have a fourth argument, its value is the
|
3226
3385
|
** number of bytes in the parameter. To be clear: the value is the
|
@@ -3231,18 +3390,18 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3231
3390
|
** If the fourth parameter to sqlite3_bind_blob() is negative, then
|
3232
3391
|
** the behavior is undefined.
|
3233
3392
|
** If a non-negative fourth parameter is provided to sqlite3_bind_text()
|
3234
|
-
** or sqlite3_bind_text16()
|
3393
|
+
** or sqlite3_bind_text16() or sqlite3_bind_text64() then
|
3394
|
+
** that parameter must be the byte offset
|
3235
3395
|
** where the NUL terminator would occur assuming the string were NUL
|
3236
3396
|
** terminated. If any NUL characters occur at byte offsets less than
|
3237
3397
|
** the value of the fourth parameter then the resulting string value will
|
3238
3398
|
** contain embedded NULs. The result of expressions involving strings
|
3239
3399
|
** with embedded NULs is undefined.
|
3240
3400
|
**
|
3241
|
-
** ^The fifth argument to
|
3242
|
-
**
|
3401
|
+
** ^The fifth argument to the BLOB and string binding interfaces
|
3402
|
+
** is a destructor used to dispose of the BLOB or
|
3243
3403
|
** string after SQLite has finished with it. ^The destructor is called
|
3244
|
-
** to dispose of the BLOB or string even if the call to
|
3245
|
-
** sqlite3_bind_text(), or sqlite3_bind_text16() fails.
|
3404
|
+
** to dispose of the BLOB or string even if the call to bind API fails.
|
3246
3405
|
** ^If the fifth argument is
|
3247
3406
|
** the special value [SQLITE_STATIC], then SQLite assumes that the
|
3248
3407
|
** information is in static, unmanaged space and does not need to be freed.
|
@@ -3250,6 +3409,14 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3250
3409
|
** SQLite makes its own private copy of the data immediately, before
|
3251
3410
|
** the sqlite3_bind_*() routine returns.
|
3252
3411
|
**
|
3412
|
+
** ^The sixth argument to sqlite3_bind_text64() must be one of
|
3413
|
+
** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
|
3414
|
+
** to specify the encoding of the text in the third parameter. If
|
3415
|
+
** the sixth argument to sqlite3_bind_text64() is not one of the
|
3416
|
+
** allowed values shown above, or if the text encoding is different
|
3417
|
+
** from the encoding specified by the sixth parameter, then the behavior
|
3418
|
+
** is undefined.
|
3419
|
+
**
|
3253
3420
|
** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
|
3254
3421
|
** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
|
3255
3422
|
** (just an integer to hold its size) while it is being processed.
|
@@ -3270,6 +3437,9 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3270
3437
|
**
|
3271
3438
|
** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
|
3272
3439
|
** [error code] if anything goes wrong.
|
3440
|
+
** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
|
3441
|
+
** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
|
3442
|
+
** [SQLITE_MAX_LENGTH].
|
3273
3443
|
** ^[SQLITE_RANGE] is returned if the parameter
|
3274
3444
|
** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
|
3275
3445
|
**
|
@@ -3277,12 +3447,16 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3277
3447
|
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
|
3278
3448
|
*/
|
3279
3449
|
SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
|
3450
|
+
SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
|
3451
|
+
void(*)(void*));
|
3280
3452
|
SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
|
3281
3453
|
SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
|
3282
3454
|
SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
|
3283
3455
|
SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
|
3284
|
-
SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,
|
3456
|
+
SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
|
3285
3457
|
SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
|
3458
|
+
SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
|
3459
|
+
void(*)(void*), unsigned char encoding);
|
3286
3460
|
SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
|
3287
3461
|
SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
|
3288
3462
|
|
@@ -3698,19 +3872,19 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
3698
3872
|
**
|
3699
3873
|
** <tr><td> NULL <td> INTEGER <td> Result is 0
|
3700
3874
|
** <tr><td> NULL <td> FLOAT <td> Result is 0.0
|
3701
|
-
** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
|
3702
|
-
** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
|
3875
|
+
** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
|
3876
|
+
** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
|
3703
3877
|
** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
|
3704
3878
|
** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
|
3705
3879
|
** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
|
3706
|
-
** <tr><td> FLOAT <td> INTEGER <td>
|
3880
|
+
** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
|
3707
3881
|
** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
|
3708
|
-
** <tr><td> FLOAT <td> BLOB <td>
|
3709
|
-
** <tr><td> TEXT <td> INTEGER <td>
|
3710
|
-
** <tr><td> TEXT <td> FLOAT <td>
|
3882
|
+
** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
|
3883
|
+
** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
|
3884
|
+
** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
|
3711
3885
|
** <tr><td> TEXT <td> BLOB <td> No change
|
3712
|
-
** <tr><td> BLOB <td> INTEGER <td>
|
3713
|
-
** <tr><td> BLOB <td> FLOAT <td>
|
3886
|
+
** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
|
3887
|
+
** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
|
3714
3888
|
** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
|
3715
3889
|
** </table>
|
3716
3890
|
** </blockquote>)^
|
@@ -3766,7 +3940,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
3766
3940
|
** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
|
3767
3941
|
** [sqlite3_finalize()] is called. ^The memory space used to hold strings
|
3768
3942
|
** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
|
3769
|
-
** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
|
3943
|
+
** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
|
3770
3944
|
** [sqlite3_free()].
|
3771
3945
|
**
|
3772
3946
|
** ^(If a memory allocation error occurs during the evaluation of any
|
@@ -3875,15 +4049,24 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
|
|
3875
4049
|
**
|
3876
4050
|
** ^The fourth parameter, eTextRep, specifies what
|
3877
4051
|
** [SQLITE_UTF8 | text encoding] this SQL function prefers for
|
3878
|
-
** its parameters.
|
3879
|
-
**
|
3880
|
-
**
|
3881
|
-
**
|
3882
|
-
**
|
4052
|
+
** its parameters. The application should set this parameter to
|
4053
|
+
** [SQLITE_UTF16LE] if the function implementation invokes
|
4054
|
+
** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
|
4055
|
+
** implementation invokes [sqlite3_value_text16be()] on an input, or
|
4056
|
+
** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
|
4057
|
+
** otherwise. ^The same SQL function may be registered multiple times using
|
4058
|
+
** different preferred text encodings, with different implementations for
|
4059
|
+
** each encoding.
|
3883
4060
|
** ^When multiple implementations of the same function are available, SQLite
|
3884
4061
|
** will pick the one that involves the least amount of data conversion.
|
3885
|
-
**
|
3886
|
-
**
|
4062
|
+
**
|
4063
|
+
** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
|
4064
|
+
** to signal that the function will always return the same result given
|
4065
|
+
** the same inputs within a single SQL statement. Most SQL functions are
|
4066
|
+
** deterministic. The built-in [random()] SQL function is an example of a
|
4067
|
+
** function that is not deterministic. The SQLite query planner is able to
|
4068
|
+
** perform additional optimizations on deterministic functions, so use
|
4069
|
+
** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
|
3887
4070
|
**
|
3888
4071
|
** ^(The fifth parameter is an arbitrary pointer. The implementation of the
|
3889
4072
|
** function can gain access to this pointer using [sqlite3_user_data()].)^
|
@@ -3969,9 +4152,19 @@ SQLITE_API int sqlite3_create_function_v2(
|
|
3969
4152
|
#define SQLITE_UTF16LE 2
|
3970
4153
|
#define SQLITE_UTF16BE 3
|
3971
4154
|
#define SQLITE_UTF16 4 /* Use native byte order */
|
3972
|
-
#define SQLITE_ANY 5 /*
|
4155
|
+
#define SQLITE_ANY 5 /* Deprecated */
|
3973
4156
|
#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
|
3974
4157
|
|
4158
|
+
/*
|
4159
|
+
** CAPI3REF: Function Flags
|
4160
|
+
**
|
4161
|
+
** These constants may be ORed together with the
|
4162
|
+
** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
|
4163
|
+
** to [sqlite3_create_function()], [sqlite3_create_function16()], or
|
4164
|
+
** [sqlite3_create_function_v2()].
|
4165
|
+
*/
|
4166
|
+
#define SQLITE_DETERMINISTIC 0x800
|
4167
|
+
|
3975
4168
|
/*
|
3976
4169
|
** CAPI3REF: Deprecated Functions
|
3977
4170
|
** DEPRECATED
|
@@ -3988,7 +4181,8 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
|
|
3988
4181
|
SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
|
3989
4182
|
SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
|
3990
4183
|
SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
|
3991
|
-
SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
|
4184
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
|
4185
|
+
void*,sqlite3_int64);
|
3992
4186
|
#endif
|
3993
4187
|
|
3994
4188
|
/*
|
@@ -4011,7 +4205,7 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
|
|
4011
4205
|
** object results in undefined behavior.
|
4012
4206
|
**
|
4013
4207
|
** ^These routines work just like the corresponding [column access functions]
|
4014
|
-
** except that
|
4208
|
+
** except that these routines take a single [protected sqlite3_value] object
|
4015
4209
|
** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
|
4016
4210
|
**
|
4017
4211
|
** ^The sqlite3_value_text16() interface extracts a UTF-16 string
|
@@ -4068,14 +4262,17 @@ SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
|
|
4068
4262
|
** In those cases, sqlite3_aggregate_context() might be called for the
|
4069
4263
|
** first time from within xFinal().)^
|
4070
4264
|
**
|
4071
|
-
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
|
4072
|
-
** less than or equal to zero or if a memory
|
4265
|
+
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
|
4266
|
+
** when first called if N is less than or equal to zero or if a memory
|
4267
|
+
** allocate error occurs.
|
4073
4268
|
**
|
4074
4269
|
** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
|
4075
4270
|
** determined by the N parameter on first successful call. Changing the
|
4076
4271
|
** value of N in subsequent call to sqlite3_aggregate_context() within
|
4077
4272
|
** the same aggregate function instance will not resize the memory
|
4078
|
-
** allocation.)^
|
4273
|
+
** allocation.)^ Within the xFinal callback, it is customary to set
|
4274
|
+
** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
|
4275
|
+
** pointless memory allocations occur.
|
4079
4276
|
**
|
4080
4277
|
** ^SQLite automatically frees the memory allocated by
|
4081
4278
|
** sqlite3_aggregate_context() when the aggregate query concludes.
|
@@ -4118,41 +4315,49 @@ SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
|
|
4118
4315
|
/*
|
4119
4316
|
** CAPI3REF: Function Auxiliary Data
|
4120
4317
|
**
|
4121
|
-
**
|
4318
|
+
** These functions may be used by (non-aggregate) SQL functions to
|
4122
4319
|
** associate metadata with argument values. If the same value is passed to
|
4123
4320
|
** multiple invocations of the same SQL function during query execution, under
|
4124
|
-
** some circumstances the associated metadata may be preserved.
|
4125
|
-
**
|
4126
|
-
** function. The compiled version of the regular expression
|
4127
|
-
** metadata associated with the
|
4128
|
-
**
|
4129
|
-
**
|
4130
|
-
**
|
4321
|
+
** some circumstances the associated metadata may be preserved. An example
|
4322
|
+
** of where this might be useful is in a regular-expression matching
|
4323
|
+
** function. The compiled version of the regular expression can be stored as
|
4324
|
+
** metadata associated with the pattern string.
|
4325
|
+
** Then as long as the pattern string remains the same,
|
4326
|
+
** the compiled regular expression can be reused on multiple
|
4327
|
+
** invocations of the same function.
|
4131
4328
|
**
|
4132
4329
|
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
|
4133
4330
|
** associated by the sqlite3_set_auxdata() function with the Nth argument
|
4134
|
-
** value to the application-defined function. ^If no metadata
|
4135
|
-
**
|
4136
|
-
**
|
4137
|
-
**
|
4138
|
-
**
|
4139
|
-
**
|
4140
|
-
**
|
4141
|
-
**
|
4142
|
-
**
|
4143
|
-
** not
|
4144
|
-
**
|
4145
|
-
**
|
4146
|
-
** the metadata
|
4147
|
-
**
|
4148
|
-
**
|
4149
|
-
**
|
4150
|
-
**
|
4151
|
-
**
|
4331
|
+
** value to the application-defined function. ^If there is no metadata
|
4332
|
+
** associated with the function argument, this sqlite3_get_auxdata() interface
|
4333
|
+
** returns a NULL pointer.
|
4334
|
+
**
|
4335
|
+
** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
|
4336
|
+
** argument of the application-defined function. ^Subsequent
|
4337
|
+
** calls to sqlite3_get_auxdata(C,N) return P from the most recent
|
4338
|
+
** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
|
4339
|
+
** NULL if the metadata has been discarded.
|
4340
|
+
** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
|
4341
|
+
** SQLite will invoke the destructor function X with parameter P exactly
|
4342
|
+
** once, when the metadata is discarded.
|
4343
|
+
** SQLite is free to discard the metadata at any time, including: <ul>
|
4344
|
+
** <li> when the corresponding function parameter changes, or
|
4345
|
+
** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
|
4346
|
+
** SQL statement, or
|
4347
|
+
** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
|
4348
|
+
** <li> during the original sqlite3_set_auxdata() call when a memory
|
4349
|
+
** allocation error occurs. </ul>)^
|
4350
|
+
**
|
4351
|
+
** Note the last bullet in particular. The destructor X in
|
4352
|
+
** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
|
4353
|
+
** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
|
4354
|
+
** should be called near the end of the function implementation and the
|
4355
|
+
** function implementation should not make any use of P after
|
4356
|
+
** sqlite3_set_auxdata() has been called.
|
4152
4357
|
**
|
4153
4358
|
** ^(In practice, metadata is preserved between function calls for
|
4154
|
-
**
|
4155
|
-
** values and [parameters].)^
|
4359
|
+
** function parameters that are compile-time constants, including literal
|
4360
|
+
** values and [parameters] and expressions composed from the same.)^
|
4156
4361
|
**
|
4157
4362
|
** These routines must be called from the same thread in which
|
4158
4363
|
** the SQL function is running.
|
@@ -4173,7 +4378,7 @@ SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(voi
|
|
4173
4378
|
** the content before returning.
|
4174
4379
|
**
|
4175
4380
|
** The typedef is necessary to work around problems in certain
|
4176
|
-
** C++ compilers.
|
4381
|
+
** C++ compilers.
|
4177
4382
|
*/
|
4178
4383
|
typedef void (*sqlite3_destructor_type)(void*);
|
4179
4384
|
#define SQLITE_STATIC ((sqlite3_destructor_type)0)
|
@@ -4247,6 +4452,10 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
4247
4452
|
** set the return value of the application-defined function to be
|
4248
4453
|
** a text string which is represented as UTF-8, UTF-16 native byte order,
|
4249
4454
|
** UTF-16 little endian, or UTF-16 big endian, respectively.
|
4455
|
+
** ^The sqlite3_result_text64() interface sets the return value of an
|
4456
|
+
** application-defined function to be a text string in an encoding
|
4457
|
+
** specified by the fifth (and last) parameter, which must be one
|
4458
|
+
** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
|
4250
4459
|
** ^SQLite takes the text result from the application from
|
4251
4460
|
** the 2nd parameter of the sqlite3_result_text* interfaces.
|
4252
4461
|
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
|
@@ -4290,6 +4499,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
4290
4499
|
** the [sqlite3_context] pointer, the results are undefined.
|
4291
4500
|
*/
|
4292
4501
|
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
|
4502
|
+
SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,sqlite3_uint64,void(*)(void*));
|
4293
4503
|
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
|
4294
4504
|
SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
|
4295
4505
|
SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
|
@@ -4300,6 +4510,8 @@ SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
|
|
4300
4510
|
SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
|
4301
4511
|
SQLITE_API void sqlite3_result_null(sqlite3_context*);
|
4302
4512
|
SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
|
4513
|
+
SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
|
4514
|
+
void(*)(void*), unsigned char encoding);
|
4303
4515
|
SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
|
4304
4516
|
SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
|
4305
4517
|
SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
|
@@ -4457,6 +4669,11 @@ SQLITE_API int sqlite3_key(
|
|
4457
4669
|
sqlite3 *db, /* Database to be rekeyed */
|
4458
4670
|
const void *pKey, int nKey /* The key */
|
4459
4671
|
);
|
4672
|
+
SQLITE_API int sqlite3_key_v2(
|
4673
|
+
sqlite3 *db, /* Database to be rekeyed */
|
4674
|
+
const char *zDbName, /* Name of the database */
|
4675
|
+
const void *pKey, int nKey /* The key */
|
4676
|
+
);
|
4460
4677
|
|
4461
4678
|
/*
|
4462
4679
|
** Change the key on an open database. If the current database is not
|
@@ -4470,6 +4687,11 @@ SQLITE_API int sqlite3_rekey(
|
|
4470
4687
|
sqlite3 *db, /* Database to be rekeyed */
|
4471
4688
|
const void *pKey, int nKey /* The new key */
|
4472
4689
|
);
|
4690
|
+
SQLITE_API int sqlite3_rekey_v2(
|
4691
|
+
sqlite3 *db, /* Database to be rekeyed */
|
4692
|
+
const char *zDbName, /* Name of the database */
|
4693
|
+
const void *pKey, int nKey /* The new key */
|
4694
|
+
);
|
4473
4695
|
|
4474
4696
|
/*
|
4475
4697
|
** Specify the activation key for a SEE database. Unless
|
@@ -4519,6 +4741,13 @@ SQLITE_API int sqlite3_sleep(int);
|
|
4519
4741
|
** is a NULL pointer, then SQLite performs a search for an appropriate
|
4520
4742
|
** temporary file directory.
|
4521
4743
|
**
|
4744
|
+
** Applications are strongly discouraged from using this global variable.
|
4745
|
+
** It is required to set a temporary folder on Windows Runtime (WinRT).
|
4746
|
+
** But for all other platforms, it is highly recommended that applications
|
4747
|
+
** neither read nor write this variable. This global variable is a relic
|
4748
|
+
** that exists for backwards compatibility of legacy applications and should
|
4749
|
+
** be avoided in new projects.
|
4750
|
+
**
|
4522
4751
|
** It is not safe to read or modify this variable in more than one
|
4523
4752
|
** thread at a time. It is not safe to read or modify this variable
|
4524
4753
|
** if a [database connection] is being used at the same time in a separate
|
@@ -4537,6 +4766,11 @@ SQLITE_API int sqlite3_sleep(int);
|
|
4537
4766
|
** Hence, if this variable is modified directly, either it should be
|
4538
4767
|
** made NULL or made to point to memory obtained from [sqlite3_malloc]
|
4539
4768
|
** or else the use of the [temp_store_directory pragma] should be avoided.
|
4769
|
+
** Except when requested by the [temp_store_directory pragma], SQLite
|
4770
|
+
** does not free the memory that sqlite3_temp_directory points to. If
|
4771
|
+
** the application wants that memory to be freed, it must do
|
4772
|
+
** so itself, taking care to only do so after all [database connection]
|
4773
|
+
** objects have been destroyed.
|
4540
4774
|
**
|
4541
4775
|
** <b>Note to Windows Runtime users:</b> The temporary directory must be set
|
4542
4776
|
** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
|
@@ -4721,12 +4955,13 @@ SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
|
4721
4955
|
**
|
4722
4956
|
** ^The sqlite3_update_hook() interface registers a callback function
|
4723
4957
|
** with the [database connection] identified by the first argument
|
4724
|
-
** to be invoked whenever a row is updated, inserted or deleted
|
4958
|
+
** to be invoked whenever a row is updated, inserted or deleted in
|
4959
|
+
** a rowid table.
|
4725
4960
|
** ^Any callback set by a previous call to this function
|
4726
4961
|
** for the same database connection is overridden.
|
4727
4962
|
**
|
4728
4963
|
** ^The second argument is a pointer to the function to invoke when a
|
4729
|
-
** row is updated, inserted or deleted.
|
4964
|
+
** row is updated, inserted or deleted in a rowid table.
|
4730
4965
|
** ^The first argument to the callback is a copy of the third argument
|
4731
4966
|
** to sqlite3_update_hook().
|
4732
4967
|
** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
|
@@ -4739,6 +4974,7 @@ SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
|
4739
4974
|
**
|
4740
4975
|
** ^(The update hook is not invoked when internal system tables are
|
4741
4976
|
** modified (i.e. sqlite_master and sqlite_sequence).)^
|
4977
|
+
** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
|
4742
4978
|
**
|
4743
4979
|
** ^In the current implementation, the update hook
|
4744
4980
|
** is not invoked when duplication rows are deleted because of an
|
@@ -4820,8 +5056,8 @@ SQLITE_API int sqlite3_release_memory(int);
|
|
4820
5056
|
**
|
4821
5057
|
** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
|
4822
5058
|
** memory as possible from database connection D. Unlike the
|
4823
|
-
** [sqlite3_release_memory()] interface, this interface is effect even
|
4824
|
-
** when
|
5059
|
+
** [sqlite3_release_memory()] interface, this interface is in effect even
|
5060
|
+
** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
|
4825
5061
|
** omitted.
|
4826
5062
|
**
|
4827
5063
|
** See also: [sqlite3_release_memory()]
|
@@ -4972,11 +5208,20 @@ SQLITE_API int sqlite3_table_column_metadata(
|
|
4972
5208
|
** ^This interface loads an SQLite extension library from the named file.
|
4973
5209
|
**
|
4974
5210
|
** ^The sqlite3_load_extension() interface attempts to load an
|
4975
|
-
** SQLite extension library contained in the file zFile.
|
5211
|
+
** [SQLite extension] library contained in the file zFile. If
|
5212
|
+
** the file cannot be loaded directly, attempts are made to load
|
5213
|
+
** with various operating-system specific extensions added.
|
5214
|
+
** So for example, if "samplelib" cannot be loaded, then names like
|
5215
|
+
** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
|
5216
|
+
** be tried also.
|
4976
5217
|
**
|
4977
5218
|
** ^The entry point is zProc.
|
4978
|
-
** ^zProc may be 0, in which case
|
4979
|
-
**
|
5219
|
+
** ^(zProc may be 0, in which case SQLite will try to come up with an
|
5220
|
+
** entry point name on its own. It first tries "sqlite3_extension_init".
|
5221
|
+
** If that does not work, it constructs a name "sqlite3_X_init" where the
|
5222
|
+
** X is consists of the lower-case equivalent of all ASCII alphabetic
|
5223
|
+
** characters in the filename from the last "/" to the first following
|
5224
|
+
** "." and omitting any initial "lib".)^
|
4980
5225
|
** ^The sqlite3_load_extension() interface returns
|
4981
5226
|
** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
|
4982
5227
|
** ^If an error occurs and pzErrMsg is not 0, then the
|
@@ -5002,11 +5247,11 @@ SQLITE_API int sqlite3_load_extension(
|
|
5002
5247
|
** CAPI3REF: Enable Or Disable Extension Loading
|
5003
5248
|
**
|
5004
5249
|
** ^So as not to open security holes in older applications that are
|
5005
|
-
** unprepared to deal with extension loading, and as a means of disabling
|
5006
|
-
** extension loading while evaluating user-entered SQL, the following API
|
5250
|
+
** unprepared to deal with [extension loading], and as a means of disabling
|
5251
|
+
** [extension loading] while evaluating user-entered SQL, the following API
|
5007
5252
|
** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
|
5008
5253
|
**
|
5009
|
-
** ^Extension loading is off by default.
|
5254
|
+
** ^Extension loading is off by default.
|
5010
5255
|
** ^Call the sqlite3_enable_load_extension() routine with onoff==1
|
5011
5256
|
** to turn extension loading on and call it with onoff==0 to turn
|
5012
5257
|
** it back off again.
|
@@ -5018,7 +5263,7 @@ SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
|
5018
5263
|
**
|
5019
5264
|
** ^This interface causes the xEntryPoint() function to be invoked for
|
5020
5265
|
** each new [database connection] that is created. The idea here is that
|
5021
|
-
** xEntryPoint() is the entry point for a statically linked SQLite extension
|
5266
|
+
** xEntryPoint() is the entry point for a statically linked [SQLite extension]
|
5022
5267
|
** that is to be automatically loaded into all new database connections.
|
5023
5268
|
**
|
5024
5269
|
** ^(Even though the function prototype shows that xEntryPoint() takes
|
@@ -5046,10 +5291,23 @@ SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
|
5046
5291
|
** on the list of automatic extensions is a harmless no-op. ^No entry point
|
5047
5292
|
** will be called more than once for each database connection that is opened.
|
5048
5293
|
**
|
5049
|
-
** See also: [sqlite3_reset_auto_extension()]
|
5294
|
+
** See also: [sqlite3_reset_auto_extension()]
|
5295
|
+
** and [sqlite3_cancel_auto_extension()]
|
5050
5296
|
*/
|
5051
5297
|
SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
|
5052
5298
|
|
5299
|
+
/*
|
5300
|
+
** CAPI3REF: Cancel Automatic Extension Loading
|
5301
|
+
**
|
5302
|
+
** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
|
5303
|
+
** initialization routine X that was registered using a prior call to
|
5304
|
+
** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)]
|
5305
|
+
** routine returns 1 if initialization routine X was successfully
|
5306
|
+
** unregistered and it returns 0 if X was not on the list of initialization
|
5307
|
+
** routines.
|
5308
|
+
*/
|
5309
|
+
SQLITE_API int sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
|
5310
|
+
|
5053
5311
|
/*
|
5054
5312
|
** CAPI3REF: Reset Automatic Extension Loading
|
5055
5313
|
**
|
@@ -5174,10 +5432,22 @@ struct sqlite3_module {
|
|
5174
5432
|
** the correct order to satisfy the ORDER BY clause so that no separate
|
5175
5433
|
** sorting step is required.
|
5176
5434
|
**
|
5177
|
-
** ^The estimatedCost value is an estimate of the cost of
|
5178
|
-
**
|
5179
|
-
** a
|
5180
|
-
**
|
5435
|
+
** ^The estimatedCost value is an estimate of the cost of a particular
|
5436
|
+
** strategy. A cost of N indicates that the cost of the strategy is similar
|
5437
|
+
** to a linear scan of an SQLite table with N rows. A cost of log(N)
|
5438
|
+
** indicates that the expense of the operation is similar to that of a
|
5439
|
+
** binary search on a unique indexed field of an SQLite table with N rows.
|
5440
|
+
**
|
5441
|
+
** ^The estimatedRows value is an estimate of the number of rows that
|
5442
|
+
** will be returned by the strategy.
|
5443
|
+
**
|
5444
|
+
** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
|
5445
|
+
** structure for SQLite version 3.8.2. If a virtual table extension is
|
5446
|
+
** used with an SQLite version earlier than 3.8.2, the results of attempting
|
5447
|
+
** to read or write the estimatedRows field are undefined (but are likely
|
5448
|
+
** to included crashing the application). The estimatedRows field should
|
5449
|
+
** therefore only be used if [sqlite3_libversion_number()] returns a
|
5450
|
+
** value greater than or equal to 3008002.
|
5181
5451
|
*/
|
5182
5452
|
struct sqlite3_index_info {
|
5183
5453
|
/* Inputs */
|
@@ -5202,7 +5472,9 @@ struct sqlite3_index_info {
|
|
5202
5472
|
char *idxStr; /* String, possibly obtained from sqlite3_malloc */
|
5203
5473
|
int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
|
5204
5474
|
int orderByConsumed; /* True if output is already ordered */
|
5205
|
-
double estimatedCost;
|
5475
|
+
double estimatedCost; /* Estimated cost of using this index */
|
5476
|
+
/* Fields below are only available in SQLite 3.8.2 and later */
|
5477
|
+
sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
|
5206
5478
|
};
|
5207
5479
|
|
5208
5480
|
/*
|
@@ -5406,6 +5678,9 @@ typedef struct sqlite3_blob sqlite3_blob;
|
|
5406
5678
|
** interface. Use the [UPDATE] SQL command to change the size of a
|
5407
5679
|
** blob.
|
5408
5680
|
**
|
5681
|
+
** ^The [sqlite3_blob_open()] interface will fail for a [WITHOUT ROWID]
|
5682
|
+
** table. Incremental BLOB I/O is not possible on [WITHOUT ROWID] tables.
|
5683
|
+
**
|
5409
5684
|
** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
|
5410
5685
|
** and the built-in [zeroblob] SQL function can be used, if desired,
|
5411
5686
|
** to create an empty, zero-filled blob in which to read or write using
|
@@ -5630,10 +5905,12 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
|
5630
5905
|
** <li> SQLITE_MUTEX_RECURSIVE
|
5631
5906
|
** <li> SQLITE_MUTEX_STATIC_MASTER
|
5632
5907
|
** <li> SQLITE_MUTEX_STATIC_MEM
|
5633
|
-
** <li>
|
5908
|
+
** <li> SQLITE_MUTEX_STATIC_OPEN
|
5634
5909
|
** <li> SQLITE_MUTEX_STATIC_PRNG
|
5635
5910
|
** <li> SQLITE_MUTEX_STATIC_LRU
|
5636
|
-
** <li>
|
5911
|
+
** <li> SQLITE_MUTEX_STATIC_PMEM
|
5912
|
+
** <li> SQLITE_MUTEX_STATIC_APP1
|
5913
|
+
** <li> SQLITE_MUTEX_STATIC_APP2
|
5637
5914
|
** </ul>)^
|
5638
5915
|
**
|
5639
5916
|
** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
|
@@ -5837,6 +6114,9 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
|
|
5837
6114
|
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
|
5838
6115
|
#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
|
5839
6116
|
#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
|
6117
|
+
#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
|
6118
|
+
#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
|
6119
|
+
#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
|
5840
6120
|
|
5841
6121
|
/*
|
5842
6122
|
** CAPI3REF: Retrieve the mutex for a database connection
|
@@ -5928,8 +6208,13 @@ SQLITE_API int sqlite3_test_control(int op, ...);
|
|
5928
6208
|
#define SQLITE_TESTCTRL_ISKEYWORD 16
|
5929
6209
|
#define SQLITE_TESTCTRL_SCRATCHMALLOC 17
|
5930
6210
|
#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
|
5931
|
-
#define SQLITE_TESTCTRL_EXPLAIN_STMT 19
|
5932
|
-
#define
|
6211
|
+
#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
|
6212
|
+
#define SQLITE_TESTCTRL_NEVER_CORRUPT 20
|
6213
|
+
#define SQLITE_TESTCTRL_VDBE_COVERAGE 21
|
6214
|
+
#define SQLITE_TESTCTRL_BYTEORDER 22
|
6215
|
+
#define SQLITE_TESTCTRL_ISINIT 23
|
6216
|
+
#define SQLITE_TESTCTRL_SORTER_MMAP 24
|
6217
|
+
#define SQLITE_TESTCTRL_LAST 24
|
5933
6218
|
|
5934
6219
|
/*
|
5935
6220
|
** CAPI3REF: SQLite Runtime Status
|
@@ -6120,12 +6405,12 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
|
6120
6405
|
** the current value is always zero.)^
|
6121
6406
|
**
|
6122
6407
|
** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
|
6123
|
-
** <dd>This parameter returns the approximate number of
|
6408
|
+
** <dd>This parameter returns the approximate number of bytes of heap
|
6124
6409
|
** memory used by all pager caches associated with the database connection.)^
|
6125
6410
|
** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
|
6126
6411
|
**
|
6127
6412
|
** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
|
6128
|
-
** <dd>This parameter returns the approximate number of
|
6413
|
+
** <dd>This parameter returns the approximate number of bytes of heap
|
6129
6414
|
** memory used to store the schema for all databases associated
|
6130
6415
|
** with the connection - main, temp, and any [ATTACH]-ed databases.)^
|
6131
6416
|
** ^The full amount of memory used by the schemas is reported, even if the
|
@@ -6134,7 +6419,7 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
|
6134
6419
|
** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
|
6135
6420
|
**
|
6136
6421
|
** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
|
6137
|
-
** <dd>This parameter returns the approximate number of
|
6422
|
+
** <dd>This parameter returns the approximate number of bytes of heap
|
6138
6423
|
** and lookaside memory used by all prepared statements associated with
|
6139
6424
|
** the database connection.)^
|
6140
6425
|
** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
|
@@ -6162,6 +6447,12 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
|
6162
6447
|
** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
|
6163
6448
|
** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
|
6164
6449
|
** </dd>
|
6450
|
+
**
|
6451
|
+
** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
|
6452
|
+
** <dd>This parameter returns zero for the current value if and only if
|
6453
|
+
** all foreign key constraints (deferred or immediate) have been
|
6454
|
+
** resolved.)^ ^The highwater mark is always 0.
|
6455
|
+
** </dd>
|
6165
6456
|
** </dl>
|
6166
6457
|
*/
|
6167
6458
|
#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
|
@@ -6174,7 +6465,8 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
|
6174
6465
|
#define SQLITE_DBSTATUS_CACHE_HIT 7
|
6175
6466
|
#define SQLITE_DBSTATUS_CACHE_MISS 8
|
6176
6467
|
#define SQLITE_DBSTATUS_CACHE_WRITE 9
|
6177
|
-
#define
|
6468
|
+
#define SQLITE_DBSTATUS_DEFERRED_FKS 10
|
6469
|
+
#define SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */
|
6178
6470
|
|
6179
6471
|
|
6180
6472
|
/*
|
@@ -6228,11 +6520,21 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
|
6228
6520
|
** A non-zero value in this counter may indicate an opportunity to
|
6229
6521
|
** improvement performance by adding permanent indices that do not
|
6230
6522
|
** need to be reinitialized each time the statement is run.</dd>
|
6523
|
+
**
|
6524
|
+
** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
|
6525
|
+
** <dd>^This is the number of virtual machine operations executed
|
6526
|
+
** by the prepared statement if that number is less than or equal
|
6527
|
+
** to 2147483647. The number of virtual machine operations can be
|
6528
|
+
** used as a proxy for the total work done by the prepared statement.
|
6529
|
+
** If the number of virtual machine operations exceeds 2147483647
|
6530
|
+
** then the value returned by this statement status code is undefined.
|
6531
|
+
** </dd>
|
6231
6532
|
** </dl>
|
6232
6533
|
*/
|
6233
6534
|
#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
|
6234
6535
|
#define SQLITE_STMTSTATUS_SORT 2
|
6235
6536
|
#define SQLITE_STMTSTATUS_AUTOINDEX 3
|
6537
|
+
#define SQLITE_STMTSTATUS_VM_STEP 4
|
6236
6538
|
|
6237
6539
|
/*
|
6238
6540
|
** CAPI3REF: Custom Page Cache Object
|
@@ -6369,7 +6671,7 @@ struct sqlite3_pcache_page {
|
|
6369
6671
|
** parameter to help it determined what action to take:
|
6370
6672
|
**
|
6371
6673
|
** <table border=1 width=85% align=center>
|
6372
|
-
** <tr><th> createFlag <th>
|
6674
|
+
** <tr><th> createFlag <th> Behavior when page is not already in cache
|
6373
6675
|
** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
|
6374
6676
|
** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
|
6375
6677
|
** Otherwise return NULL.
|
@@ -6798,10 +7100,25 @@ SQLITE_API int sqlite3_unlock_notify(
|
|
6798
7100
|
SQLITE_API int sqlite3_stricmp(const char *, const char *);
|
6799
7101
|
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
|
6800
7102
|
|
7103
|
+
/*
|
7104
|
+
** CAPI3REF: String Globbing
|
7105
|
+
*
|
7106
|
+
** ^The [sqlite3_strglob(P,X)] interface returns zero if string X matches
|
7107
|
+
** the glob pattern P, and it returns non-zero if string X does not match
|
7108
|
+
** the glob pattern P. ^The definition of glob pattern matching used in
|
7109
|
+
** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
|
7110
|
+
** SQL dialect used by SQLite. ^The sqlite3_strglob(P,X) function is case
|
7111
|
+
** sensitive.
|
7112
|
+
**
|
7113
|
+
** Note that this routine returns zero on a match and non-zero if the strings
|
7114
|
+
** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
7115
|
+
*/
|
7116
|
+
SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
|
7117
|
+
|
6801
7118
|
/*
|
6802
7119
|
** CAPI3REF: Error Logging Interface
|
6803
7120
|
**
|
6804
|
-
** ^The [sqlite3_log()] interface writes a message into the error log
|
7121
|
+
** ^The [sqlite3_log()] interface writes a message into the [error log]
|
6805
7122
|
** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
|
6806
7123
|
** ^If logging is enabled, the zFormat string and subsequent arguments are
|
6807
7124
|
** used with [sqlite3_snprintf()] to generate the final output string.
|
@@ -6881,6 +7198,9 @@ SQLITE_API void *sqlite3_wal_hook(
|
|
6881
7198
|
** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
|
6882
7199
|
** from SQL.
|
6883
7200
|
**
|
7201
|
+
** ^Checkpoints initiated by this mechanism are
|
7202
|
+
** [sqlite3_wal_checkpoint_v2|PASSIVE].
|
7203
|
+
**
|
6884
7204
|
** ^Every new [database connection] defaults to having the auto-checkpoint
|
6885
7205
|
** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
|
6886
7206
|
** pages. The use of this interface
|
@@ -6897,6 +7217,10 @@ SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
|
6897
7217
|
** empty string, then a checkpoint is run on all databases of
|
6898
7218
|
** connection D. ^If the database connection D is not in
|
6899
7219
|
** [WAL | write-ahead log mode] then this interface is a harmless no-op.
|
7220
|
+
** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a
|
7221
|
+
** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint.
|
7222
|
+
** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL
|
7223
|
+
** or RESET checkpoint.
|
6900
7224
|
**
|
6901
7225
|
** ^The [wal_checkpoint pragma] can be used to invoke this interface
|
6902
7226
|
** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
|
@@ -6919,10 +7243,12 @@ SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
|
6919
7243
|
** Checkpoint as many frames as possible without waiting for any database
|
6920
7244
|
** readers or writers to finish. Sync the db file if all frames in the log
|
6921
7245
|
** are checkpointed. This mode is the same as calling
|
6922
|
-
** sqlite3_wal_checkpoint(). The busy-handler callback
|
7246
|
+
** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback]
|
7247
|
+
** is never invoked.
|
6923
7248
|
**
|
6924
7249
|
** <dt>SQLITE_CHECKPOINT_FULL<dd>
|
6925
|
-
** This mode blocks (
|
7250
|
+
** This mode blocks (it invokes the
|
7251
|
+
** [sqlite3_busy_handler|busy-handler callback]) until there is no
|
6926
7252
|
** database writer and all readers are reading from the most recent database
|
6927
7253
|
** snapshot. It then checkpoints all frames in the log file and syncs the
|
6928
7254
|
** database file. This call blocks database writers while it is running,
|
@@ -6930,7 +7256,8 @@ SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
|
6930
7256
|
**
|
6931
7257
|
** <dt>SQLITE_CHECKPOINT_RESTART<dd>
|
6932
7258
|
** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
|
6933
|
-
** checkpointing the log file it blocks (calls the
|
7259
|
+
** checkpointing the log file it blocks (calls the
|
7260
|
+
** [sqlite3_busy_handler|busy-handler callback])
|
6934
7261
|
** until all readers are reading from the database file only. This ensures
|
6935
7262
|
** that the next client to write to the database file restarts the log file
|
6936
7263
|
** from the beginning. This call blocks database writers while it is running,
|
@@ -7068,6 +7395,7 @@ SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
|
|
7068
7395
|
|
7069
7396
|
/*
|
7070
7397
|
** CAPI3REF: Conflict resolution modes
|
7398
|
+
** KEYWORDS: {conflict resolution mode}
|
7071
7399
|
**
|
7072
7400
|
** These constants are returned by [sqlite3_vtab_on_conflict()] to
|
7073
7401
|
** inform a [virtual table] implementation what the [ON CONFLICT] mode
|
@@ -7096,7 +7424,7 @@ SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
|
|
7096
7424
|
#ifdef __cplusplus
|
7097
7425
|
} /* End of the 'extern "C"' block */
|
7098
7426
|
#endif
|
7099
|
-
#endif
|
7427
|
+
#endif /* _SQLITE3_H_ */
|
7100
7428
|
|
7101
7429
|
/*
|
7102
7430
|
** 2010 August 30
|
@@ -7120,6 +7448,16 @@ extern "C" {
|
|
7120
7448
|
#endif
|
7121
7449
|
|
7122
7450
|
typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
|
7451
|
+
typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
|
7452
|
+
|
7453
|
+
/* The double-precision datatype used by RTree depends on the
|
7454
|
+
** SQLITE_RTREE_INT_ONLY compile-time option.
|
7455
|
+
*/
|
7456
|
+
#ifdef SQLITE_RTREE_INT_ONLY
|
7457
|
+
typedef sqlite3_int64 sqlite3_rtree_dbl;
|
7458
|
+
#else
|
7459
|
+
typedef double sqlite3_rtree_dbl;
|
7460
|
+
#endif
|
7123
7461
|
|
7124
7462
|
/*
|
7125
7463
|
** Register a geometry callback named zGeom that can be used as part of an
|
@@ -7130,11 +7468,7 @@ typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
|
|
7130
7468
|
SQLITE_API int sqlite3_rtree_geometry_callback(
|
7131
7469
|
sqlite3 *db,
|
7132
7470
|
const char *zGeom,
|
7133
|
-
|
7134
|
-
int (*xGeom)(sqlite3_rtree_geometry*, int n, sqlite3_int64 *a, int *pRes),
|
7135
|
-
#else
|
7136
|
-
int (*xGeom)(sqlite3_rtree_geometry*, int n, double *a, int *pRes),
|
7137
|
-
#endif
|
7471
|
+
int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
|
7138
7472
|
void *pContext
|
7139
7473
|
);
|
7140
7474
|
|
@@ -7146,11 +7480,60 @@ SQLITE_API int sqlite3_rtree_geometry_callback(
|
|
7146
7480
|
struct sqlite3_rtree_geometry {
|
7147
7481
|
void *pContext; /* Copy of pContext passed to s_r_g_c() */
|
7148
7482
|
int nParam; /* Size of array aParam[] */
|
7149
|
-
|
7483
|
+
sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
|
7150
7484
|
void *pUser; /* Callback implementation user data */
|
7151
7485
|
void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
|
7152
7486
|
};
|
7153
7487
|
|
7488
|
+
/*
|
7489
|
+
** Register a 2nd-generation geometry callback named zScore that can be
|
7490
|
+
** used as part of an R-Tree geometry query as follows:
|
7491
|
+
**
|
7492
|
+
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
|
7493
|
+
*/
|
7494
|
+
SQLITE_API int sqlite3_rtree_query_callback(
|
7495
|
+
sqlite3 *db,
|
7496
|
+
const char *zQueryFunc,
|
7497
|
+
int (*xQueryFunc)(sqlite3_rtree_query_info*),
|
7498
|
+
void *pContext,
|
7499
|
+
void (*xDestructor)(void*)
|
7500
|
+
);
|
7501
|
+
|
7502
|
+
|
7503
|
+
/*
|
7504
|
+
** A pointer to a structure of the following type is passed as the
|
7505
|
+
** argument to scored geometry callback registered using
|
7506
|
+
** sqlite3_rtree_query_callback().
|
7507
|
+
**
|
7508
|
+
** Note that the first 5 fields of this structure are identical to
|
7509
|
+
** sqlite3_rtree_geometry. This structure is a subclass of
|
7510
|
+
** sqlite3_rtree_geometry.
|
7511
|
+
*/
|
7512
|
+
struct sqlite3_rtree_query_info {
|
7513
|
+
void *pContext; /* pContext from when function registered */
|
7514
|
+
int nParam; /* Number of function parameters */
|
7515
|
+
sqlite3_rtree_dbl *aParam; /* value of function parameters */
|
7516
|
+
void *pUser; /* callback can use this, if desired */
|
7517
|
+
void (*xDelUser)(void*); /* function to free pUser */
|
7518
|
+
sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
|
7519
|
+
unsigned int *anQueue; /* Number of pending entries in the queue */
|
7520
|
+
int nCoord; /* Number of coordinates */
|
7521
|
+
int iLevel; /* Level of current node or entry */
|
7522
|
+
int mxLevel; /* The largest iLevel value in the tree */
|
7523
|
+
sqlite3_int64 iRowid; /* Rowid for current entry */
|
7524
|
+
sqlite3_rtree_dbl rParentScore; /* Score of parent node */
|
7525
|
+
int eParentWithin; /* Visibility of parent node */
|
7526
|
+
int eWithin; /* OUT: Visiblity */
|
7527
|
+
sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
|
7528
|
+
};
|
7529
|
+
|
7530
|
+
/*
|
7531
|
+
** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
|
7532
|
+
*/
|
7533
|
+
#define NOT_WITHIN 0 /* Object completely outside of query region */
|
7534
|
+
#define PARTLY_WITHIN 1 /* Object partially overlaps query region */
|
7535
|
+
#define FULLY_WITHIN 2 /* Object fully contained within query region */
|
7536
|
+
|
7154
7537
|
|
7155
7538
|
#ifdef __cplusplus
|
7156
7539
|
} /* end of the 'extern "C"' block */
|