… | |
… | |
105 | ** |
105 | ** |
106 | ** See also: [sqlite3_libversion()], |
106 | ** See also: [sqlite3_libversion()], |
107 | ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
107 | ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
108 | ** [sqlite_version()] and [sqlite_source_id()]. |
108 | ** [sqlite_version()] and [sqlite_source_id()]. |
109 | */ |
109 | */ |
110 | #define SQLITE_VERSION "3.7.15.2" |
110 | #define SQLITE_VERSION "3.8.7.4" |
111 | #define SQLITE_VERSION_NUMBER 3007015 |
111 | #define SQLITE_VERSION_NUMBER 3008007 |
112 | #define SQLITE_SOURCE_ID "2013-01-09 11:53:05 c0e09560d26f0a6456be9dd3447f5311eb4f238f" |
112 | #define SQLITE_SOURCE_ID "2014-12-09 01:34:36 f66f7a17b78ba617acde90fc810107f34f1a1f2e" |
113 | |
113 | |
114 | /* |
114 | /* |
115 | ** CAPI3REF: Run-Time Library Version Numbers |
115 | ** CAPI3REF: Run-Time Library Version Numbers |
116 | ** KEYWORDS: sqlite3_version, sqlite3_sourceid |
116 | ** KEYWORDS: sqlite3_version, sqlite3_sourceid |
117 | ** |
117 | ** |
… | |
… | |
267 | /* |
267 | /* |
268 | ** CAPI3REF: Closing A Database Connection |
268 | ** CAPI3REF: Closing A Database Connection |
269 | ** |
269 | ** |
270 | ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors |
270 | ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors |
271 | ** for the [sqlite3] object. |
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 | ** the [sqlite3] object is successfully destroyed and all associated |
273 | ** the [sqlite3] object is successfully destroyed and all associated |
274 | ** resources are deallocated. |
274 | ** resources are deallocated. |
275 | ** |
275 | ** |
276 | ** ^If the database connection is associated with unfinalized prepared |
276 | ** ^If the database connection is associated with unfinalized prepared |
277 | ** statements or unfinished sqlite3_backup objects then sqlite3_close() |
277 | ** statements or unfinished sqlite3_backup objects then sqlite3_close() |
278 | ** will leave the database connection open and return [SQLITE_BUSY]. |
278 | ** will leave the database connection open and return [SQLITE_BUSY]. |
279 | ** ^If sqlite3_close_v2() is called with unfinalized prepared statements |
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 | ** an unusable "zombie" which will automatically be deallocated when the |
281 | ** an unusable "zombie" which will automatically be deallocated when the |
282 | ** last prepared statement is finalized or the last sqlite3_backup is |
282 | ** last prepared statement is finalized or the last sqlite3_backup is |
283 | ** finished. The sqlite3_close_v2() interface is intended for use with |
283 | ** finished. The sqlite3_close_v2() interface is intended for use with |
284 | ** host languages that are garbage collected, and where the order in which |
284 | ** host languages that are garbage collected, and where the order in which |
285 | ** destructors are called is arbitrary. |
285 | ** destructors are called is arbitrary. |
286 | ** |
286 | ** |
287 | ** Applications should [sqlite3_finalize | finalize] all [prepared statements], |
287 | ** Applications should [sqlite3_finalize | finalize] all [prepared statements], |
288 | ** [sqlite3_blob_close | close] all [BLOB handles], and |
288 | ** [sqlite3_blob_close | close] all [BLOB handles], and |
289 | ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated |
289 | ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated |
290 | ** with the [sqlite3] object prior to attempting to close the object. ^If |
290 | ** with the [sqlite3] object prior to attempting to close the object. ^If |
291 | ** sqlite3_close() is called on a [database connection] that still has |
291 | ** sqlite3_close_v2() is called on a [database connection] that still has |
292 | ** outstanding [prepared statements], [BLOB handles], and/or |
292 | ** outstanding [prepared statements], [BLOB handles], and/or |
293 | ** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation |
293 | ** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation |
294 | ** of resources is deferred until all [prepared statements], [BLOB handles], |
294 | ** of resources is deferred until all [prepared statements], [BLOB handles], |
295 | ** and [sqlite3_backup] objects are also destroyed. |
295 | ** and [sqlite3_backup] objects are also destroyed. |
296 | ** |
296 | ** |
297 | ** ^If an [sqlite3] object is destroyed while a transaction is open, |
297 | ** ^If an [sqlite3] object is destroyed while a transaction is open, |
298 | ** the transaction is automatically rolled back. |
298 | ** the transaction is automatically rolled back. |
… | |
… | |
368 | ** Restrictions: |
368 | ** Restrictions: |
369 | ** |
369 | ** |
370 | ** <ul> |
370 | ** <ul> |
371 | ** <li> The application must insure that the 1st parameter to sqlite3_exec() |
371 | ** <li> The application must insure that the 1st parameter to sqlite3_exec() |
372 | ** is a valid and open [database connection]. |
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 | ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. |
374 | ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. |
375 | ** <li> The application must not modify the SQL statement text passed into |
375 | ** <li> The application must not modify the SQL statement text passed into |
376 | ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. |
376 | ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. |
377 | ** </ul> |
377 | ** </ul> |
378 | */ |
378 | */ |
… | |
… | |
384 | char **errmsg /* Error msg written here */ |
384 | char **errmsg /* Error msg written here */ |
385 | ); |
385 | ); |
386 | |
386 | |
387 | /* |
387 | /* |
388 | ** CAPI3REF: Result Codes |
388 | ** CAPI3REF: Result Codes |
389 | ** KEYWORDS: SQLITE_OK {error code} {error codes} |
389 | ** KEYWORDS: {result code definitions} |
390 | ** KEYWORDS: {result code} {result codes} |
|
|
391 | ** |
390 | ** |
392 | ** Many SQLite functions return an integer result code from the set shown |
391 | ** Many SQLite functions return an integer result code from the set shown |
393 | ** here in order to indicate success or failure. |
392 | ** here in order to indicate success or failure. |
394 | ** |
393 | ** |
395 | ** New error codes may be added in future versions of SQLite. |
394 | ** New error codes may be added in future versions of SQLite. |
396 | ** |
395 | ** |
397 | ** See also: [SQLITE_IOERR_READ | extended result codes], |
396 | ** See also: [extended result code definitions] |
398 | ** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes]. |
|
|
399 | */ |
397 | */ |
400 | #define SQLITE_OK 0 /* Successful result */ |
398 | #define SQLITE_OK 0 /* Successful result */ |
401 | /* beginning-of-error-codes */ |
399 | /* beginning-of-error-codes */ |
402 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
400 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
403 | #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ |
401 | #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ |
… | |
… | |
423 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ |
421 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ |
424 | #define SQLITE_AUTH 23 /* Authorization denied */ |
422 | #define SQLITE_AUTH 23 /* Authorization denied */ |
425 | #define SQLITE_FORMAT 24 /* Auxiliary database format error */ |
423 | #define SQLITE_FORMAT 24 /* Auxiliary database format error */ |
426 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ |
424 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ |
427 | #define SQLITE_NOTADB 26 /* File opened that is not a database file */ |
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 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ |
428 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ |
429 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ |
429 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ |
430 | /* end-of-error-codes */ |
430 | /* end-of-error-codes */ |
431 | |
431 | |
432 | /* |
432 | /* |
433 | ** CAPI3REF: Extended Result Codes |
433 | ** CAPI3REF: Extended Result Codes |
434 | ** KEYWORDS: {extended error code} {extended error codes} |
|
|
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 26 integer |
436 | ** In its default configuration, SQLite API routines return one of 30 integer |
438 | ** [SQLITE_OK | result codes]. However, experience has shown that many of |
437 | ** [result codes]. However, experience has shown that many of |
439 | ** these result codes are too coarse-grained. They do not provide as |
438 | ** these result codes are too coarse-grained. They do not provide as |
440 | ** much information about problems as programmers might like. In an effort to |
439 | ** much information about problems as programmers might like. In an effort to |
441 | ** address this, newer versions of SQLite (version 3.3.8 and later) include |
440 | ** address this, newer versions of SQLite (version 3.3.8 and later) include |
442 | ** support for additional result codes that provide more detailed information |
441 | ** support for additional result codes that provide more detailed information |
443 | ** about errors. The extended result codes are enabled or disabled |
442 | ** about errors. These [extended result codes] are enabled or disabled |
444 | ** on a per database connection basis using the |
443 | ** on a per database connection basis using the |
|
|
444 | ** [sqlite3_extended_result_codes()] API. Or, the extended code for |
|
|
445 | ** the most recent error can be obtained using |
445 | ** [sqlite3_extended_result_codes()] API. |
446 | ** [sqlite3_extended_errcode()]. |
446 | ** |
|
|
447 | ** Some of the available extended result codes are listed here. |
|
|
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. |
|
|
454 | */ |
447 | */ |
455 | #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
448 | #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
456 | #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
449 | #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
457 | #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
450 | #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
458 | #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) |
451 | #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) |
… | |
… | |
473 | #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) |
466 | #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) |
474 | #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) |
467 | #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) |
475 | #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) |
468 | #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) |
476 | #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) |
469 | #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) |
477 | #define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8)) |
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 | #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) |
474 | #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) |
479 | #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) |
475 | #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) |
|
|
476 | #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) |
480 | #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) |
477 | #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) |
481 | #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) |
478 | #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) |
482 | #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) |
479 | #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) |
|
|
480 | #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) |
483 | #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) |
481 | #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) |
484 | #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) |
482 | #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) |
485 | #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) |
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 | #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) |
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 | ** CAPI3REF: Flags For File Open Operations |
503 | ** CAPI3REF: Flags For File Open Operations |
490 | ** |
504 | ** |
491 | ** These bit values are intended for use in the |
505 | ** These bit values are intended for use in the |
… | |
… | |
535 | ** information is written to disk in the same order as calls |
549 | ** information is written to disk in the same order as calls |
536 | ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that |
550 | ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that |
537 | ** after reboot following a crash or power loss, the only bytes in a |
551 | ** after reboot following a crash or power loss, the only bytes in a |
538 | ** file that were written at the application level might have changed |
552 | ** file that were written at the application level might have changed |
539 | ** and that adjacent bytes, even bytes within the same sector are |
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 | #define SQLITE_IOCAP_ATOMIC 0x00000001 |
560 | #define SQLITE_IOCAP_ATOMIC 0x00000001 |
543 | #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
561 | #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
544 | #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
562 | #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
545 | #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
563 | #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
… | |
… | |
550 | #define SQLITE_IOCAP_ATOMIC64K 0x00000100 |
568 | #define SQLITE_IOCAP_ATOMIC64K 0x00000100 |
551 | #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 |
569 | #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 |
552 | #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 |
570 | #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 |
553 | #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 |
571 | #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 |
554 | #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 |
572 | #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 |
|
|
573 | #define SQLITE_IOCAP_IMMUTABLE 0x00002000 |
555 | |
574 | |
556 | /* |
575 | /* |
557 | ** CAPI3REF: File Locking Levels |
576 | ** CAPI3REF: File Locking Levels |
558 | ** |
577 | ** |
559 | ** SQLite uses one of these integer values as the second |
578 | ** SQLite uses one of these integer values as the second |
… | |
… | |
656 | ** write return values. Potential uses for xFileControl() might be |
675 | ** write return values. Potential uses for xFileControl() might be |
657 | ** functions to enable blocking locks with timeouts, to change the |
676 | ** functions to enable blocking locks with timeouts, to change the |
658 | ** locking strategy (for example to use dot-file locks), to inquire |
677 | ** locking strategy (for example to use dot-file locks), to inquire |
659 | ** about the status of a lock, or to break stale locks. The SQLite |
678 | ** about the status of a lock, or to break stale locks. The SQLite |
660 | ** core reserves all opcodes less than 100 for its own use. |
679 | ** core reserves all opcodes less than 100 for its own use. |
661 | ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. |
680 | ** A [file control opcodes | list of opcodes] less than 100 is available. |
662 | ** Applications that define a custom xFileControl method should use opcodes |
681 | ** Applications that define a custom xFileControl method should use opcodes |
663 | ** greater than 100 to avoid conflicts. VFS implementations should |
682 | ** greater than 100 to avoid conflicts. VFS implementations should |
664 | ** return [SQLITE_NOTFOUND] for file control opcodes that they do not |
683 | ** return [SQLITE_NOTFOUND] for file control opcodes that they do not |
665 | ** recognize. |
684 | ** recognize. |
666 | ** |
685 | ** |
… | |
… | |
721 | int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); |
740 | int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); |
722 | int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); |
741 | int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); |
723 | void (*xShmBarrier)(sqlite3_file*); |
742 | void (*xShmBarrier)(sqlite3_file*); |
724 | int (*xShmUnmap)(sqlite3_file*, int deleteFlag); |
743 | int (*xShmUnmap)(sqlite3_file*, int deleteFlag); |
725 | /* Methods above are valid for version 2 */ |
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 | /* Additional methods may be added in future releases */ |
748 | /* Additional methods may be added in future releases */ |
727 | }; |
749 | }; |
728 | |
750 | |
729 | /* |
751 | /* |
730 | ** CAPI3REF: Standard File Control Opcodes |
752 | ** CAPI3REF: Standard File Control Opcodes |
|
|
753 | ** KEYWORDS: {file control opcodes} {file control opcode} |
731 | ** |
754 | ** |
732 | ** These integer constants are opcodes for the xFileControl method |
755 | ** These integer constants are opcodes for the xFileControl method |
733 | ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] |
756 | ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] |
734 | ** interface. |
757 | ** interface. |
735 | ** |
758 | ** |
… | |
… | |
763 | ** to the [sqlite3_file] object associated with a particular database |
786 | ** to the [sqlite3_file] object associated with a particular database |
764 | ** connection. See the [sqlite3_file_control()] documentation for |
787 | ** connection. See the [sqlite3_file_control()] documentation for |
765 | ** additional information. |
788 | ** additional information. |
766 | ** |
789 | ** |
767 | ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]] |
790 | ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]] |
|
|
791 | ** No longer in use. |
|
|
792 | ** |
|
|
793 | ** <li>[[SQLITE_FCNTL_SYNC]] |
768 | ** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by |
794 | ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and |
769 | ** SQLite and sent to all VFSes in place of a call to the xSync method |
795 | ** sent to the VFS immediately before the xSync method is invoked on a |
770 | ** when the database connection has [PRAGMA synchronous] set to OFF.)^ |
796 | ** database file descriptor. Or, if the xSync method is not invoked |
771 | ** Some specialized VFSes need this signal in order to operate correctly |
797 | ** because the user has configured SQLite with |
772 | ** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most |
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 |
773 | ** VFSes do not need this signal and should silently ignore this opcode. |
803 | ** do not need this signal should silently ignore this opcode. Applications |
774 | ** Applications should not call [sqlite3_file_control()] with this |
804 | ** should not call [sqlite3_file_control()] with this opcode as doing so may |
775 | ** opcode as doing so may disrupt the operation of the specialized VFSes |
805 | ** disrupt the operation of the specialized VFSes that do require it. |
776 | ** 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 | ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]] |
815 | ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]] |
779 | ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic |
816 | ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic |
780 | ** retry counts and intervals for certain disk I/O operations for the |
817 | ** retry counts and intervals for certain disk I/O operations for the |
781 | ** windows [VFS] in order to provide robustness in the presence of |
818 | ** windows [VFS] in order to provide robustness in the presence of |
… | |
… | |
857 | ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA] |
894 | ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA] |
858 | ** file control occurs at the beginning of pragma statement analysis and so |
895 | ** file control occurs at the beginning of pragma statement analysis and so |
859 | ** it is able to override built-in [PRAGMA] statements. |
896 | ** it is able to override built-in [PRAGMA] statements. |
860 | ** |
897 | ** |
861 | ** <li>[[SQLITE_FCNTL_BUSYHANDLER]] |
898 | ** <li>[[SQLITE_FCNTL_BUSYHANDLER]] |
|
|
899 | ** ^The [SQLITE_FCNTL_BUSYHANDLER] |
862 | ** ^This file-control may be invoked by SQLite on the database file handle |
900 | ** file-control may be invoked by SQLite on the database file handle |
863 | ** shortly after it is opened in order to provide a custom VFS with access |
901 | ** shortly after it is opened in order to provide a custom VFS with access |
864 | ** to the connections busy-handler callback. The argument is of type (void **) |
902 | ** to the connections busy-handler callback. The argument is of type (void **) |
865 | ** - an array of two (void *) values. The first (void *) actually points |
903 | ** - an array of two (void *) values. The first (void *) actually points |
866 | ** to a function of type (int (*)(void *)). In order to invoke the connections |
904 | ** to a function of type (int (*)(void *)). In order to invoke the connections |
867 | ** busy-handler, this function should be invoked with the second (void *) in |
905 | ** busy-handler, this function should be invoked with the second (void *) in |
868 | ** the array as the only argument. If it returns non-zero, then the operation |
906 | ** the array as the only argument. If it returns non-zero, then the operation |
869 | ** should be retried. If it returns zero, the custom VFS should abandon the |
907 | ** should be retried. If it returns zero, the custom VFS should abandon the |
870 | ** current operation. |
908 | ** current operation. |
871 | ** |
909 | ** |
872 | ** <li>[[SQLITE_FCNTL_TEMPFILENAME]] |
910 | ** <li>[[SQLITE_FCNTL_TEMPFILENAME]] |
873 | ** ^Application can invoke this file-control to have SQLite generate a |
911 | ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control |
|
|
912 | ** to have SQLite generate a |
874 | ** temporary filename using the same algorithm that is followed to generate |
913 | ** temporary filename using the same algorithm that is followed to generate |
875 | ** temporary filenames for TEMP tables and other internal uses. The |
914 | ** temporary filenames for TEMP tables and other internal uses. The |
876 | ** argument should be a char** which will be filled with the filename |
915 | ** argument should be a char** which will be filled with the filename |
877 | ** written into memory obtained from [sqlite3_malloc()]. The caller should |
916 | ** written into memory obtained from [sqlite3_malloc()]. The caller should |
878 | ** invoke [sqlite3_free()] on the result to avoid a memory leak. |
917 | ** invoke [sqlite3_free()] on the result to avoid a memory leak. |
|
|
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. |
879 | ** |
948 | ** |
880 | ** </ul> |
949 | ** </ul> |
881 | */ |
950 | */ |
882 | #define SQLITE_FCNTL_LOCKSTATE 1 |
951 | #define SQLITE_FCNTL_LOCKSTATE 1 |
883 | #define SQLITE_GET_LOCKPROXYFILE 2 |
952 | #define SQLITE_GET_LOCKPROXYFILE 2 |
… | |
… | |
893 | #define SQLITE_FCNTL_VFSNAME 12 |
962 | #define SQLITE_FCNTL_VFSNAME 12 |
894 | #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13 |
963 | #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13 |
895 | #define SQLITE_FCNTL_PRAGMA 14 |
964 | #define SQLITE_FCNTL_PRAGMA 14 |
896 | #define SQLITE_FCNTL_BUSYHANDLER 15 |
965 | #define SQLITE_FCNTL_BUSYHANDLER 15 |
897 | #define SQLITE_FCNTL_TEMPFILENAME 16 |
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 | ** CAPI3REF: Mutex Handle |
975 | ** CAPI3REF: Mutex Handle |
901 | ** |
976 | ** |
902 | ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
977 | ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
… | |
… | |
1337 | ** of 8. Some allocators round up to a larger multiple or to a power of 2. |
1412 | ** of 8. Some allocators round up to a larger multiple or to a power of 2. |
1338 | ** Every memory allocation request coming in through [sqlite3_malloc()] |
1413 | ** Every memory allocation request coming in through [sqlite3_malloc()] |
1339 | ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, |
1414 | ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, |
1340 | ** that causes the corresponding memory allocation to fail. |
1415 | ** that causes the corresponding memory allocation to fail. |
1341 | ** |
1416 | ** |
1342 | ** The xInit method initializes the memory allocator. (For example, |
1417 | ** The xInit method initializes the memory allocator. For example, |
1343 | ** it might allocate any require mutexes or initialize internal data |
1418 | ** it might allocate any require mutexes or initialize internal data |
1344 | ** structures. The xShutdown method is invoked (indirectly) by |
1419 | ** structures. The xShutdown method is invoked (indirectly) by |
1345 | ** [sqlite3_shutdown()] and should deallocate any resources acquired |
1420 | ** [sqlite3_shutdown()] and should deallocate any resources acquired |
1346 | ** by xInit. The pAppData pointer is used as the only parameter to |
1421 | ** by xInit. The pAppData pointer is used as the only parameter to |
1347 | ** xInit and xShutdown. |
1422 | ** xInit and xShutdown. |
… | |
… | |
1559 | ** <dd> ^(This option takes a single argument which is a pointer to an |
1634 | ** <dd> ^(This option takes a single argument which is a pointer to an |
1560 | ** [sqlite3_pcache_methods2] object. SQLite copies of the current |
1635 | ** [sqlite3_pcache_methods2] object. SQLite copies of the current |
1561 | ** page cache implementation into that object.)^ </dd> |
1636 | ** page cache implementation into that object.)^ </dd> |
1562 | ** |
1637 | ** |
1563 | ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt> |
1638 | ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt> |
|
|
1639 | ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite |
|
|
1640 | ** global [error log]. |
1564 | ** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a |
1641 | ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a |
1565 | ** function with a call signature of void(*)(void*,int,const char*), |
1642 | ** function with a call signature of void(*)(void*,int,const char*), |
1566 | ** and a pointer to void. ^If the function pointer is not NULL, it is |
1643 | ** and a pointer to void. ^If the function pointer is not NULL, it is |
1567 | ** invoked by [sqlite3_log()] to process each logging event. ^If the |
1644 | ** invoked by [sqlite3_log()] to process each logging event. ^If the |
1568 | ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op. |
1645 | ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op. |
1569 | ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is |
1646 | ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is |
… | |
… | |
1577 | ** supplied by the application must not invoke any SQLite interface. |
1654 | ** supplied by the application must not invoke any SQLite interface. |
1578 | ** In a multi-threaded application, the application-defined logger |
1655 | ** In a multi-threaded application, the application-defined logger |
1579 | ** function must be threadsafe. </dd> |
1656 | ** function must be threadsafe. </dd> |
1580 | ** |
1657 | ** |
1581 | ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI |
1658 | ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI |
1582 | ** <dd> This option takes a single argument of type int. If non-zero, then |
1659 | ** <dd>^(This option takes a single argument of type int. If non-zero, then |
1583 | ** URI handling is globally enabled. If the parameter is zero, then URI handling |
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 | ** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or |
1662 | ** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or |
1586 | ** specified as part of [ATTACH] commands are interpreted as URIs, regardless |
1663 | ** specified as part of [ATTACH] commands are interpreted as URIs, regardless |
1587 | ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database |
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 | ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the |
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 | ** disabled. The default value may be changed by compiling with the |
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 | ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN |
1671 | ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN |
1595 | ** <dd> This option takes a single integer argument which is interpreted as |
1672 | ** <dd>^This option takes a single integer argument which is interpreted as |
1596 | ** a boolean in order to enable or disable the use of covering indices for |
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 | ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on" |
1675 | ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on" |
1599 | ** if that compile-time option is omitted. |
1676 | ** if that compile-time option is omitted. |
1600 | ** The ability to disable the use of covering indices for full table scans |
1677 | ** The ability to disable the use of covering indices for full table scans |
1601 | ** is because some incorrectly coded legacy applications might malfunction |
1678 | ** is because some incorrectly coded legacy applications might malfunction |
1602 | ** malfunction when the optimization is enabled. Providing the ability to |
1679 | ** when the optimization is enabled. Providing the ability to |
1603 | ** disable the optimization allows the older, buggy application code to work |
1680 | ** disable the optimization allows the older, buggy application code to work |
1604 | ** without change even with newer versions of SQLite. |
1681 | ** without change even with newer versions of SQLite. |
1605 | ** |
1682 | ** |
1606 | ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]] |
1683 | ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]] |
1607 | ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE |
1684 | ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE |
1608 | ** <dd> These options are obsolete and should not be used by new code. |
1685 | ** <dd> These options are obsolete and should not be used by new code. |
1609 | ** They are retained for backwards compatibility but are now no-ops. |
1686 | ** They are retained for backwards compatibility but are now no-ops. |
1610 | ** </dl> |
1687 | ** </dd> |
1611 | ** |
1688 | ** |
1612 | ** [[SQLITE_CONFIG_SQLLOG]] |
1689 | ** [[SQLITE_CONFIG_SQLLOG]] |
1613 | ** <dt>SQLITE_CONFIG_SQLLOG |
1690 | ** <dt>SQLITE_CONFIG_SQLLOG |
1614 | ** <dd>This option is only available if sqlite is compiled with the |
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 | ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int). |
1693 | ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int). |
1617 | ** The second should be of type (void*). The callback is invoked by the library |
1694 | ** The second should be of type (void*). The callback is invoked by the library |
1618 | ** in three separate circumstances, identified by the value passed as the |
1695 | ** in three separate circumstances, identified by the value passed as the |
1619 | ** fourth parameter. If the fourth parameter is 0, then the database connection |
1696 | ** fourth parameter. If the fourth parameter is 0, then the database connection |
1620 | ** passed as the second argument has just been opened. The third argument |
1697 | ** passed as the second argument has just been opened. The third argument |
1621 | ** points to a buffer containing the name of the main database file. If the |
1698 | ** points to a buffer containing the name of the main database file. If the |
1622 | ** fourth parameter is 1, then the SQL statement that the third parameter |
1699 | ** fourth parameter is 1, then the SQL statement that the third parameter |
1623 | ** points to has just been executed. Or, if the fourth parameter is 2, then |
1700 | ** points to has just been executed. Or, if the fourth parameter is 2, then |
1624 | ** the connection being passed as the second parameter is being closed. The |
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 | ** </dl> |
1726 | ** </dl> |
1627 | */ |
1727 | */ |
1628 | #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
1728 | #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
1629 | #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
1729 | #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
1630 | #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
1730 | #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
… | |
… | |
1644 | #define SQLITE_CONFIG_URI 17 /* int */ |
1744 | #define SQLITE_CONFIG_URI 17 /* int */ |
1645 | #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ |
1745 | #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ |
1646 | #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ |
1746 | #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ |
1647 | #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ |
1747 | #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ |
1648 | #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ |
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 | ** CAPI3REF: Database Connection Configuration Options |
1753 | ** CAPI3REF: Database Connection Configuration Options |
1652 | ** |
1754 | ** |
1653 | ** These constants are the available integer configuration options that |
1755 | ** These constants are the available integer configuration options that |
… | |
… | |
1720 | SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); |
1822 | SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); |
1721 | |
1823 | |
1722 | /* |
1824 | /* |
1723 | ** CAPI3REF: Last Insert Rowid |
1825 | ** CAPI3REF: Last Insert Rowid |
1724 | ** |
1826 | ** |
1725 | ** ^Each entry in an SQLite table has a unique 64-bit signed |
1827 | ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables) |
|
|
1828 | ** has a unique 64-bit signed |
1726 | ** integer key called the [ROWID | "rowid"]. ^The rowid is always available |
1829 | ** integer key called the [ROWID | "rowid"]. ^The rowid is always available |
1727 | ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those |
1830 | ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those |
1728 | ** names are not also used by explicitly declared columns. ^If |
1831 | ** names are not also used by explicitly declared columns. ^If |
1729 | ** the table has a column of type [INTEGER PRIMARY KEY] then that column |
1832 | ** the table has a column of type [INTEGER PRIMARY KEY] then that column |
1730 | ** is another alias for the rowid. |
1833 | ** is another alias for the rowid. |
1731 | ** |
1834 | ** |
1732 | ** ^This routine returns the [rowid] of the most recent |
1835 | ** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the |
1733 | ** successful [INSERT] into the database from the [database connection] |
1836 | ** most recent successful [INSERT] into a rowid table or [virtual table] |
1734 | ** in the first argument. ^As of SQLite version 3.7.7, this routines |
1837 | ** on database connection D. |
1735 | ** records the last insert rowid of both ordinary tables and [virtual tables]. |
1838 | ** ^Inserts into [WITHOUT ROWID] tables are not recorded. |
1736 | ** ^If no successful [INSERT]s |
1839 | ** ^If no successful [INSERT]s into rowid tables |
1737 | ** have ever occurred on that database connection, zero is returned. |
1840 | ** have ever occurred on the database connection D, |
|
|
1841 | ** then sqlite3_last_insert_rowid(D) returns zero. |
1738 | ** |
1842 | ** |
1739 | ** ^(If an [INSERT] occurs within a trigger or within a [virtual table] |
1843 | ** ^(If an [INSERT] occurs within a trigger or within a [virtual table] |
1740 | ** method, then this routine will return the [rowid] of the inserted |
1844 | ** method, then this routine will return the [rowid] of the inserted |
1741 | ** row as long as the trigger or virtual table method is running. |
1845 | ** row as long as the trigger or virtual table method is running. |
1742 | ** But once the trigger or virtual table method ends, the value returned |
1846 | ** But once the trigger or virtual table method ends, the value returned |
… | |
… | |
1924 | SQLITE_API int sqlite3_complete16(const void *sql); |
2028 | SQLITE_API int sqlite3_complete16(const void *sql); |
1925 | |
2029 | |
1926 | /* |
2030 | /* |
1927 | ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
2031 | ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
1928 | ** |
2032 | ** |
1929 | ** ^This routine sets a callback function that might be invoked whenever |
2033 | ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X |
1930 | ** an attempt is made to open a database table that another thread |
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 |
1931 | ** or process has locked. |
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] or [SQLITE_IOERR_BLOCKED] |
2041 | ** ^If the busy callback is NULL, then [SQLITE_BUSY] |
1934 | ** is returned immediately upon encountering the lock. ^If the busy callback |
2042 | ** is returned immediately upon encountering the lock. ^If the busy callback |
1935 | ** is not NULL, then the callback might be invoked with two arguments. |
2043 | ** is not NULL, then the callback might be invoked with two arguments. |
1936 | ** |
2044 | ** |
1937 | ** ^The first argument to the busy handler is a copy of the void* pointer which |
2045 | ** ^The first argument to the busy handler is a copy of the void* pointer which |
1938 | ** is the third argument to sqlite3_busy_handler(). ^The second argument to |
2046 | ** is the third argument to sqlite3_busy_handler(). ^The second argument to |
1939 | ** the busy handler callback is the number of times that the busy handler has |
2047 | ** the busy handler callback is the number of times that the busy handler has |
1940 | ** been invoked for this locking event. ^If the |
2048 | ** been invoked for the same locking event. ^If the |
1941 | ** busy callback returns 0, then no additional attempts are made to |
2049 | ** busy callback returns 0, then no additional attempts are made to |
1942 | ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. |
2050 | ** access the database and [SQLITE_BUSY] is returned |
|
|
2051 | ** to the application. |
1943 | ** ^If the callback returns non-zero, then another attempt |
2052 | ** ^If the callback returns non-zero, then another attempt |
1944 | ** is made to open the database for reading and the cycle repeats. |
2053 | ** is made to access the database and the cycle repeats. |
1945 | ** |
2054 | ** |
1946 | ** The presence of a busy handler does not guarantee that it will be invoked |
2055 | ** The presence of a busy handler does not guarantee that it will be invoked |
1947 | ** when there is lock contention. ^If SQLite determines that invoking the busy |
2056 | ** when there is lock contention. ^If SQLite determines that invoking the busy |
1948 | ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] |
2057 | ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] |
1949 | ** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. |
2058 | ** to the application instead of invoking the |
|
|
2059 | ** busy handler. |
1950 | ** Consider a scenario where one process is holding a read lock that |
2060 | ** Consider a scenario where one process is holding a read lock that |
1951 | ** it is trying to promote to a reserved lock and |
2061 | ** it is trying to promote to a reserved lock and |
1952 | ** a second process is holding a reserved lock that it is trying |
2062 | ** a second process is holding a reserved lock that it is trying |
1953 | ** to promote to an exclusive lock. The first process cannot proceed |
2063 | ** to promote to an exclusive lock. The first process cannot proceed |
1954 | ** because it is blocked by the second and the second process cannot |
2064 | ** because it is blocked by the second and the second process cannot |
… | |
… | |
1958 | ** will induce the first process to release its read lock and allow |
2068 | ** will induce the first process to release its read lock and allow |
1959 | ** the second process to proceed. |
2069 | ** the second process to proceed. |
1960 | ** |
2070 | ** |
1961 | ** ^The default busy callback is NULL. |
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 | ** ^(There can only be a single busy handler defined for each |
2073 | ** ^(There can only be a single busy handler defined for each |
1979 | ** [database connection]. Setting a new busy handler clears any |
2074 | ** [database connection]. Setting a new busy handler clears any |
1980 | ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] |
2075 | ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] |
1981 | ** will also set or clear the busy handler. |
2076 | ** or evaluating [PRAGMA busy_timeout=N] will change the |
|
|
2077 | ** busy handler and thus clear any previously set busy handler. |
1982 | ** |
2078 | ** |
1983 | ** The busy callback should not take any actions which modify the |
2079 | ** The busy callback should not take any actions which modify the |
1984 | ** database connection that invoked the busy handler. Any such actions |
2080 | ** database connection that invoked the busy handler. In other words, |
|
|
2081 | ** the busy handler is not reentrant. Any such actions |
1985 | ** result in undefined behavior. |
2082 | ** result in undefined behavior. |
1986 | ** |
2083 | ** |
1987 | ** A busy handler must not close the database connection |
2084 | ** A busy handler must not close the database connection |
1988 | ** or [prepared statement] that invoked the busy handler. |
2085 | ** or [prepared statement] that invoked the busy handler. |
1989 | */ |
2086 | */ |
… | |
… | |
1995 | ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps |
2092 | ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps |
1996 | ** for a specified amount of time when a table is locked. ^The handler |
2093 | ** for a specified amount of time when a table is locked. ^The handler |
1997 | ** will sleep multiple times until at least "ms" milliseconds of sleeping |
2094 | ** will sleep multiple times until at least "ms" milliseconds of sleeping |
1998 | ** have accumulated. ^After at least "ms" milliseconds of sleeping, |
2095 | ** have accumulated. ^After at least "ms" milliseconds of sleeping, |
1999 | ** the handler returns 0 which causes [sqlite3_step()] to return |
2096 | ** the handler returns 0 which causes [sqlite3_step()] to return |
2000 | ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. |
2097 | ** [SQLITE_BUSY]. |
2001 | ** |
2098 | ** |
2002 | ** ^Calling this routine with an argument less than or equal to zero |
2099 | ** ^Calling this routine with an argument less than or equal to zero |
2003 | ** turns off all busy handlers. |
2100 | ** turns off all busy handlers. |
2004 | ** |
2101 | ** |
2005 | ** ^(There can only be a single busy handler for a particular |
2102 | ** ^(There can only be a single busy handler for a particular |
2006 | ** [database connection] any any given moment. If another busy handler |
2103 | ** [database connection] at any given moment. If another busy handler |
2007 | ** was defined (using [sqlite3_busy_handler()]) prior to calling |
2104 | ** was defined (using [sqlite3_busy_handler()]) prior to calling |
2008 | ** this routine, that other busy handler is cleared.)^ |
2105 | ** this routine, that other busy handler is cleared.)^ |
|
|
2106 | ** |
|
|
2107 | ** See also: [PRAGMA busy_timeout] |
2009 | */ |
2108 | */ |
2010 | SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
2109 | SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
2011 | |
2110 | |
2012 | /* |
2111 | /* |
2013 | ** CAPI3REF: Convenience Routines For Running Queries |
2112 | ** CAPI3REF: Convenience Routines For Running Queries |
… | |
… | |
2203 | ** ^If sqlite3_malloc() is unable to obtain sufficient free |
2302 | ** ^If sqlite3_malloc() is unable to obtain sufficient free |
2204 | ** memory, it returns a NULL pointer. ^If the parameter N to |
2303 | ** memory, it returns a NULL pointer. ^If the parameter N to |
2205 | ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns |
2304 | ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns |
2206 | ** a NULL pointer. |
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 | ** ^Calling sqlite3_free() with a pointer previously returned |
2311 | ** ^Calling sqlite3_free() with a pointer previously returned |
2209 | ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so |
2312 | ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so |
2210 | ** that it might be reused. ^The sqlite3_free() routine is |
2313 | ** that it might be reused. ^The sqlite3_free() routine is |
2211 | ** a no-op if is called with a NULL pointer. Passing a NULL pointer |
2314 | ** a no-op if is called with a NULL pointer. Passing a NULL pointer |
2212 | ** to sqlite3_free() is harmless. After being freed, memory |
2315 | ** to sqlite3_free() is harmless. After being freed, memory |
… | |
… | |
2214 | ** memory might result in a segmentation fault or other severe error. |
2317 | ** memory might result in a segmentation fault or other severe error. |
2215 | ** Memory corruption, a segmentation fault, or other severe error |
2318 | ** Memory corruption, a segmentation fault, or other severe error |
2216 | ** might result if sqlite3_free() is called with a non-NULL pointer that |
2319 | ** might result if sqlite3_free() is called with a non-NULL pointer that |
2217 | ** was not obtained from sqlite3_malloc() or sqlite3_realloc(). |
2320 | ** was not obtained from sqlite3_malloc() or sqlite3_realloc(). |
2218 | ** |
2321 | ** |
2219 | ** ^(The sqlite3_realloc() interface attempts to resize a |
2322 | ** ^The sqlite3_realloc(X,N) interface attempts to resize a |
2220 | ** prior memory allocation to be at least N bytes, where N is the |
2323 | ** prior memory allocation X to be at least N bytes. |
2221 | ** second parameter. The memory allocation to be resized is the first |
2324 | ** ^If the X parameter to sqlite3_realloc(X,N) |
2222 | ** parameter.)^ ^ If the first parameter to sqlite3_realloc() |
|
|
2223 | ** is a NULL pointer then its behavior is identical to calling |
2325 | ** is a NULL pointer then its behavior is identical to calling |
2224 | ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). |
2326 | ** sqlite3_malloc(N). |
2225 | ** ^If the second parameter to sqlite3_realloc() is zero or |
2327 | ** ^If the N parameter to sqlite3_realloc(X,N) is zero or |
2226 | ** negative then the behavior is exactly the same as calling |
2328 | ** negative then the behavior is exactly the same as calling |
2227 | ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). |
2329 | ** sqlite3_free(X). |
2228 | ** ^sqlite3_realloc() returns a pointer to a memory allocation |
2330 | ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation |
2229 | ** of at least N bytes in size or NULL if sufficient memory is unavailable. |
2331 | ** of at least N bytes in size or NULL if insufficient memory is available. |
2230 | ** ^If M is the size of the prior allocation, then min(N,M) bytes |
2332 | ** ^If M is the size of the prior allocation, then min(N,M) bytes |
2231 | ** of the prior allocation are copied into the beginning of buffer returned |
2333 | ** of the prior allocation are copied into the beginning of buffer returned |
2232 | ** by sqlite3_realloc() and the prior allocation is freed. |
2334 | ** by sqlite3_realloc(X,N) and the prior allocation is freed. |
2233 | ** ^If sqlite3_realloc() returns NULL, then the prior allocation |
2335 | ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the |
2234 | ** is not freed. |
2336 | ** prior allocation is not freed. |
2235 | ** |
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 | ** |
2236 | ** ^The memory returned by sqlite3_malloc() and sqlite3_realloc() |
2352 | ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(), |
|
|
2353 | ** sqlite3_malloc64(), and sqlite3_realloc64() |
2237 | ** is always aligned to at least an 8 byte boundary, or to a |
2354 | ** is always aligned to at least an 8 byte boundary, or to a |
2238 | ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time |
2355 | ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time |
2239 | ** option is used. |
2356 | ** option is used. |
2240 | ** |
2357 | ** |
2241 | ** In SQLite version 3.5.0 and 3.5.1, it was possible to define |
2358 | ** In SQLite version 3.5.0 and 3.5.1, it was possible to define |
… | |
… | |
2259 | ** The application must not read or write any part of |
2376 | ** The application must not read or write any part of |
2260 | ** a block of memory after it has been released using |
2377 | ** a block of memory after it has been released using |
2261 | ** [sqlite3_free()] or [sqlite3_realloc()]. |
2378 | ** [sqlite3_free()] or [sqlite3_realloc()]. |
2262 | */ |
2379 | */ |
2263 | SQLITE_API void *sqlite3_malloc(int); |
2380 | SQLITE_API void *sqlite3_malloc(int); |
|
|
2381 | SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); |
2264 | SQLITE_API void *sqlite3_realloc(void*, int); |
2382 | SQLITE_API void *sqlite3_realloc(void*, int); |
|
|
2383 | SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); |
2265 | SQLITE_API void sqlite3_free(void*); |
2384 | SQLITE_API void sqlite3_free(void*); |
|
|
2385 | SQLITE_API sqlite3_uint64 sqlite3_msize(void*); |
2266 | |
2386 | |
2267 | /* |
2387 | /* |
2268 | ** CAPI3REF: Memory Allocator Statistics |
2388 | ** CAPI3REF: Memory Allocator Statistics |
2269 | ** |
2389 | ** |
2270 | ** SQLite provides these two interfaces for reporting on the status |
2390 | ** SQLite provides these two interfaces for reporting on the status |
… | |
… | |
2298 | ** already uses the largest possible [ROWID]. The PRNG is also used for |
2418 | ** already uses the largest possible [ROWID]. The PRNG is also used for |
2299 | ** the build-in random() and randomblob() SQL functions. This interface allows |
2419 | ** the build-in random() and randomblob() SQL functions. This interface allows |
2300 | ** applications to access the same PRNG for other purposes. |
2420 | ** applications to access the same PRNG for other purposes. |
2301 | ** |
2421 | ** |
2302 | ** ^A call to this routine stores N bytes of randomness into buffer P. |
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 | ** ^The first time this routine is invoked (either internally or by |
2425 | ** ^If this routine has not been previously called or if the previous |
2305 | ** the application) the PRNG is seeded using randomness obtained |
2426 | ** call had N less than one, then the PRNG is seeded using randomness |
2306 | ** from the xRandomness method of the default [sqlite3_vfs] object. |
2427 | ** obtained from the xRandomness method of the default [sqlite3_vfs] object. |
2307 | ** ^On all subsequent invocations, the pseudo-randomness is generated |
2428 | ** ^If the previous call to this routine had an N of 1 or more then |
|
|
2429 | ** the pseudo-randomness is generated |
2308 | ** internally and without recourse to the [sqlite3_vfs] xRandomness |
2430 | ** internally and without recourse to the [sqlite3_vfs] xRandomness |
2309 | ** method. |
2431 | ** method. |
2310 | */ |
2432 | */ |
2311 | SQLITE_API void sqlite3_randomness(int N, void *P); |
2433 | SQLITE_API void sqlite3_randomness(int N, void *P); |
2312 | |
2434 | |
… | |
… | |
2403 | ** return either [SQLITE_OK] or one of these two constants in order |
2525 | ** return either [SQLITE_OK] or one of these two constants in order |
2404 | ** to signal SQLite whether or not the action is permitted. See the |
2526 | ** to signal SQLite whether or not the action is permitted. See the |
2405 | ** [sqlite3_set_authorizer | authorizer documentation] for additional |
2527 | ** [sqlite3_set_authorizer | authorizer documentation] for additional |
2406 | ** information. |
2528 | ** information. |
2407 | ** |
2529 | ** |
2408 | ** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code] |
2530 | ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode] |
2409 | ** from the [sqlite3_vtab_on_conflict()] interface. |
2531 | ** returned from the [sqlite3_vtab_on_conflict()] interface. |
2410 | */ |
2532 | */ |
2411 | #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ |
2533 | #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ |
2412 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
2534 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
2413 | |
2535 | |
2414 | /* |
2536 | /* |
… | |
… | |
2462 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ |
2584 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ |
2463 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
2585 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
2464 | #define SQLITE_FUNCTION 31 /* NULL Function Name */ |
2586 | #define SQLITE_FUNCTION 31 /* NULL Function Name */ |
2465 | #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ |
2587 | #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ |
2466 | #define SQLITE_COPY 0 /* No longer used */ |
2588 | #define SQLITE_COPY 0 /* No longer used */ |
|
|
2589 | #define SQLITE_RECURSIVE 33 /* NULL NULL */ |
2467 | |
2590 | |
2468 | /* |
2591 | /* |
2469 | ** CAPI3REF: Tracing And Profiling Functions |
2592 | ** CAPI3REF: Tracing And Profiling Functions |
2470 | ** |
2593 | ** |
2471 | ** These routines register callback functions that can be used for |
2594 | ** These routines register callback functions that can be used for |
… | |
… | |
2476 | ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the |
2599 | ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the |
2477 | ** SQL statement text as the statement first begins executing. |
2600 | ** SQL statement text as the statement first begins executing. |
2478 | ** ^(Additional sqlite3_trace() callbacks might occur |
2601 | ** ^(Additional sqlite3_trace() callbacks might occur |
2479 | ** as each triggered subprogram is entered. The callbacks for triggers |
2602 | ** as each triggered subprogram is entered. The callbacks for triggers |
2480 | ** contain a UTF-8 SQL comment that identifies the trigger.)^ |
2603 | ** contain a UTF-8 SQL comment that identifies the trigger.)^ |
|
|
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(). |
2481 | ** |
2607 | ** |
2482 | ** ^The callback function registered by sqlite3_profile() is invoked |
2608 | ** ^The callback function registered by sqlite3_profile() is invoked |
2483 | ** as each SQL statement finishes. ^The profile callback contains |
2609 | ** as each SQL statement finishes. ^The profile callback contains |
2484 | ** the original statement text and an estimate of wall-clock time |
2610 | ** the original statement text and an estimate of wall-clock time |
2485 | ** of how long that statement took to run. ^The profile callback |
2611 | ** of how long that statement took to run. ^The profile callback |
… | |
… | |
2502 | ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for |
2628 | ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for |
2503 | ** database connection D. An example use for this |
2629 | ** database connection D. An example use for this |
2504 | ** interface is to keep a GUI updated during a large query. |
2630 | ** interface is to keep a GUI updated during a large query. |
2505 | ** |
2631 | ** |
2506 | ** ^The parameter P is passed through as the only parameter to the |
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 | ** [virtual machine instructions] that are evaluated between successive |
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 | ** ^Only a single progress handler may be defined at one time per |
2638 | ** ^Only a single progress handler may be defined at one time per |
2512 | ** [database connection]; setting a new progress handler cancels the |
2639 | ** [database connection]; setting a new progress handler cancels the |
2513 | ** old one. ^Setting parameter X to NULL disables the progress handler. |
2640 | ** old one. ^Setting parameter X to NULL disables the progress handler. |
2514 | ** ^The progress handler is also disabled by setting N to a value less |
2641 | ** ^The progress handler is also disabled by setting N to a value less |
… | |
… | |
2540 | ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The |
2667 | ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The |
2541 | ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain |
2668 | ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain |
2542 | ** an English language description of the error following a failure of any |
2669 | ** an English language description of the error following a failure of any |
2543 | ** of the sqlite3_open() routines. |
2670 | ** of the sqlite3_open() routines. |
2544 | ** |
2671 | ** |
2545 | ** ^The default encoding for the database will be UTF-8 if |
2672 | ** ^The default encoding will be UTF-8 for databases created using |
2546 | ** sqlite3_open() or sqlite3_open_v2() is called and |
2673 | ** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases |
2547 | ** UTF-16 in the native byte order if sqlite3_open16() is used. |
2674 | ** created using sqlite3_open16() will be UTF-16 in the native byte order. |
2548 | ** |
2675 | ** |
2549 | ** Whether or not an error occurs when it is opened, resources |
2676 | ** Whether or not an error occurs when it is opened, resources |
2550 | ** associated with the [database connection] handle should be released by |
2677 | ** associated with the [database connection] handle should be released by |
2551 | ** passing it to [sqlite3_close()] when it is no longer required. |
2678 | ** passing it to [sqlite3_close()] when it is no longer required. |
2552 | ** |
2679 | ** |
… | |
… | |
2630 | ** ^SQLite uses the path component of the URI as the name of the disk file |
2757 | ** ^SQLite uses the path component of the URI as the name of the disk file |
2631 | ** which contains the database. ^If the path begins with a '/' character, |
2758 | ** which contains the database. ^If the path begins with a '/' character, |
2632 | ** then it is interpreted as an absolute path. ^If the path does not begin |
2759 | ** then it is interpreted as an absolute path. ^If the path does not begin |
2633 | ** with a '/' (meaning that the authority section is omitted from the URI) |
2760 | ** with a '/' (meaning that the authority section is omitted from the URI) |
2634 | ** then the path is interpreted as a relative path. |
2761 | ** then the path is interpreted as a relative path. |
2635 | ** ^On windows, the first component of an absolute path |
2762 | ** ^(On windows, the first component of an absolute path |
2636 | ** is a drive specification (e.g. "C:"). |
2763 | ** is a drive specification (e.g. "C:").)^ |
2637 | ** |
2764 | ** |
2638 | ** [[core URI query parameters]] |
2765 | ** [[core URI query parameters]] |
2639 | ** The query component of a URI may contain parameters that are interpreted |
2766 | ** The query component of a URI may contain parameters that are interpreted |
2640 | ** either by SQLite itself, or by a [VFS | custom VFS implementation]. |
2767 | ** either by SQLite itself, or by a [VFS | custom VFS implementation]. |
2641 | ** SQLite interprets the following three query parameters: |
2768 | ** SQLite and its built-in [VFSes] interpret the |
|
|
2769 | ** following query parameters: |
2642 | ** |
2770 | ** |
2643 | ** <ul> |
2771 | ** <ul> |
2644 | ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of |
2772 | ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of |
2645 | ** a VFS object that provides the operating system interface that should |
2773 | ** a VFS object that provides the operating system interface that should |
2646 | ** be used to access the database file on disk. ^If this option is set to |
2774 | ** be used to access the database file on disk. ^If this option is set to |
… | |
… | |
2668 | ** "private". ^Setting it to "shared" is equivalent to setting the |
2796 | ** "private". ^Setting it to "shared" is equivalent to setting the |
2669 | ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to |
2797 | ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to |
2670 | ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is |
2798 | ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is |
2671 | ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. |
2799 | ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. |
2672 | ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in |
2800 | ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in |
2673 | ** a URI filename, its value overrides any behaviour requested by setting |
2801 | ** a URI filename, its value overrides any behavior requested by setting |
2674 | ** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. |
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 | ** </ul> |
2825 | ** </ul> |
2676 | ** |
2826 | ** |
2677 | ** ^Specifying an unknown parameter in the query component of a URI is not an |
2827 | ** ^Specifying an unknown parameter in the query component of a URI is not an |
2678 | ** error. Future versions of SQLite might understand additional query |
2828 | ** error. Future versions of SQLite might understand additional query |
2679 | ** parameters. See "[query parameters with special meaning to SQLite]" for |
2829 | ** parameters. See "[query parameters with special meaning to SQLite]" for |
… | |
… | |
2699 | ** in URI filenames. |
2849 | ** in URI filenames. |
2700 | ** <tr><td> file:data.db?mode=ro&cache=private <td> |
2850 | ** <tr><td> file:data.db?mode=ro&cache=private <td> |
2701 | ** Open file "data.db" in the current directory for read-only access. |
2851 | ** Open file "data.db" in the current directory for read-only access. |
2702 | ** Regardless of whether or not shared-cache mode is enabled by |
2852 | ** Regardless of whether or not shared-cache mode is enabled by |
2703 | ** default, use a private cache. |
2853 | ** default, use a private cache. |
2704 | ** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td> |
2854 | ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td> |
2705 | ** Open file "/home/fred/data.db". Use the special VFS "unix-nolock". |
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 | ** <tr><td> file:data.db?mode=readonly <td> |
2857 | ** <tr><td> file:data.db?mode=readonly <td> |
2707 | ** An error. "readonly" is not a valid option for the "mode" parameter. |
2858 | ** An error. "readonly" is not a valid option for the "mode" parameter. |
2708 | ** </table> |
2859 | ** </table> |
2709 | ** |
2860 | ** |
2710 | ** ^URI hexadecimal escape sequences (%HH) are supported within the path and |
2861 | ** ^URI hexadecimal escape sequences (%HH) are supported within the path and |
… | |
… | |
2946 | ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> |
3097 | ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> |
2947 | ** <dd>The maximum index number of any [parameter] in an SQL statement.)^ |
3098 | ** <dd>The maximum index number of any [parameter] in an SQL statement.)^ |
2948 | ** |
3099 | ** |
2949 | ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> |
3100 | ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> |
2950 | ** <dd>The maximum depth of recursion for triggers.</dd>)^ |
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 | ** </dl> |
3106 | ** </dl> |
2952 | */ |
3107 | */ |
2953 | #define SQLITE_LIMIT_LENGTH 0 |
3108 | #define SQLITE_LIMIT_LENGTH 0 |
2954 | #define SQLITE_LIMIT_SQL_LENGTH 1 |
3109 | #define SQLITE_LIMIT_SQL_LENGTH 1 |
2955 | #define SQLITE_LIMIT_COLUMN 2 |
3110 | #define SQLITE_LIMIT_COLUMN 2 |
… | |
… | |
2959 | #define SQLITE_LIMIT_FUNCTION_ARG 6 |
3114 | #define SQLITE_LIMIT_FUNCTION_ARG 6 |
2960 | #define SQLITE_LIMIT_ATTACHED 7 |
3115 | #define SQLITE_LIMIT_ATTACHED 7 |
2961 | #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 |
3116 | #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 |
2962 | #define SQLITE_LIMIT_VARIABLE_NUMBER 9 |
3117 | #define SQLITE_LIMIT_VARIABLE_NUMBER 9 |
2963 | #define SQLITE_LIMIT_TRIGGER_DEPTH 10 |
3118 | #define SQLITE_LIMIT_TRIGGER_DEPTH 10 |
|
|
3119 | #define SQLITE_LIMIT_WORKER_THREADS 11 |
2964 | |
3120 | |
2965 | /* |
3121 | /* |
2966 | ** CAPI3REF: Compiling An SQL Statement |
3122 | ** CAPI3REF: Compiling An SQL Statement |
2967 | ** KEYWORDS: {SQL statement compiler} |
3123 | ** KEYWORDS: {SQL statement compiler} |
2968 | ** |
3124 | ** |
… | |
… | |
3015 | ** |
3171 | ** |
3016 | ** <ol> |
3172 | ** <ol> |
3017 | ** <li> |
3173 | ** <li> |
3018 | ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it |
3174 | ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it |
3019 | ** always used to do, [sqlite3_step()] will automatically recompile the SQL |
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 | ** </li> |
3178 | ** </li> |
3022 | ** |
3179 | ** |
3023 | ** <li> |
3180 | ** <li> |
3024 | ** ^When an error occurs, [sqlite3_step()] will return one of the detailed |
3181 | ** ^When an error occurs, [sqlite3_step()] will return one of the detailed |
3025 | ** [error codes] or [extended error codes]. ^The legacy behavior was that |
3182 | ** [error codes] or [extended error codes]. ^The legacy behavior was that |
… | |
… | |
3037 | ** to the [sqlite3_bind_text | bindings] of that [parameter]. |
3194 | ** to the [sqlite3_bind_text | bindings] of that [parameter]. |
3038 | ** ^The specific value of WHERE-clause [parameter] might influence the |
3195 | ** ^The specific value of WHERE-clause [parameter] might influence the |
3039 | ** choice of query plan if the parameter is the left-hand side of a [LIKE] |
3196 | ** choice of query plan if the parameter is the left-hand side of a [LIKE] |
3040 | ** or [GLOB] operator or if the parameter is compared to an indexed column |
3197 | ** or [GLOB] operator or if the parameter is compared to an indexed column |
3041 | ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. |
3198 | ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. |
3042 | ** the |
|
|
3043 | ** </li> |
3199 | ** </li> |
3044 | ** </ol> |
3200 | ** </ol> |
3045 | */ |
3201 | */ |
3046 | SQLITE_API int sqlite3_prepare( |
3202 | SQLITE_API int sqlite3_prepare( |
3047 | sqlite3 *db, /* Database handle */ |
3203 | sqlite3 *db, /* Database handle */ |
… | |
… | |
3219 | ** for "?NNN" parameters is the value of NNN. |
3375 | ** for "?NNN" parameters is the value of NNN. |
3220 | ** ^The NNN value must be between 1 and the [sqlite3_limit()] |
3376 | ** ^The NNN value must be between 1 and the [sqlite3_limit()] |
3221 | ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). |
3377 | ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). |
3222 | ** |
3378 | ** |
3223 | ** ^The third argument is the value to bind to the parameter. |
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 | ** ^(In those routines that have a fourth argument, its value is the |
3384 | ** ^(In those routines that have a fourth argument, its value is the |
3226 | ** number of bytes in the parameter. To be clear: the value is the |
3385 | ** number of bytes in the parameter. To be clear: the value is the |
3227 | ** number of <u>bytes</u> in the value, not the number of characters.)^ |
3386 | ** number of <u>bytes</u> in the value, not the number of characters.)^ |
3228 | ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() |
3387 | ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() |
3229 | ** is negative, then the length of the string is |
3388 | ** is negative, then the length of the string is |
3230 | ** the number of bytes up to the first zero terminator. |
3389 | ** the number of bytes up to the first zero terminator. |
3231 | ** If the fourth parameter to sqlite3_bind_blob() is negative, then |
3390 | ** If the fourth parameter to sqlite3_bind_blob() is negative, then |
3232 | ** the behavior is undefined. |
3391 | ** the behavior is undefined. |
3233 | ** If a non-negative fourth parameter is provided to sqlite3_bind_text() |
3392 | ** If a non-negative fourth parameter is provided to sqlite3_bind_text() |
3234 | ** or sqlite3_bind_text16() then that parameter must be the byte offset |
3393 | ** or sqlite3_bind_text16() or sqlite3_bind_text64() then |
|
|
3394 | ** that parameter must be the byte offset |
3235 | ** where the NUL terminator would occur assuming the string were NUL |
3395 | ** where the NUL terminator would occur assuming the string were NUL |
3236 | ** terminated. If any NUL characters occur at byte offsets less than |
3396 | ** terminated. If any NUL characters occur at byte offsets less than |
3237 | ** the value of the fourth parameter then the resulting string value will |
3397 | ** the value of the fourth parameter then the resulting string value will |
3238 | ** contain embedded NULs. The result of expressions involving strings |
3398 | ** contain embedded NULs. The result of expressions involving strings |
3239 | ** with embedded NULs is undefined. |
3399 | ** with embedded NULs is undefined. |
3240 | ** |
3400 | ** |
3241 | ** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and |
3401 | ** ^The fifth argument to the BLOB and string binding interfaces |
3242 | ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or |
3402 | ** is a destructor used to dispose of the BLOB or |
3243 | ** string after SQLite has finished with it. ^The destructor is called |
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 sqlite3_bind_blob(), |
3404 | ** to dispose of the BLOB or string even if the call to bind API fails. |
3245 | ** sqlite3_bind_text(), or sqlite3_bind_text16() fails. |
|
|
3246 | ** ^If the fifth argument is |
3405 | ** ^If the fifth argument is |
3247 | ** the special value [SQLITE_STATIC], then SQLite assumes that the |
3406 | ** the special value [SQLITE_STATIC], then SQLite assumes that the |
3248 | ** information is in static, unmanaged space and does not need to be freed. |
3407 | ** information is in static, unmanaged space and does not need to be freed. |
3249 | ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then |
3408 | ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then |
3250 | ** SQLite makes its own private copy of the data immediately, before |
3409 | ** SQLite makes its own private copy of the data immediately, before |
3251 | ** the sqlite3_bind_*() routine returns. |
3410 | ** the sqlite3_bind_*() routine returns. |
|
|
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. |
3252 | ** |
3419 | ** |
3253 | ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that |
3420 | ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that |
3254 | ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory |
3421 | ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory |
3255 | ** (just an integer to hold its size) while it is being processed. |
3422 | ** (just an integer to hold its size) while it is being processed. |
3256 | ** Zeroblobs are intended to serve as placeholders for BLOBs whose |
3423 | ** Zeroblobs are intended to serve as placeholders for BLOBs whose |
… | |
… | |
3268 | ** ^Bindings are not cleared by the [sqlite3_reset()] routine. |
3435 | ** ^Bindings are not cleared by the [sqlite3_reset()] routine. |
3269 | ** ^Unbound parameters are interpreted as NULL. |
3436 | ** ^Unbound parameters are interpreted as NULL. |
3270 | ** |
3437 | ** |
3271 | ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an |
3438 | ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an |
3272 | ** [error code] if anything goes wrong. |
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 | ** ^[SQLITE_RANGE] is returned if the parameter |
3443 | ** ^[SQLITE_RANGE] is returned if the parameter |
3274 | ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. |
3444 | ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. |
3275 | ** |
3445 | ** |
3276 | ** See also: [sqlite3_bind_parameter_count()], |
3446 | ** See also: [sqlite3_bind_parameter_count()], |
3277 | ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. |
3447 | ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. |
3278 | */ |
3448 | */ |
3279 | SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); |
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 | SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); |
3452 | SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); |
3281 | SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); |
3453 | SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); |
3282 | SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
3454 | SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
3283 | SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); |
3455 | SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); |
3284 | SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); |
3456 | SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); |
3285 | SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); |
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 | SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
3460 | SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
3287 | SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
3461 | SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
3288 | |
3462 | |
3289 | /* |
3463 | /* |
3290 | ** CAPI3REF: Number Of SQL Parameters |
3464 | ** CAPI3REF: Number Of SQL Parameters |
… | |
… | |
3696 | ** <table border="1"> |
3870 | ** <table border="1"> |
3697 | ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion |
3871 | ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion |
3698 | ** |
3872 | ** |
3699 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 |
3873 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 |
3700 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 |
3874 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 |
3701 | ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer |
3875 | ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer |
3702 | ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer |
3876 | ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer |
3703 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float |
3877 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float |
3704 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
3878 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
3705 | ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT |
3879 | ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT |
3706 | ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer |
3880 | ** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER |
3707 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float |
3881 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float |
3708 | ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT |
3882 | ** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB |
3709 | ** <tr><td> TEXT <td> INTEGER <td> Use atoi() |
3883 | ** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER |
3710 | ** <tr><td> TEXT <td> FLOAT <td> Use atof() |
3884 | ** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL |
3711 | ** <tr><td> TEXT <td> BLOB <td> No change |
3885 | ** <tr><td> TEXT <td> BLOB <td> No change |
3712 | ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() |
3886 | ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER |
3713 | ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() |
3887 | ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL |
3714 | ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed |
3888 | ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed |
3715 | ** </table> |
3889 | ** </table> |
3716 | ** </blockquote>)^ |
3890 | ** </blockquote>)^ |
3717 | ** |
3891 | ** |
3718 | ** The table above makes reference to standard C library functions atoi() |
3892 | ** The table above makes reference to standard C library functions atoi() |
… | |
… | |
3764 | ** |
3938 | ** |
3765 | ** ^The pointers returned are valid until a type conversion occurs as |
3939 | ** ^The pointers returned are valid until a type conversion occurs as |
3766 | ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or |
3940 | ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or |
3767 | ** [sqlite3_finalize()] is called. ^The memory space used to hold strings |
3941 | ** [sqlite3_finalize()] is called. ^The memory space used to hold strings |
3768 | ** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned |
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 | ** [sqlite3_free()]. |
3944 | ** [sqlite3_free()]. |
3771 | ** |
3945 | ** |
3772 | ** ^(If a memory allocation error occurs during the evaluation of any |
3946 | ** ^(If a memory allocation error occurs during the evaluation of any |
3773 | ** of these routines, a default value is returned. The default value |
3947 | ** of these routines, a default value is returned. The default value |
3774 | ** is either the integer 0, the floating point number 0.0, or a NULL |
3948 | ** is either the integer 0, the floating point number 0.0, or a NULL |
… | |
… | |
3873 | ** parameter is less than -1 or greater than 127 then the behavior is |
4047 | ** parameter is less than -1 or greater than 127 then the behavior is |
3874 | ** undefined. |
4048 | ** undefined. |
3875 | ** |
4049 | ** |
3876 | ** ^The fourth parameter, eTextRep, specifies what |
4050 | ** ^The fourth parameter, eTextRep, specifies what |
3877 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
4051 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
3878 | ** its parameters. Every SQL function implementation must be able to work |
4052 | ** its parameters. The application should set this parameter to |
3879 | ** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
4053 | ** [SQLITE_UTF16LE] if the function implementation invokes |
3880 | ** more efficient with one encoding than another. ^An application may |
4054 | ** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the |
3881 | ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple |
4055 | ** implementation invokes [sqlite3_value_text16be()] on an input, or |
3882 | ** times with the same function but with different values of eTextRep. |
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 | ** ^When multiple implementations of the same function are available, SQLite |
4060 | ** ^When multiple implementations of the same function are available, SQLite |
3884 | ** will pick the one that involves the least amount of data conversion. |
4061 | ** will pick the one that involves the least amount of data conversion. |
3885 | ** If there is only a single implementation which does not care what text |
4062 | ** |
3886 | ** encoding is used, then the fourth argument should be [SQLITE_ANY]. |
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 | ** ^(The fifth parameter is an arbitrary pointer. The implementation of the |
4071 | ** ^(The fifth parameter is an arbitrary pointer. The implementation of the |
3889 | ** function can gain access to this pointer using [sqlite3_user_data()].)^ |
4072 | ** function can gain access to this pointer using [sqlite3_user_data()].)^ |
3890 | ** |
4073 | ** |
3891 | ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are |
4074 | ** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are |
… | |
… | |
3967 | */ |
4150 | */ |
3968 | #define SQLITE_UTF8 1 |
4151 | #define SQLITE_UTF8 1 |
3969 | #define SQLITE_UTF16LE 2 |
4152 | #define SQLITE_UTF16LE 2 |
3970 | #define SQLITE_UTF16BE 3 |
4153 | #define SQLITE_UTF16BE 3 |
3971 | #define SQLITE_UTF16 4 /* Use native byte order */ |
4154 | #define SQLITE_UTF16 4 /* Use native byte order */ |
3972 | #define SQLITE_ANY 5 /* sqlite3_create_function only */ |
4155 | #define SQLITE_ANY 5 /* Deprecated */ |
3973 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
4156 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
|
|
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 |
3974 | |
4167 | |
3975 | /* |
4168 | /* |
3976 | ** CAPI3REF: Deprecated Functions |
4169 | ** CAPI3REF: Deprecated Functions |
3977 | ** DEPRECATED |
4170 | ** DEPRECATED |
3978 | ** |
4171 | ** |
… | |
… | |
3986 | SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); |
4179 | SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); |
3987 | SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); |
4180 | SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); |
3988 | SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
4181 | SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
3989 | SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); |
4182 | SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); |
3990 | SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); |
4183 | SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); |
3991 | SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); |
4184 | SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int), |
|
|
4185 | void*,sqlite3_int64); |
3992 | #endif |
4186 | #endif |
3993 | |
4187 | |
3994 | /* |
4188 | /* |
3995 | ** CAPI3REF: Obtaining SQL Function Parameter Values |
4189 | ** CAPI3REF: Obtaining SQL Function Parameter Values |
3996 | ** |
4190 | ** |
… | |
… | |
4009 | ** These routines work only with [protected sqlite3_value] objects. |
4203 | ** These routines work only with [protected sqlite3_value] objects. |
4010 | ** Any attempt to use these routines on an [unprotected sqlite3_value] |
4204 | ** Any attempt to use these routines on an [unprotected sqlite3_value] |
4011 | ** object results in undefined behavior. |
4205 | ** object results in undefined behavior. |
4012 | ** |
4206 | ** |
4013 | ** ^These routines work just like the corresponding [column access functions] |
4207 | ** ^These routines work just like the corresponding [column access functions] |
4014 | ** except that these routines take a single [protected sqlite3_value] object |
4208 | ** except that these routines take a single [protected sqlite3_value] object |
4015 | ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. |
4209 | ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. |
4016 | ** |
4210 | ** |
4017 | ** ^The sqlite3_value_text16() interface extracts a UTF-16 string |
4211 | ** ^The sqlite3_value_text16() interface extracts a UTF-16 string |
4018 | ** in the native byte-order of the host machine. ^The |
4212 | ** in the native byte-order of the host machine. ^The |
4019 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces |
4213 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces |
… | |
… | |
4066 | ** an aggregate query, the xStep() callback of the aggregate function |
4260 | ** an aggregate query, the xStep() callback of the aggregate function |
4067 | ** implementation is never called and xFinal() is called exactly once. |
4261 | ** implementation is never called and xFinal() is called exactly once. |
4068 | ** In those cases, sqlite3_aggregate_context() might be called for the |
4262 | ** In those cases, sqlite3_aggregate_context() might be called for the |
4069 | ** first time from within xFinal().)^ |
4263 | ** first time from within xFinal().)^ |
4070 | ** |
4264 | ** |
4071 | ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is |
4265 | ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer |
4072 | ** less than or equal to zero or if a memory allocate error occurs. |
4266 | ** when first called if N is less than or equal to zero or if a memory |
|
|
4267 | ** allocate error occurs. |
4073 | ** |
4268 | ** |
4074 | ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is |
4269 | ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is |
4075 | ** determined by the N parameter on first successful call. Changing the |
4270 | ** determined by the N parameter on first successful call. Changing the |
4076 | ** value of N in subsequent call to sqlite3_aggregate_context() within |
4271 | ** value of N in subsequent call to sqlite3_aggregate_context() within |
4077 | ** the same aggregate function instance will not resize the memory |
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 | ** ^SQLite automatically frees the memory allocated by |
4277 | ** ^SQLite automatically frees the memory allocated by |
4081 | ** sqlite3_aggregate_context() when the aggregate query concludes. |
4278 | ** sqlite3_aggregate_context() when the aggregate query concludes. |
4082 | ** |
4279 | ** |
4083 | ** The first parameter must be a copy of the |
4280 | ** The first parameter must be a copy of the |
… | |
… | |
4116 | SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); |
4313 | SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); |
4117 | |
4314 | |
4118 | /* |
4315 | /* |
4119 | ** CAPI3REF: Function Auxiliary Data |
4316 | ** CAPI3REF: Function Auxiliary Data |
4120 | ** |
4317 | ** |
4121 | ** The following two functions may be used by scalar SQL functions to |
4318 | ** These functions may be used by (non-aggregate) SQL functions to |
4122 | ** associate metadata with argument values. If the same value is passed to |
4319 | ** associate metadata with argument values. If the same value is passed to |
4123 | ** multiple invocations of the same SQL function during query execution, under |
4320 | ** multiple invocations of the same SQL function during query execution, under |
4124 | ** some circumstances the associated metadata may be preserved. This may |
4321 | ** some circumstances the associated metadata may be preserved. An example |
4125 | ** be used, for example, to add a regular-expression matching scalar |
4322 | ** of where this might be useful is in a regular-expression matching |
4126 | ** function. The compiled version of the regular expression is stored as |
4323 | ** function. The compiled version of the regular expression can be stored as |
4127 | ** metadata associated with the SQL value passed as the regular expression |
4324 | ** metadata associated with the pattern string. |
|
|
4325 | ** Then as long as the pattern string remains the same, |
4128 | ** pattern. The compiled regular expression can be reused on multiple |
4326 | ** the compiled regular expression can be reused on multiple |
4129 | ** invocations of the same function so that the original pattern string |
4327 | ** invocations of the same function. |
4130 | ** does not need to be recompiled on each invocation. |
|
|
4131 | ** |
4328 | ** |
4132 | ** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata |
4329 | ** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata |
4133 | ** associated by the sqlite3_set_auxdata() function with the Nth argument |
4330 | ** associated by the sqlite3_set_auxdata() function with the Nth argument |
4134 | ** value to the application-defined function. ^If no metadata has been ever |
4331 | ** value to the application-defined function. ^If there is no metadata |
4135 | ** been set for the Nth argument of the function, or if the corresponding |
4332 | ** associated with the function argument, this sqlite3_get_auxdata() interface |
4136 | ** function parameter has changed since the meta-data was set, |
4333 | ** returns a NULL pointer. |
4137 | ** then sqlite3_get_auxdata() returns a NULL pointer. |
|
|
4138 | ** |
4334 | ** |
4139 | ** ^The sqlite3_set_auxdata() interface saves the metadata |
4335 | ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th |
4140 | ** pointed to by its 3rd parameter as the metadata for the N-th |
|
|
4141 | ** argument of the application-defined function. Subsequent |
4336 | ** argument of the application-defined function. ^Subsequent |
4142 | ** calls to sqlite3_get_auxdata() might return this data, if it has |
4337 | ** calls to sqlite3_get_auxdata(C,N) return P from the most recent |
4143 | ** not been destroyed. |
4338 | ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or |
4144 | ** ^If it is not NULL, SQLite will invoke the destructor |
4339 | ** NULL if the metadata has been discarded. |
4145 | ** function given by the 4th parameter to sqlite3_set_auxdata() on |
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> |
4146 | ** the metadata when the corresponding function parameter changes |
4344 | ** <li> when the corresponding function parameter changes, or |
4147 | ** or when the SQL statement completes, whichever comes first. |
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>)^ |
4148 | ** |
4350 | ** |
4149 | ** SQLite is free to call the destructor and drop metadata on any |
4351 | ** Note the last bullet in particular. The destructor X in |
4150 | ** parameter of any function at any time. ^The only guarantee is that |
4352 | ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the |
4151 | ** the destructor will be called before the metadata is dropped. |
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 | ** ^(In practice, metadata is preserved between function calls for |
4358 | ** ^(In practice, metadata is preserved between function calls for |
4154 | ** expressions that are constant at compile time. This includes literal |
4359 | ** function parameters that are compile-time constants, including literal |
4155 | ** values and [parameters].)^ |
4360 | ** values and [parameters] and expressions composed from the same.)^ |
4156 | ** |
4361 | ** |
4157 | ** These routines must be called from the same thread in which |
4362 | ** These routines must be called from the same thread in which |
4158 | ** the SQL function is running. |
4363 | ** the SQL function is running. |
4159 | */ |
4364 | */ |
4160 | SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); |
4365 | SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); |
… | |
… | |
4171 | ** SQLITE_TRANSIENT value means that the content will likely change in |
4376 | ** SQLITE_TRANSIENT value means that the content will likely change in |
4172 | ** the near future and that SQLite should make its own private copy of |
4377 | ** the near future and that SQLite should make its own private copy of |
4173 | ** the content before returning. |
4378 | ** the content before returning. |
4174 | ** |
4379 | ** |
4175 | ** The typedef is necessary to work around problems in certain |
4380 | ** The typedef is necessary to work around problems in certain |
4176 | ** C++ compilers. See ticket #2191. |
4381 | ** C++ compilers. |
4177 | */ |
4382 | */ |
4178 | typedef void (*sqlite3_destructor_type)(void*); |
4383 | typedef void (*sqlite3_destructor_type)(void*); |
4179 | #define SQLITE_STATIC ((sqlite3_destructor_type)0) |
4384 | #define SQLITE_STATIC ((sqlite3_destructor_type)0) |
4180 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
4385 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
4181 | |
4386 | |
… | |
… | |
4245 | ** ^The sqlite3_result_text(), sqlite3_result_text16(), |
4450 | ** ^The sqlite3_result_text(), sqlite3_result_text16(), |
4246 | ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces |
4451 | ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces |
4247 | ** set the return value of the application-defined function to be |
4452 | ** set the return value of the application-defined function to be |
4248 | ** a text string which is represented as UTF-8, UTF-16 native byte order, |
4453 | ** a text string which is represented as UTF-8, UTF-16 native byte order, |
4249 | ** UTF-16 little endian, or UTF-16 big endian, respectively. |
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 | ** ^SQLite takes the text result from the application from |
4459 | ** ^SQLite takes the text result from the application from |
4251 | ** the 2nd parameter of the sqlite3_result_text* interfaces. |
4460 | ** the 2nd parameter of the sqlite3_result_text* interfaces. |
4252 | ** ^If the 3rd parameter to the sqlite3_result_text* interfaces |
4461 | ** ^If the 3rd parameter to the sqlite3_result_text* interfaces |
4253 | ** is negative, then SQLite takes result text from the 2nd parameter |
4462 | ** is negative, then SQLite takes result text from the 2nd parameter |
4254 | ** through the first zero character. |
4463 | ** through the first zero character. |
… | |
… | |
4288 | ** If these routines are called from within the different thread |
4497 | ** If these routines are called from within the different thread |
4289 | ** than the one containing the application-defined function that received |
4498 | ** than the one containing the application-defined function that received |
4290 | ** the [sqlite3_context] pointer, the results are undefined. |
4499 | ** the [sqlite3_context] pointer, the results are undefined. |
4291 | */ |
4500 | */ |
4292 | SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); |
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 | SQLITE_API void sqlite3_result_double(sqlite3_context*, double); |
4503 | SQLITE_API void sqlite3_result_double(sqlite3_context*, double); |
4294 | SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); |
4504 | SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); |
4295 | SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); |
4505 | SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); |
4296 | SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); |
4506 | SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); |
4297 | SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); |
4507 | SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); |
4298 | SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); |
4508 | SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); |
4299 | SQLITE_API void sqlite3_result_int(sqlite3_context*, int); |
4509 | SQLITE_API void sqlite3_result_int(sqlite3_context*, int); |
4300 | SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
4510 | SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
4301 | SQLITE_API void sqlite3_result_null(sqlite3_context*); |
4511 | SQLITE_API void sqlite3_result_null(sqlite3_context*); |
4302 | SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); |
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 | SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
4515 | SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
4304 | SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
4516 | SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
4305 | SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
4517 | SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
4306 | SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
4518 | SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
4307 | SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); |
4519 | SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); |
… | |
… | |
4455 | */ |
4667 | */ |
4456 | SQLITE_API int sqlite3_key( |
4668 | SQLITE_API int sqlite3_key( |
4457 | sqlite3 *db, /* Database to be rekeyed */ |
4669 | sqlite3 *db, /* Database to be rekeyed */ |
4458 | const void *pKey, int nKey /* The key */ |
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 | ** Change the key on an open database. If the current database is not |
4679 | ** Change the key on an open database. If the current database is not |
4463 | ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
4680 | ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
4464 | ** database is decrypted. |
4681 | ** database is decrypted. |
… | |
… | |
4466 | ** The code to implement this API is not available in the public release |
4683 | ** The code to implement this API is not available in the public release |
4467 | ** of SQLite. |
4684 | ** of SQLite. |
4468 | */ |
4685 | */ |
4469 | SQLITE_API int sqlite3_rekey( |
4686 | SQLITE_API int sqlite3_rekey( |
4470 | sqlite3 *db, /* Database to be rekeyed */ |
4687 | sqlite3 *db, /* Database to be rekeyed */ |
|
|
4688 | const void *pKey, int nKey /* The new key */ |
|
|
4689 | ); |
|
|
4690 | SQLITE_API int sqlite3_rekey_v2( |
|
|
4691 | sqlite3 *db, /* Database to be rekeyed */ |
|
|
4692 | const char *zDbName, /* Name of the database */ |
4471 | const void *pKey, int nKey /* The new key */ |
4693 | const void *pKey, int nKey /* The new key */ |
4472 | ); |
4694 | ); |
4473 | |
4695 | |
4474 | /* |
4696 | /* |
4475 | ** Specify the activation key for a SEE database. Unless |
4697 | ** Specify the activation key for a SEE database. Unless |
… | |
… | |
4516 | ** the name of a folder (a.k.a. directory), then all temporary files |
4738 | ** the name of a folder (a.k.a. directory), then all temporary files |
4517 | ** created by SQLite when using a built-in [sqlite3_vfs | VFS] |
4739 | ** created by SQLite when using a built-in [sqlite3_vfs | VFS] |
4518 | ** will be placed in that directory.)^ ^If this variable |
4740 | ** will be placed in that directory.)^ ^If this variable |
4519 | ** is a NULL pointer, then SQLite performs a search for an appropriate |
4741 | ** is a NULL pointer, then SQLite performs a search for an appropriate |
4520 | ** temporary file directory. |
4742 | ** temporary file directory. |
|
|
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. |
4521 | ** |
4750 | ** |
4522 | ** It is not safe to read or modify this variable in more than one |
4751 | ** It is not safe to read or modify this variable in more than one |
4523 | ** thread at a time. It is not safe to read or modify this variable |
4752 | ** thread at a time. It is not safe to read or modify this variable |
4524 | ** if a [database connection] is being used at the same time in a separate |
4753 | ** if a [database connection] is being used at the same time in a separate |
4525 | ** thread. |
4754 | ** thread. |
… | |
… | |
4535 | ** [sqlite3_malloc] and the pragma may attempt to free that memory |
4764 | ** [sqlite3_malloc] and the pragma may attempt to free that memory |
4536 | ** using [sqlite3_free]. |
4765 | ** using [sqlite3_free]. |
4537 | ** Hence, if this variable is modified directly, either it should be |
4766 | ** Hence, if this variable is modified directly, either it should be |
4538 | ** made NULL or made to point to memory obtained from [sqlite3_malloc] |
4767 | ** made NULL or made to point to memory obtained from [sqlite3_malloc] |
4539 | ** or else the use of the [temp_store_directory pragma] should be avoided. |
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 | ** <b>Note to Windows Runtime users:</b> The temporary directory must be set |
4775 | ** <b>Note to Windows Runtime users:</b> The temporary directory must be set |
4542 | ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various |
4776 | ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various |
4543 | ** features that require the use of temporary files may fail. Here is an |
4777 | ** features that require the use of temporary files may fail. Here is an |
4544 | ** example of how to do this using C++ with the Windows Runtime: |
4778 | ** example of how to do this using C++ with the Windows Runtime: |
… | |
… | |
4719 | /* |
4953 | /* |
4720 | ** CAPI3REF: Data Change Notification Callbacks |
4954 | ** CAPI3REF: Data Change Notification Callbacks |
4721 | ** |
4955 | ** |
4722 | ** ^The sqlite3_update_hook() interface registers a callback function |
4956 | ** ^The sqlite3_update_hook() interface registers a callback function |
4723 | ** with the [database connection] identified by the first argument |
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 | ** ^Any callback set by a previous call to this function |
4960 | ** ^Any callback set by a previous call to this function |
4726 | ** for the same database connection is overridden. |
4961 | ** for the same database connection is overridden. |
4727 | ** |
4962 | ** |
4728 | ** ^The second argument is a pointer to the function to invoke when a |
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 | ** ^The first argument to the callback is a copy of the third argument |
4965 | ** ^The first argument to the callback is a copy of the third argument |
4731 | ** to sqlite3_update_hook(). |
4966 | ** to sqlite3_update_hook(). |
4732 | ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], |
4967 | ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], |
4733 | ** or [SQLITE_UPDATE], depending on the operation that caused the callback |
4968 | ** or [SQLITE_UPDATE], depending on the operation that caused the callback |
4734 | ** to be invoked. |
4969 | ** to be invoked. |
… | |
… | |
4737 | ** ^The final callback parameter is the [rowid] of the row. |
4972 | ** ^The final callback parameter is the [rowid] of the row. |
4738 | ** ^In the case of an update, this is the [rowid] after the update takes place. |
4973 | ** ^In the case of an update, this is the [rowid] after the update takes place. |
4739 | ** |
4974 | ** |
4740 | ** ^(The update hook is not invoked when internal system tables are |
4975 | ** ^(The update hook is not invoked when internal system tables are |
4741 | ** modified (i.e. sqlite_master and sqlite_sequence).)^ |
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 | ** ^In the current implementation, the update hook |
4979 | ** ^In the current implementation, the update hook |
4744 | ** is not invoked when duplication rows are deleted because of an |
4980 | ** is not invoked when duplication rows are deleted because of an |
4745 | ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook |
4981 | ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook |
4746 | ** invoked when rows are deleted using the [truncate optimization]. |
4982 | ** invoked when rows are deleted using the [truncate optimization]. |
… | |
… | |
4818 | /* |
5054 | /* |
4819 | ** CAPI3REF: Free Memory Used By A Database Connection |
5055 | ** CAPI3REF: Free Memory Used By A Database Connection |
4820 | ** |
5056 | ** |
4821 | ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap |
5057 | ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap |
4822 | ** memory as possible from database connection D. Unlike the |
5058 | ** memory as possible from database connection D. Unlike the |
4823 | ** [sqlite3_release_memory()] interface, this interface is effect even |
5059 | ** [sqlite3_release_memory()] interface, this interface is in effect even |
4824 | ** when then [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is |
5060 | ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is |
4825 | ** omitted. |
5061 | ** omitted. |
4826 | ** |
5062 | ** |
4827 | ** See also: [sqlite3_release_memory()] |
5063 | ** See also: [sqlite3_release_memory()] |
4828 | */ |
5064 | */ |
4829 | SQLITE_API int sqlite3_db_release_memory(sqlite3*); |
5065 | SQLITE_API int sqlite3_db_release_memory(sqlite3*); |
… | |
… | |
4970 | ** CAPI3REF: Load An Extension |
5206 | ** CAPI3REF: Load An Extension |
4971 | ** |
5207 | ** |
4972 | ** ^This interface loads an SQLite extension library from the named file. |
5208 | ** ^This interface loads an SQLite extension library from the named file. |
4973 | ** |
5209 | ** |
4974 | ** ^The sqlite3_load_extension() interface attempts to load an |
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 | ** ^The entry point is zProc. |
5218 | ** ^The entry point is zProc. |
4978 | ** ^zProc may be 0, in which case the name of the entry point |
5219 | ** ^(zProc may be 0, in which case SQLite will try to come up with an |
4979 | ** defaults to "sqlite3_extension_init". |
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 | ** ^The sqlite3_load_extension() interface returns |
5225 | ** ^The sqlite3_load_extension() interface returns |
4981 | ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
5226 | ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
4982 | ** ^If an error occurs and pzErrMsg is not 0, then the |
5227 | ** ^If an error occurs and pzErrMsg is not 0, then the |
4983 | ** [sqlite3_load_extension()] interface shall attempt to |
5228 | ** [sqlite3_load_extension()] interface shall attempt to |
4984 | ** fill *pzErrMsg with error message text stored in memory |
5229 | ** fill *pzErrMsg with error message text stored in memory |
… | |
… | |
5000 | |
5245 | |
5001 | /* |
5246 | /* |
5002 | ** CAPI3REF: Enable Or Disable Extension Loading |
5247 | ** CAPI3REF: Enable Or Disable Extension Loading |
5003 | ** |
5248 | ** |
5004 | ** ^So as not to open security holes in older applications that are |
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 |
5250 | ** unprepared to deal with [extension loading], and as a means of disabling |
5006 | ** extension loading while evaluating user-entered SQL, the following API |
5251 | ** [extension loading] while evaluating user-entered SQL, the following API |
5007 | ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. |
5252 | ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. |
5008 | ** |
5253 | ** |
5009 | ** ^Extension loading is off by default. See ticket #1863. |
5254 | ** ^Extension loading is off by default. |
5010 | ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 |
5255 | ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 |
5011 | ** to turn extension loading on and call it with onoff==0 to turn |
5256 | ** to turn extension loading on and call it with onoff==0 to turn |
5012 | ** it back off again. |
5257 | ** it back off again. |
5013 | */ |
5258 | */ |
5014 | SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
5259 | SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
… | |
… | |
5016 | /* |
5261 | /* |
5017 | ** CAPI3REF: Automatically Load Statically Linked Extensions |
5262 | ** CAPI3REF: Automatically Load Statically Linked Extensions |
5018 | ** |
5263 | ** |
5019 | ** ^This interface causes the xEntryPoint() function to be invoked for |
5264 | ** ^This interface causes the xEntryPoint() function to be invoked for |
5020 | ** each new [database connection] that is created. The idea here is that |
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 | ** that is to be automatically loaded into all new database connections. |
5267 | ** that is to be automatically loaded into all new database connections. |
5023 | ** |
5268 | ** |
5024 | ** ^(Even though the function prototype shows that xEntryPoint() takes |
5269 | ** ^(Even though the function prototype shows that xEntryPoint() takes |
5025 | ** no arguments and returns void, SQLite invokes xEntryPoint() with three |
5270 | ** no arguments and returns void, SQLite invokes xEntryPoint() with three |
5026 | ** arguments and expects and integer result as if the signature of the |
5271 | ** arguments and expects and integer result as if the signature of the |
… | |
… | |
5044 | ** |
5289 | ** |
5045 | ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already |
5290 | ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already |
5046 | ** on the list of automatic extensions is a harmless no-op. ^No entry point |
5291 | ** on the list of automatic extensions is a harmless no-op. ^No entry point |
5047 | ** will be called more than once for each database connection that is opened. |
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 | SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void)); |
5297 | SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void)); |
|
|
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)); |
5052 | |
5310 | |
5053 | /* |
5311 | /* |
5054 | ** CAPI3REF: Reset Automatic Extension Loading |
5312 | ** CAPI3REF: Reset Automatic Extension Loading |
5055 | ** |
5313 | ** |
5056 | ** ^This interface disables all automatic extensions previously |
5314 | ** ^This interface disables all automatic extensions previously |
… | |
… | |
5172 | ** |
5430 | ** |
5173 | ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in |
5431 | ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in |
5174 | ** the correct order to satisfy the ORDER BY clause so that no separate |
5432 | ** the correct order to satisfy the ORDER BY clause so that no separate |
5175 | ** sorting step is required. |
5433 | ** sorting step is required. |
5176 | ** |
5434 | ** |
5177 | ** ^The estimatedCost value is an estimate of the cost of doing the |
5435 | ** ^The estimatedCost value is an estimate of the cost of a particular |
5178 | ** particular lookup. A full scan of a table with N entries should have |
5436 | ** strategy. A cost of N indicates that the cost of the strategy is similar |
5179 | ** a cost of N. A binary search of a table of N entries should have a |
5437 | ** to a linear scan of an SQLite table with N rows. A cost of log(N) |
5180 | ** cost of approximately 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 | struct sqlite3_index_info { |
5452 | struct sqlite3_index_info { |
5183 | /* Inputs */ |
5453 | /* Inputs */ |
5184 | int nConstraint; /* Number of entries in aConstraint */ |
5454 | int nConstraint; /* Number of entries in aConstraint */ |
5185 | struct sqlite3_index_constraint { |
5455 | struct sqlite3_index_constraint { |
… | |
… | |
5200 | } *aConstraintUsage; |
5470 | } *aConstraintUsage; |
5201 | int idxNum; /* Number used to identify the index */ |
5471 | int idxNum; /* Number used to identify the index */ |
5202 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ |
5472 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ |
5203 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ |
5473 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ |
5204 | int orderByConsumed; /* True if output is already ordered */ |
5474 | int orderByConsumed; /* True if output is already ordered */ |
5205 | double estimatedCost; /* Estimated cost of using this index */ |
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 | /* |
5209 | ** CAPI3REF: Virtual Table Constraint Operator Codes |
5481 | ** CAPI3REF: Virtual Table Constraint Operator Codes |
5210 | ** |
5482 | ** |
… | |
… | |
5404 | ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of |
5676 | ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of |
5405 | ** the opened blob. ^The size of a blob may not be changed by this |
5677 | ** the opened blob. ^The size of a blob may not be changed by this |
5406 | ** interface. Use the [UPDATE] SQL command to change the size of a |
5678 | ** interface. Use the [UPDATE] SQL command to change the size of a |
5407 | ** blob. |
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 | ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces |
5684 | ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces |
5410 | ** and the built-in [zeroblob] SQL function can be used, if desired, |
5685 | ** and the built-in [zeroblob] SQL function can be used, if desired, |
5411 | ** to create an empty, zero-filled blob in which to read or write using |
5686 | ** to create an empty, zero-filled blob in which to read or write using |
5412 | ** this interface. |
5687 | ** this interface. |
5413 | ** |
5688 | ** |
… | |
… | |
5628 | ** <ul> |
5903 | ** <ul> |
5629 | ** <li> SQLITE_MUTEX_FAST |
5904 | ** <li> SQLITE_MUTEX_FAST |
5630 | ** <li> SQLITE_MUTEX_RECURSIVE |
5905 | ** <li> SQLITE_MUTEX_RECURSIVE |
5631 | ** <li> SQLITE_MUTEX_STATIC_MASTER |
5906 | ** <li> SQLITE_MUTEX_STATIC_MASTER |
5632 | ** <li> SQLITE_MUTEX_STATIC_MEM |
5907 | ** <li> SQLITE_MUTEX_STATIC_MEM |
5633 | ** <li> SQLITE_MUTEX_STATIC_MEM2 |
5908 | ** <li> SQLITE_MUTEX_STATIC_OPEN |
5634 | ** <li> SQLITE_MUTEX_STATIC_PRNG |
5909 | ** <li> SQLITE_MUTEX_STATIC_PRNG |
5635 | ** <li> SQLITE_MUTEX_STATIC_LRU |
5910 | ** <li> SQLITE_MUTEX_STATIC_LRU |
|
|
5911 | ** <li> SQLITE_MUTEX_STATIC_PMEM |
|
|
5912 | ** <li> SQLITE_MUTEX_STATIC_APP1 |
5636 | ** <li> SQLITE_MUTEX_STATIC_LRU2 |
5913 | ** <li> SQLITE_MUTEX_STATIC_APP2 |
5637 | ** </ul>)^ |
5914 | ** </ul>)^ |
5638 | ** |
5915 | ** |
5639 | ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) |
5916 | ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) |
5640 | ** cause sqlite3_mutex_alloc() to create |
5917 | ** cause sqlite3_mutex_alloc() to create |
5641 | ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE |
5918 | ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE |
… | |
… | |
5835 | #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ |
6112 | #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ |
5836 | #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ |
6113 | #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ |
5837 | #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
6114 | #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
5838 | #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ |
6115 | #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ |
5839 | #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ |
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 | ** CAPI3REF: Retrieve the mutex for a database connection |
6122 | ** CAPI3REF: Retrieve the mutex for a database connection |
5843 | ** |
6123 | ** |
5844 | ** ^This interface returns a pointer the [sqlite3_mutex] object that |
6124 | ** ^This interface returns a pointer the [sqlite3_mutex] object that |
… | |
… | |
5926 | #define SQLITE_TESTCTRL_RESERVE 14 |
6206 | #define SQLITE_TESTCTRL_RESERVE 14 |
5927 | #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
6207 | #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
5928 | #define SQLITE_TESTCTRL_ISKEYWORD 16 |
6208 | #define SQLITE_TESTCTRL_ISKEYWORD 16 |
5929 | #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 |
6209 | #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 |
5930 | #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
6210 | #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
5931 | #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 |
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 |
5932 | #define SQLITE_TESTCTRL_LAST 19 |
6217 | #define SQLITE_TESTCTRL_LAST 24 |
5933 | |
6218 | |
5934 | /* |
6219 | /* |
5935 | ** CAPI3REF: SQLite Runtime Status |
6220 | ** CAPI3REF: SQLite Runtime Status |
5936 | ** |
6221 | ** |
5937 | ** ^This interface is used to retrieve runtime status information |
6222 | ** ^This interface is used to retrieve runtime status information |
… | |
… | |
6118 | ** memory already being in use. |
6403 | ** memory already being in use. |
6119 | ** Only the high-water value is meaningful; |
6404 | ** Only the high-water value is meaningful; |
6120 | ** the current value is always zero.)^ |
6405 | ** the current value is always zero.)^ |
6121 | ** |
6406 | ** |
6122 | ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> |
6407 | ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> |
6123 | ** <dd>This parameter returns the approximate number of of bytes of heap |
6408 | ** <dd>This parameter returns the approximate number of bytes of heap |
6124 | ** memory used by all pager caches associated with the database connection.)^ |
6409 | ** memory used by all pager caches associated with the database connection.)^ |
6125 | ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. |
6410 | ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. |
6126 | ** |
6411 | ** |
6127 | ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> |
6412 | ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> |
6128 | ** <dd>This parameter returns the approximate number of of bytes of heap |
6413 | ** <dd>This parameter returns the approximate number of bytes of heap |
6129 | ** memory used to store the schema for all databases associated |
6414 | ** memory used to store the schema for all databases associated |
6130 | ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ |
6415 | ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ |
6131 | ** ^The full amount of memory used by the schemas is reported, even if the |
6416 | ** ^The full amount of memory used by the schemas is reported, even if the |
6132 | ** schema memory is shared with other database connections due to |
6417 | ** schema memory is shared with other database connections due to |
6133 | ** [shared cache mode] being enabled. |
6418 | ** [shared cache mode] being enabled. |
6134 | ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. |
6419 | ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. |
6135 | ** |
6420 | ** |
6136 | ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> |
6421 | ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> |
6137 | ** <dd>This parameter returns the approximate number of of bytes of heap |
6422 | ** <dd>This parameter returns the approximate number of bytes of heap |
6138 | ** and lookaside memory used by all prepared statements associated with |
6423 | ** and lookaside memory used by all prepared statements associated with |
6139 | ** the database connection.)^ |
6424 | ** the database connection.)^ |
6140 | ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. |
6425 | ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. |
6141 | ** </dd> |
6426 | ** </dd> |
6142 | ** |
6427 | ** |
… | |
… | |
6160 | ** transaction rollback or database recovery operations are not included. |
6445 | ** transaction rollback or database recovery operations are not included. |
6161 | ** If an IO or other error occurs while writing a page to disk, the effect |
6446 | ** If an IO or other error occurs while writing a page to disk, the effect |
6162 | ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The |
6447 | ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The |
6163 | ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0. |
6448 | ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0. |
6164 | ** </dd> |
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 | ** </dl> |
6456 | ** </dl> |
6166 | */ |
6457 | */ |
6167 | #define SQLITE_DBSTATUS_LOOKASIDE_USED 0 |
6458 | #define SQLITE_DBSTATUS_LOOKASIDE_USED 0 |
6168 | #define SQLITE_DBSTATUS_CACHE_USED 1 |
6459 | #define SQLITE_DBSTATUS_CACHE_USED 1 |
6169 | #define SQLITE_DBSTATUS_SCHEMA_USED 2 |
6460 | #define SQLITE_DBSTATUS_SCHEMA_USED 2 |
… | |
… | |
6172 | #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 |
6463 | #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 |
6173 | #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 |
6464 | #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 |
6174 | #define SQLITE_DBSTATUS_CACHE_HIT 7 |
6465 | #define SQLITE_DBSTATUS_CACHE_HIT 7 |
6175 | #define SQLITE_DBSTATUS_CACHE_MISS 8 |
6466 | #define SQLITE_DBSTATUS_CACHE_MISS 8 |
6176 | #define SQLITE_DBSTATUS_CACHE_WRITE 9 |
6467 | #define SQLITE_DBSTATUS_CACHE_WRITE 9 |
|
|
6468 | #define SQLITE_DBSTATUS_DEFERRED_FKS 10 |
6177 | #define SQLITE_DBSTATUS_MAX 9 /* Largest defined DBSTATUS */ |
6469 | #define SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */ |
6178 | |
6470 | |
6179 | |
6471 | |
6180 | /* |
6472 | /* |
6181 | ** CAPI3REF: Prepared Statement Status |
6473 | ** CAPI3REF: Prepared Statement Status |
6182 | ** |
6474 | ** |
… | |
… | |
6226 | ** <dd>^This is the number of rows inserted into transient indices that |
6518 | ** <dd>^This is the number of rows inserted into transient indices that |
6227 | ** were created automatically in order to help joins run faster. |
6519 | ** were created automatically in order to help joins run faster. |
6228 | ** A non-zero value in this counter may indicate an opportunity to |
6520 | ** A non-zero value in this counter may indicate an opportunity to |
6229 | ** improvement performance by adding permanent indices that do not |
6521 | ** improvement performance by adding permanent indices that do not |
6230 | ** need to be reinitialized each time the statement is run.</dd> |
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 | ** </dl> |
6532 | ** </dl> |
6232 | */ |
6533 | */ |
6233 | #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 |
6534 | #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 |
6234 | #define SQLITE_STMTSTATUS_SORT 2 |
6535 | #define SQLITE_STMTSTATUS_SORT 2 |
6235 | #define SQLITE_STMTSTATUS_AUTOINDEX 3 |
6536 | #define SQLITE_STMTSTATUS_AUTOINDEX 3 |
|
|
6537 | #define SQLITE_STMTSTATUS_VM_STEP 4 |
6236 | |
6538 | |
6237 | /* |
6539 | /* |
6238 | ** CAPI3REF: Custom Page Cache Object |
6540 | ** CAPI3REF: Custom Page Cache Object |
6239 | ** |
6541 | ** |
6240 | ** The sqlite3_pcache type is opaque. It is implemented by |
6542 | ** The sqlite3_pcache type is opaque. It is implemented by |
… | |
… | |
6367 | ** intact. If the requested page is not already in the cache, then the |
6669 | ** intact. If the requested page is not already in the cache, then the |
6368 | ** cache implementation should use the value of the createFlag |
6670 | ** cache implementation should use the value of the createFlag |
6369 | ** parameter to help it determined what action to take: |
6671 | ** parameter to help it determined what action to take: |
6370 | ** |
6672 | ** |
6371 | ** <table border=1 width=85% align=center> |
6673 | ** <table border=1 width=85% align=center> |
6372 | ** <tr><th> createFlag <th> Behaviour when page is not already in cache |
6674 | ** <tr><th> createFlag <th> Behavior when page is not already in cache |
6373 | ** <tr><td> 0 <td> Do not allocate a new page. Return NULL. |
6675 | ** <tr><td> 0 <td> Do not allocate a new page. Return NULL. |
6374 | ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. |
6676 | ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. |
6375 | ** Otherwise return NULL. |
6677 | ** Otherwise return NULL. |
6376 | ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return |
6678 | ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return |
6377 | ** NULL if allocating a new page is effectively impossible. |
6679 | ** NULL if allocating a new page is effectively impossible. |
… | |
… | |
6797 | */ |
7099 | */ |
6798 | SQLITE_API int sqlite3_stricmp(const char *, const char *); |
7100 | SQLITE_API int sqlite3_stricmp(const char *, const char *); |
6799 | SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); |
7101 | SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); |
6800 | |
7102 | |
6801 | /* |
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 | |
|
|
7118 | /* |
6802 | ** CAPI3REF: Error Logging Interface |
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 | ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. |
7122 | ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. |
6806 | ** ^If logging is enabled, the zFormat string and subsequent arguments are |
7123 | ** ^If logging is enabled, the zFormat string and subsequent arguments are |
6807 | ** used with [sqlite3_snprintf()] to generate the final output string. |
7124 | ** used with [sqlite3_snprintf()] to generate the final output string. |
6808 | ** |
7125 | ** |
6809 | ** The sqlite3_log() interface is intended for use by extensions such as |
7126 | ** The sqlite3_log() interface is intended for use by extensions such as |
… | |
… | |
6879 | ** configured by this function. |
7196 | ** configured by this function. |
6880 | ** |
7197 | ** |
6881 | ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface |
7198 | ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface |
6882 | ** from SQL. |
7199 | ** from SQL. |
6883 | ** |
7200 | ** |
|
|
7201 | ** ^Checkpoints initiated by this mechanism are |
|
|
7202 | ** [sqlite3_wal_checkpoint_v2|PASSIVE]. |
|
|
7203 | ** |
6884 | ** ^Every new [database connection] defaults to having the auto-checkpoint |
7204 | ** ^Every new [database connection] defaults to having the auto-checkpoint |
6885 | ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] |
7205 | ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] |
6886 | ** pages. The use of this interface |
7206 | ** pages. The use of this interface |
6887 | ** is only necessary if the default setting is found to be suboptimal |
7207 | ** is only necessary if the default setting is found to be suboptimal |
6888 | ** for a particular application. |
7208 | ** for a particular application. |
… | |
… | |
6895 | ** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X |
7215 | ** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X |
6896 | ** on [database connection] D to be [checkpointed]. ^If X is NULL or an |
7216 | ** on [database connection] D to be [checkpointed]. ^If X is NULL or an |
6897 | ** empty string, then a checkpoint is run on all databases of |
7217 | ** empty string, then a checkpoint is run on all databases of |
6898 | ** connection D. ^If the database connection D is not in |
7218 | ** connection D. ^If the database connection D is not in |
6899 | ** [WAL | write-ahead log mode] then this interface is a harmless no-op. |
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 | ** ^The [wal_checkpoint pragma] can be used to invoke this interface |
7225 | ** ^The [wal_checkpoint pragma] can be used to invoke this interface |
6902 | ** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the |
7226 | ** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the |
6903 | ** [wal_autocheckpoint pragma] can be used to cause this interface to be |
7227 | ** [wal_autocheckpoint pragma] can be used to cause this interface to be |
6904 | ** run whenever the WAL reaches a certain size threshold. |
7228 | ** run whenever the WAL reaches a certain size threshold. |
… | |
… | |
6917 | ** <dl> |
7241 | ** <dl> |
6918 | ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd> |
7242 | ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd> |
6919 | ** Checkpoint as many frames as possible without waiting for any database |
7243 | ** Checkpoint as many frames as possible without waiting for any database |
6920 | ** readers or writers to finish. Sync the db file if all frames in the log |
7244 | ** readers or writers to finish. Sync the db file if all frames in the log |
6921 | ** are checkpointed. This mode is the same as calling |
7245 | ** are checkpointed. This mode is the same as calling |
6922 | ** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked. |
7246 | ** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback] |
|
|
7247 | ** is never invoked. |
6923 | ** |
7248 | ** |
6924 | ** <dt>SQLITE_CHECKPOINT_FULL<dd> |
7249 | ** <dt>SQLITE_CHECKPOINT_FULL<dd> |
6925 | ** This mode blocks (calls the busy-handler callback) until there is no |
7250 | ** This mode blocks (it invokes the |
|
|
7251 | ** [sqlite3_busy_handler|busy-handler callback]) until there is no |
6926 | ** database writer and all readers are reading from the most recent database |
7252 | ** database writer and all readers are reading from the most recent database |
6927 | ** snapshot. It then checkpoints all frames in the log file and syncs the |
7253 | ** snapshot. It then checkpoints all frames in the log file and syncs the |
6928 | ** database file. This call blocks database writers while it is running, |
7254 | ** database file. This call blocks database writers while it is running, |
6929 | ** but not database readers. |
7255 | ** but not database readers. |
6930 | ** |
7256 | ** |
6931 | ** <dt>SQLITE_CHECKPOINT_RESTART<dd> |
7257 | ** <dt>SQLITE_CHECKPOINT_RESTART<dd> |
6932 | ** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after |
7258 | ** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after |
6933 | ** checkpointing the log file it blocks (calls the busy-handler callback) |
7259 | ** checkpointing the log file it blocks (calls the |
|
|
7260 | ** [sqlite3_busy_handler|busy-handler callback]) |
6934 | ** until all readers are reading from the database file only. This ensures |
7261 | ** until all readers are reading from the database file only. This ensures |
6935 | ** that the next client to write to the database file restarts the log file |
7262 | ** that the next client to write to the database file restarts the log file |
6936 | ** from the beginning. This call blocks database writers while it is running, |
7263 | ** from the beginning. This call blocks database writers while it is running, |
6937 | ** but not database readers. |
7264 | ** but not database readers. |
6938 | ** </dl> |
7265 | ** </dl> |
… | |
… | |
7066 | */ |
7393 | */ |
7067 | SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
7394 | SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
7068 | |
7395 | |
7069 | /* |
7396 | /* |
7070 | ** CAPI3REF: Conflict resolution modes |
7397 | ** CAPI3REF: Conflict resolution modes |
|
|
7398 | ** KEYWORDS: {conflict resolution mode} |
7071 | ** |
7399 | ** |
7072 | ** These constants are returned by [sqlite3_vtab_on_conflict()] to |
7400 | ** These constants are returned by [sqlite3_vtab_on_conflict()] to |
7073 | ** inform a [virtual table] implementation what the [ON CONFLICT] mode |
7401 | ** inform a [virtual table] implementation what the [ON CONFLICT] mode |
7074 | ** is for the SQL statement being evaluated. |
7402 | ** is for the SQL statement being evaluated. |
7075 | ** |
7403 | ** |
… | |
… | |
7094 | #endif |
7422 | #endif |
7095 | |
7423 | |
7096 | #ifdef __cplusplus |
7424 | #ifdef __cplusplus |
7097 | } /* End of the 'extern "C"' block */ |
7425 | } /* End of the 'extern "C"' block */ |
7098 | #endif |
7426 | #endif |
7099 | #endif |
7427 | #endif /* _SQLITE3_H_ */ |
7100 | |
7428 | |
7101 | /* |
7429 | /* |
7102 | ** 2010 August 30 |
7430 | ** 2010 August 30 |
7103 | ** |
7431 | ** |
7104 | ** The author disclaims copyright to this source code. In place of |
7432 | ** The author disclaims copyright to this source code. In place of |
… | |
… | |
7118 | #ifdef __cplusplus |
7446 | #ifdef __cplusplus |
7119 | extern "C" { |
7447 | extern "C" { |
7120 | #endif |
7448 | #endif |
7121 | |
7449 | |
7122 | typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry; |
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 | ** Register a geometry callback named zGeom that can be used as part of an |
7463 | ** Register a geometry callback named zGeom that can be used as part of an |
7126 | ** R-Tree geometry query as follows: |
7464 | ** R-Tree geometry query as follows: |
7127 | ** |
7465 | ** |
7128 | ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) |
7466 | ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) |
7129 | */ |
7467 | */ |
7130 | SQLITE_API int sqlite3_rtree_geometry_callback( |
7468 | SQLITE_API int sqlite3_rtree_geometry_callback( |
7131 | sqlite3 *db, |
7469 | sqlite3 *db, |
7132 | const char *zGeom, |
7470 | const char *zGeom, |
7133 | #ifdef SQLITE_RTREE_INT_ONLY |
|
|
7134 | int (*xGeom)(sqlite3_rtree_geometry*, int n, sqlite3_int64 *a, int *pRes), |
7471 | int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), |
7135 | #else |
|
|
7136 | int (*xGeom)(sqlite3_rtree_geometry*, int n, double *a, int *pRes), |
|
|
7137 | #endif |
|
|
7138 | void *pContext |
7472 | void *pContext |
7139 | ); |
7473 | ); |
7140 | |
7474 | |
7141 | |
7475 | |
7142 | /* |
7476 | /* |
… | |
… | |
7144 | ** argument to callbacks registered using rtree_geometry_callback(). |
7478 | ** argument to callbacks registered using rtree_geometry_callback(). |
7145 | */ |
7479 | */ |
7146 | struct sqlite3_rtree_geometry { |
7480 | struct sqlite3_rtree_geometry { |
7147 | void *pContext; /* Copy of pContext passed to s_r_g_c() */ |
7481 | void *pContext; /* Copy of pContext passed to s_r_g_c() */ |
7148 | int nParam; /* Size of array aParam[] */ |
7482 | int nParam; /* Size of array aParam[] */ |
7149 | double *aParam; /* Parameters passed to SQL geom function */ |
7483 | sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ |
7150 | void *pUser; /* Callback implementation user data */ |
7484 | void *pUser; /* Callback implementation user data */ |
7151 | void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ |
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 | #ifdef __cplusplus |
7538 | #ifdef __cplusplus |
7156 | } /* end of the 'extern "C"' block */ |
7539 | } /* end of the 'extern "C"' block */ |
7157 | #endif |
7540 | #endif |
7158 | |
7541 | |