0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 38 2e 20 20 42 ersion 3.7.8. B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20 y combining all
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43 the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65 this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65 large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 be compiled as
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61 a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54 tion.** unit. T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20 his allows many
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20 compilers to do
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68 optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74 ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20 y. Performance
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20 improvements.**
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72 of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20 e commonly seen
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69 gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54 on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20 his file is all
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70 you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20 ile SQLite. To
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74 use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66 you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66 ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73 ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f ary. (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68 not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 . Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 eeded.** if you
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 ng.** language.
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 s file contains
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 ef SQLITE_API.#
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 ile sqliteInt.h
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35 001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65 ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65 ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61 fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75 ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69 pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74 stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63 . If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65 ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20 support, or if
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77 the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20 s, these should
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20 Ticket #2739:
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74 OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61 appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20 cludes. Hence,
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76 de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64 ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20 e in all source
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 ge file support
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20 can be disabled
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49 using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73 TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20 witch.** on the
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64 compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20 line. This is
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75 necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61 * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48 chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20 at 7.2) but you
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74 want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 o work.** on an
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65 older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20 ** without this
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65 option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20 nable. But LFS
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20 n the kernel.**
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20 in Red Hat 6.0,
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27 so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20 t work. Hence,
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61 for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74 ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69 y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d t LFS..**.** Sim
0b00: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72 ilar is true for
0b10: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 Mac OS X. LFS
0b20: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 is only supporte
0b30: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 d on Mac OS X 9
0b40: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 and later..*/.#i
0b50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53 fndef SQLITE_DIS
0b60: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e ABLE_LFS.# defin
0b70: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 e _LARGE_FILE
0b80: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 1.# ifndef _
0b90: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 FILE_OFFSET_BITS
0ba0: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c .# define _FIL
0bb0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34 E_OFFSET_BITS 64
0bc0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e .# endif.# defin
0bd0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 e _LARGEFILE_SOU
0be0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a RCE 1.#endif../*
0bf0: 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 20 .** Include the
0c00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 65 configuration he
0c10: 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 27 ader output by '
0c20: 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 65 configure' if we
0c30: 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 're using the.**
0c40: 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 20 autoconf-based
0c50: 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 20 build.*/.#ifdef
0c60: 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f 4e _HAVE_SQLITE_CON
0c70: 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 22 FIG_H.#include "
0c80: 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 66 config.h".#endif
0c90: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ../*************
0ca0: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 * Include sqlite
0cb0: 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 6d Limit.h in the m
0cc0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 iddle of sqliteI
0cd0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
0ce0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
0cf0: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c * Begin file sql
0d00: 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a iteLimit.h *****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d30: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 79 /./*.** 2007 May
0d40: 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 7.**.** The aut
0d50: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f hor disclaims co
0d60: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 pyright to this
0d70: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e source code. In
0d80: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c place of.** a l
0d90: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 egal notice, her
0da0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a e is a blessing:
0db0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f .**.** May yo
0dc0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f u do good and no
0dd0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 t evil..** Ma
0de0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 y you find forgi
0df0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 veness for yours
0e00: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 elf and forgive
0e10: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 others..** Ma
0e20: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 y you share free
0e30: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 ly, never taking
0e40: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 more than you g
0e50: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a ive..**.********
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ea0: 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 69 *.** .** This fi
0eb0: 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 6f le defines vario
0ec0: 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 61 us limits of wha
0ed0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 6f t SQLite can pro
0ee0: 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 cess..*/../*.**
0ef0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
0f00: 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 20 th of a TEXT or
0f10: 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 20 BLOB in bytes.
0f20: 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c 69 This also.** li
0f30: 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 mits the size of
0f40: 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c a row in a tabl
0f50: 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a 2a e or index..**.*
0f60: 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 74 * The hard limit
0f70: 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 20 is the ability
0f80: 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e of a 32-bit sign
0f90: 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 6f ed integer.** to
0fa0: 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 3a count the size:
0fb0: 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 34 2^31-1 or 21474
0fc0: 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 65 83647..*/.#ifnde
0fd0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e f SQLITE_MAX_LEN
0fe0: 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c GTH.# define SQL
0ff0: 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 31 ITE_MAX_LENGTH 1
1000: 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 66 000000000.#endif
1010: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 ../*.** This is
1020: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
1030: 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 2a er of.**.** *
1040: 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 Columns in a ta
1050: 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 ble.** * Colu
1060: 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
1070: 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 20 ** * Columns
1080: 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 20 in a view.**
1090: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 53 * Terms in the S
10a0: 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20 ET clause of an
10b0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
10c0: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 .** * Terms i
10d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
10e0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 of a SELECT sta
10f0: 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 tement.** * T
1100: 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f 55 erms in the GROU
1110: 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 59 P BY or ORDER BY
1120: 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 45 clauses of a SE
1130: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a LECT statement..
1140: 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 6e ** * Terms in
1150: 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75 the VALUES clau
1160: 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20 se of an INSERT
1170: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 statement.**.**
1180: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c The hard upper l
1190: 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 36 imit here is 326
11a0: 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 61 76. Most databa
11b0: 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a 2a se people will.*
11c0: 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 20 * tell you that
11d0: 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 6c in a well-normal
11e0: 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 79 ized database, y
11f0: 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 6c ou usually shoul
1200: 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d 6f d.** not have mo
1210: 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e 20 re than a dozen
1220: 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 6e or so columns in
1230: 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e 64 any table. And
1240: 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 if.** that is t
1250: 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 69 he case, there i
1260: 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 61 s no point in ha
1270: 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 61 ving more than a
1280: 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 61 few.** dozen va
1290: 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 74 lues in any of t
12a0: 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 69 he other situati
12b0: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62 ons described ab
12c0: 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ove..*/.#ifndef
12d0: 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d SQLITE_MAX_COLUM
12e0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 N.# define SQLIT
12f0: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 30 E_MAX_COLUMN 200
1300: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 0.#endif../*.**
1310: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
1320: 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 53 th of a single S
1330: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
1340: 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 bytes..**.** It
1350: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 63 used to be the c
1360: 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e 67 ase that setting
1370: 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 7a this value to z
1380: 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 72 ero would.** tur
1390: 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 2e n the limit off.
13a0: 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f 6e That is no lon
13b0: 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 73 ger true. It is
13c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a 2a not possible.**
13d0: 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c 69 to turn this li
13e0: 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 6e mit off..*/.#ifn
13f0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 def SQLITE_MAX_S
1400: 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 69 QL_LENGTH.# defi
1410: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 ne SQLITE_MAX_SQ
1420: 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 30 L_LENGTH 1000000
1430: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 000.#endif../*.*
1440: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 * The maximum de
1450: 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 73 pth of an expres
1460: 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 20 sion tree. This
1470: 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a 2a is limited to .*
1480: 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79 * some extent by
1490: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f SQLITE_MAX_SQL_
14a0: 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d 65 LENGTH. But some
14b0: 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 0a time you might .
14c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 65 ** want to place
14d0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 6d more severe lim
14e0: 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 6c its on the compl
14f0: 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a 20 exity of an .**
1500: 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a 2a expression..**.*
1510: 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 75 * A value of 0 u
1520: 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 74 sed to mean that
1530: 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 6e the limit was n
1540: 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a 20 ot enforced..**
1550: 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 6c But that is no l
1560: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 65 onger true. The
1570: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 74 limit is now st
1580: 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 0a rictly enforced.
1590: 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 2e ** at all times.
15a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
15b0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 TE_MAX_EXPR_DEPT
15c0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 H.# define SQLIT
15d0: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48 E_MAX_EXPR_DEPTH
15e0: 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 1000.#endif../*
15f0: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 .** The maximum
1600: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 number of terms
1610: 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 in a compound SE
1620: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a LECT statement..
1630: 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e 65 ** The code gene
1640: 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f 75 rator for compou
1650: 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d nd SELECT statem
1660: 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a 2a ents does one.**
1670: 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 73 level of recurs
1680: 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 72 ion for each ter
1690: 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 72 m. A stack over
16a0: 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 0a flow can result.
16b0: 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72 ** if the number
16c0: 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f 6f of terms is too
16d0: 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 63 large. In prac
16e0: 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a 2a tice, most SQL.*
16f0: 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 65 * never has more
1700: 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 72 than 3 or 4 ter
1710: 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 65 ms. Use a value
1720: 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c 65 of 0 to disable
1730: 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f 6e .** any limit on
1740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
1750: 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 erms in a compou
1760: 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 69 nt SELECT..*/.#i
1770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1780: 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
1790: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
17a0: 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 _MAX_COMPOUND_SE
17b0: 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 0a LECT 500.#endif.
17c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d ./*.** The maxim
17d0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 63 um number of opc
17e0: 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 70 odes in a VDBE p
17f0: 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 63 rogram..** Not c
1800: 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 65 urrently enforce
1810: 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 d..*/.#ifndef SQ
1820: 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 LITE_MAX_VDBE_OP
1830: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
1840: 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 30 _MAX_VDBE_OP 250
1850: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 00.#endif../*.**
1860: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d The maximum num
1870: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
1880: 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 to an SQL funct
1890: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ion..*/.#ifndef
18a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54 SQLITE_MAX_FUNCT
18b0: 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e 65 ION_ARG.# define
18c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 SQLITE_MAX_FUNC
18d0: 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 6e TION_ARG 127.#en
18e0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d dif../*.** The m
18f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1900: 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 73 in-memory pages
1910: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20 to use for the
1920: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a main database.**
1930: 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 74 table and for t
1940: 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 2e emporary tables.
1950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 The SQLITE_DEF
1960: 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a AULT_CACHE_SIZE.
1970: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
1980: 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f E_DEFAULT_CACHE_
1990: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 SIZE.# define SQ
19a0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 LITE_DEFAULT_CAC
19b0: 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 65 HE_SIZE 2000.#e
19c0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c ndif.#ifndef SQL
19d0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d 50 ITE_DEFAULT_TEMP
19e0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 65 _CACHE_SIZE.# de
19f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41 fine SQLITE_DEFA
1a00: 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f 53 ULT_TEMP_CACHE_S
1a10: 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 0a IZE 500.#endif.
1a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ./*.** The defau
1a30: 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 61 lt number of fra
1a40: 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 mes to accumulat
1a50: 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c e in the log fil
1a60: 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 63 e before.** chec
1a70: 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 61 kpointing the da
1a80: 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f tabase in WAL mo
1a90: 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 de..*/.#ifndef S
1aa0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 QLITE_DEFAULT_WA
1ab0: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 L_AUTOCHECKPOINT
1ac0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
1ad0: 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54 _DEFAULT_WAL_AUT
1ae0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 30 OCHECKPOINT 100
1af0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 0.#endif../*.**
1b00: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1b10: 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 er of attached d
1b20: 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 20 atabases. This
1b30: 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 must be between
1b40: 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 68 0.** and 62. Th
1b50: 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e e upper bound on
1b60: 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 61 62 is because a
1b70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1b80: 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 65 bitmap.** is use
1b90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
1ba0: 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 64 track attached d
1bb0: 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 66 atabases..*/.#if
1bc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f ndef SQLITE_MAX_
1bd0: 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 6e ATTACHED.# defin
1be0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54 e SQLITE_MAX_ATT
1bf0: 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 0a ACHED 10.#endif.
1c00: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 ../*.** The maxi
1c10: 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 3f mum value of a ?
1c20: 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 61 nnn wildcard tha
1c30: 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 6c t the parser wil
1c40: 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 66 l accept..*/.#if
1c50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f ndef SQLITE_MAX_
1c60: 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a VARIABLE_NUMBER.
1c70: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
1c80: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MAX_VARIABLE_NUM
1c90: 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a 0a BER 999.#endif..
1ca0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 20 /* Maximum page
1cb0: 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 72 size. The upper
1cc0: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 76 bound on this v
1cd0: 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 20 alue is 65536.
1ce0: 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a 20 This a limit.**
1cf0: 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 75 imposed by the u
1d00: 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 66 se of 16-bit off
1d10: 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 68 sets within each
1d20: 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 72 page..**.** Ear
1d30: 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 lier versions of
1d40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 20 SQLite allowed
1d50: 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 6e the user to chan
1d60: 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 74 ge this value at
1d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 .** compile time
1d80: 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f 6e . This is no lon
1d90: 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 6f ger permitted, o
1da0: 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 68 n the grounds th
1db0: 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a 2a at it creates.**
1dc0: 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 20 a library that
1dd0: 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69 is technically i
1de0: 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68 ncompatible with
1df0: 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 61 an SQLite libra
1e00: 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 ry .** compiled
1e10: 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74 with a different
1e20: 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 6f limit. If a pro
1e30: 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 6f cess operating o
1e40: 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a n a database .**
1e50: 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 7a with a page-siz
1e60: 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 73 e of 65536 bytes
1e70: 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 61 crashes, then a
1e80: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51 n instance of SQ
1e90: 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 Lite .** compile
1ea0: 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 d with the defau
1eb0: 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 6d lt page-size lim
1ec0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 it will not be a
1ed0: 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20 ble to rollback
1ee0: 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 20 .** the aborted
1ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
1f00: 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f 20 s could lead to
1f10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
1f20: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ion..*/.#ifdef S
1f30: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 QLITE_MAX_PAGE_S
1f40: 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 IZE.# undef SQLI
1f50: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 TE_MAX_PAGE_SIZE
1f60: 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
1f70: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
1f80: 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a 0a SIZE 65536.../*.
1f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73 ** The default s
1fa0: 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 ize of a databas
1fb0: 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e 64 e page..*/.#ifnd
1fc0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c ef SQLITE_DEFAUL
1fd0: 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 T_PAGE_SIZE.# de
1fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41 fine SQLITE_DEFA
1ff0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 30 ULT_PAGE_SIZE 10
2000: 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 24.#endif.#if SQ
2010: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 LITE_DEFAULT_PAG
2020: 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d 41 E_SIZE>SQLITE_MA
2030: 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 6e X_PAGE_SIZE.# un
2040: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 def SQLITE_DEFAU
2050: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 LT_PAGE_SIZE.# d
2060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 efine SQLITE_DEF
2070: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 AULT_PAGE_SIZE S
2080: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 QLITE_MAX_PAGE_S
2090: 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a IZE.#endif../*.*
20a0: 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 66 * Ordinarily, if
20b0: 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 70 no value is exp
20c0: 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64 licitly provided
20d0: 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73 , SQLite creates
20e0: 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 69 databases.** wi
20f0: 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 4c th page size SQL
2100: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 ITE_DEFAULT_PAGE
2110: 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c 20 _SIZE. However,
2120: 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 6e based on certain
2130: 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 61 .** device chara
2140: 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 74 cteristics (sect
2150: 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f 6d or-size and atom
2160: 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 6f ic write() suppo
2170: 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 6d rt),.** SQLite m
2180: 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 67 ay choose a larg
2190: 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 63 er value. This c
21a0: 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 6d onstant is the m
21b0: 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a 20 aximum value.**
21c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f 6f SQLite will choo
21d0: 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a 2a se on its own..*
21e0: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
21f0: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 _MAX_DEFAULT_PAG
2200: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 E_SIZE.# define
2210: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 SQLITE_MAX_DEFAU
2220: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 39 LT_PAGE_SIZE 819
2230: 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 2.#endif.#if SQL
2240: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f ITE_MAX_DEFAULT_
2250: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 PAGE_SIZE>SQLITE
2260: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 _MAX_PAGE_SIZE.#
2270: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 undef SQLITE_MA
2280: 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 X_DEFAULT_PAGE_S
2290: 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c IZE.# define SQL
22a0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f ITE_MAX_DEFAULT_
22b0: 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 45 PAGE_SIZE SQLITE
22c0: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 _MAX_PAGE_SIZE.#
22d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d 61 endif.../*.** Ma
22e0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
22f0: 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 74 pages in one dat
2300: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a abase file..**.*
2310: 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c 79 * This is really
2320: 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 6c just the defaul
2330: 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 t value for the
2340: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 70 max_page_count p
2350: 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 76 ragma..** This v
2360: 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 65 alue can be lowe
2370: 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 20 red (or raised)
2380: 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
2390: 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d 61 g that the.** ma
23a0: 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 63 x_page_count mac
23b0: 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 ro..*/.#ifndef S
23c0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 QLITE_MAX_PAGE_C
23d0: 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 OUNT.# define SQ
23e0: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f LITE_MAX_PAGE_CO
23f0: 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a 23 UNT 1073741823.#
2400: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 endif../*.** Max
2410: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e 20 imum length (in
2420: 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 61 bytes) of the pa
2430: 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 20 ttern in a LIKE
2440: 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 61 or GLOB.** opera
2450: 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 tor..*/.#ifndef
2460: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f SQLITE_MAX_LIKE_
2470: 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a 23 PATTERN_LENGTH.#
2480: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d define SQLITE_M
2490: 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f AX_LIKE_PATTERN_
24a0: 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 6e LENGTH 50000.#en
24b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 6d dif../*.** Maxim
24c0: 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
24d0: 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
24e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c 75 rs..**.** A valu
24f0: 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 61 e of 1 means tha
2500: 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 t a trigger prog
2510: 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 ram will not be
2520: 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a 2a able to itself.*
2530: 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 67 * fire any trigg
2540: 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 20 ers. A value of
2550: 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 0 means that no
2560: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 trigger programs
2570: 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 20 at all .** may
2580: 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f 0a be executed..*/.
2590: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d #ifndef SQLITE_M
25a0: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 AX_TRIGGER_DEPTH
25b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
25c0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 _MAX_TRIGGER_DEP
25d0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a TH 1000.#endif..
25e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
25f0: 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 6d End of sqliteLim
2600: 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a it.h ***********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
2630: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
2640: 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 Continuing where
2650: 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 we left off in
2660: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a sqliteInt.h ****
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
2680: 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 73 ./* Disable nuis
2690: 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e ance warnings on
26a0: 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c 65 Borland compile
26b0: 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 rs */.#if define
26c0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
26d0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 63 #pragma warn -rc
26e0: 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c 65 h /* unreachable
26f0: 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d 61 code */.#pragma
2700: 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 6f warn -ccc /* Co
2710: 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 79 ndition is alway
2720: 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 20 s true or false
2730: 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 */.#pragma warn
2740: 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 64 -aus /* Assigned
2750: 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 20 value is never
2760: 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 20 used */.#pragma
2770: 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f 6d warn -csu /* Com
2780: 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 6e paring signed an
2790: 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 70 d unsigned */.#p
27a0: 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 20 ragma warn -spa
27b0: 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 6f /* Suspicious po
27c0: 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 63 inter arithmetic
27d0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e */.#endif../* N
27e0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 eeded for variou
27f0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e s definitions...
2800: 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e 55 */.#ifndef _GNU
2810: 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e 65 _SOURCE.# define
2820: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e _GNU_SOURCE.#en
2830: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 dif../*.** Inclu
2840: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64 de standard head
2850: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65 er files as nece
2860: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20 ssary.*/.#ifdef
2870: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69 HAVE_STDINT_H.#i
2880: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68 nclude <stdint.h
2890: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 >.#endif.#ifdef
28a0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a HAVE_INTTYPES_H.
28b0: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70 #include <inttyp
28c0: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a es.h>.#endif../*
28d0: 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f .** The number o
28e0: 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61 6e 20 f samples of an
28f0: 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c 69 74 index that SQLit
2900: 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64 65 72 e takes in order
2910: 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72 75 63 to .** construc
2920: 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20 6f 66 t a histogram of
2930: 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 the table conte
2940: 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67 20 nt when running
2950: 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64 20 77 ANALYZE.** and w
2960: 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c ith SQLITE_ENABL
2970: 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65 66 69 E_STAT2.*/.#defi
2980: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
2990: 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a 0a 2a SAMPLES 10../*.*
29a0: 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
29b0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 macros are used
29c0: 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 72 73 to cast pointers
29d0: 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 6e 64 to integers and
29e0: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 6f 20 .** integers to
29f0: 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 20 77 pointers. The w
2a00: 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 20 76 ay you do this v
2a10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 63 aries from one c
2a20: 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 74 68 ompiler.** to th
2a30: 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 68 61 e next, so we ha
2a40: 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 68 65 ve developed the
2a50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 20 6f following set o
2a60: 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e 74 73 f #if statements
2a70: 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 65 20 .** to generate
2a80: 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 63 72 appropriate macr
2a90: 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 72 61 os for a wide ra
2aa0: 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 72 73 nge of compilers
2ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 72 72 ..**.** The corr
2ac0: 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 20 74 ect "ANSI" way t
2ad0: 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 6f 20 o do this is to
2ae0: 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 5f 74 use the intptr_t
2af0: 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 6f 72 type. .** Unfor
2b00: 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 20 74 tunately, that t
2b10: 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 61 76 ypedef is not av
2b20: 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c 20 63 ailable on all c
2b30: 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a 2a 20 ompilers, or.**
2b40: 69 66 20 69 74 20 69 73 20 61 76 61 69 6c 61 62 if it is availab
2b50: 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 73 20 le, it requires
2b60: 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 20 73 an #include of s
2b70: 70 65 63 69 66 69 63 20 68 65 61 64 65 72 73 0a pecific headers.
2b80: 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 72 6f ** that vary fro
2b90: 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 74 6f m one machine to
2ba0: 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a the next..**.**
2bb0: 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a 20 20 Ticket #3860:
2bc0: 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 2e 32 The llvm-gcc-4.2
2bd0: 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d 20 41 compiler from A
2be0: 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e 0a 2a pple chokes on.*
2bf0: 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 26 28 * the ((void*)&(
2c00: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 63 6f (char*)0)[X]) co
2c10: 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 4d 53 nstruct. But MS
2c20: 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 28 76 VC chokes on ((v
2c30: 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 53 6f oid*)(X))..** So
2c40: 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 66 69 we have to defi
2c50: 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e ne the macros in
2c60: 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 73 20 different ways
2c70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
2c80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a 2a 2f .** compiler..*/
2c90: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 50 .#if defined(__P
2ca0: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 20 20 TRDIFF_TYPE__)
2cb0: 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 68 6f /* This case sho
2cc0: 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 43 43 uld work for GCC
2cd0: 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c */.# define SQL
2ce0: 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 ITE_INT_TO_PTR(X
2cf0: 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f 50 54 ) ((void*)(__PT
2d00: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 RDIFF_TYPE__)(X)
2d10: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 ).# define SQLIT
2d20: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 E_PTR_TO_INT(X)
2d30: 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 49 46 ((int)(__PTRDIF
2d40: 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a 23 65 F_TYPE__)(X)).#e
2d50: 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f 5f 47 lif !defined(__G
2d60: 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f 2a 20 NUC__) /*
2d70: 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 69 6c Works for compil
2d80: 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e 20 4c ers other than L
2d90: 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 LVM */.# define
2da0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 SQLITE_INT_TO_PT
2db0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 26 28 R(X) ((void*)&(
2dc0: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a 23 20 (char*)0)[X]).#
2dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 define SQLITE_PT
2de0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 R_TO_INT(X) ((i
2df0: 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 2d 28 nt)(((char*)X)-(
2e00: 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 66 20 char*)0)).#elif
2e10: 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 54 44 defined(HAVE_STD
2e20: 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 65 20 INT_H) /* Use
2e30: 74 68 69 73 20 63 61 73 65 20 69 66 20 77 65 20 this case if we
2e40: 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 65 72 have ANSI header
2e50: 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 s */.# define SQ
2e60: 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 LITE_INT_TO_PTR(
2e70: 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 6e 74 X) ((void*)(int
2e80: 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 65 66 ptr_t)(X)).# def
2e90: 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54 ine SQLITE_PTR_T
2ea0: 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29 O_INT(X) ((int)
2eb0: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 (intptr_t)(X)).#
2ec0: 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 20 20 else
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2ee0: 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 61 72 Generates a war
2ef0: 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 61 6c ning - but it al
2f00: 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a 23 20 ways works */.#
2f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2f20: 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76 T_TO_PTR(X) ((v
2f30: 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 66 69 oid*)(X)).# defi
2f40: 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f ne SQLITE_PTR_TO
2f50: 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29 28 _INT(X) ((int)(
2f60: 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a X)).#endif../*.*
2f70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 48 52 * The SQLITE_THR
2f80: 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 6d 75 EADSAFE macro mu
2f90: 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 61 73 st be defined as
2fa0: 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a 2a 20 0, 1, or 2..**
2fb0: 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 73 20 0 means mutexes
2fc0: 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79 20 are permanently
2fd0: 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 65 20 disable and the
2fe0: 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 65 72 library is never
2ff0: 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2e 20 .** threadsafe.
3000: 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c 69 62 1 means the lib
3010: 72 61 72 79 20 69 73 20 73 65 72 69 61 6c 69 7a rary is serializ
3020: 65 64 20 77 68 69 63 68 20 69 73 20 74 68 65 20 ed which is the
3030: 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 65 6c highest.** level
3040: 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 74 79 of threadsafety
3050: 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 20 6c . 2 means the l
3060: 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69 74 68 ibary is multith
3070: 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69 70 6c readed - multipl
3080: 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63 61 6e e.** threads can
3090: 20 75 73 65 20 53 51 4c 69 74 65 20 61 73 20 6c use SQLite as l
30a0: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
30b0: 72 65 61 64 73 20 74 72 79 20 74 6f 20 75 73 65 reads try to use
30c0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
30d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
30f0: 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72 20 76 e..**.** Older v
3100: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3110: 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69 6f 6e e used an option
3120: 61 6c 20 54 48 52 45 41 44 53 41 46 45 20 6d 61 al THREADSAFE ma
3130: 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70 70 6f cro..** We suppo
3140: 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65 67 61 rt that for lega
3150: 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 cy..*/.#if !defi
3160: 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 45 41 ned(SQLITE_THREA
3170: 44 53 41 46 45 29 0a 23 69 66 20 64 65 66 69 6e DSAFE).#if defin
3180: 65 64 28 54 48 52 45 41 44 53 41 46 45 29 0a 23 ed(THREADSAFE).#
3190: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 20 54 48 52 45 41 44 HREADSAFE THREAD
31b0: 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64 65 66 SAFE.#else.# def
31c0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 ine SQLITE_THREA
31d0: 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50 3a 20 DSAFE 1 /* IMP:
31e0: 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20 2a 2f R-07272-22309 */
31f0: 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a .#endif.#endif..
3200: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 /*.** The SQLITE
3210: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 _DEFAULT_MEMSTAT
3220: 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 US macro must be
3230: 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74 68 defined as eith
3240: 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74 er 0 or 1..** It
3250: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 74 determines whet
3260: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 her or not the f
3270: 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64 20 eatures related
3280: 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f to .** SQLITE_CO
3290: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 61 NFIG_MEMSTATUS a
32a0: 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20 re available by
32b0: 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20 default or not.
32c0: 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a This value can.*
32d0: 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 * be overridden
32e0: 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 at runtime using
32f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e the sqlite3_con
3300: 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69 fig() API..*/.#i
3310: 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 f !defined(SQLIT
3320: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 E_DEFAULT_MEMSTA
3330: 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53 51 TUS).# define SQ
3340: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d LITE_DEFAULT_MEM
3350: 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66 0a STATUS 1.#endif.
3360: 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f ./*.** Exactly o
3370: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
3380: 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74 20 ing macros must
3390: 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f 72 be defined in or
33a0: 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66 der to.** specif
33b0: 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20 61 y which memory a
33c0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
33d0: 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a tem to use..**.*
33e0: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59 53 * SQLITE_SYS
33f0: 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 TEM_MALLOC
3400: 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61 // Use norma
3410: 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 l system malloc(
3420: 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f ).** SQLITE_
3430: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 20 20 20 20 WIN32_MALLOC
3440: 20 20 20 20 20 20 20 2f 2f 20 55 73 65 20 57 69 // Use Wi
3450: 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 n32 native heap
3460: 41 50 49 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 API.** SQLIT
3470: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20 E_MEMDEBUG
3480: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75 // Debu
3490: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66 gging version of
34a0: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
34b0: 0a 2a 2a 0a 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77 .**.** On Window
34c0: 73 2c 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 s, if the SQLITE
34d0: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41 _WIN32_MALLOC_VA
34e0: 4c 49 44 41 54 45 20 6d 61 63 72 6f 20 69 73 20 LIDATE macro is
34f0: 64 65 66 69 6e 65 64 20 61 6e 64 20 74 68 65 0a defined and the.
3500: 2a 2a 20 61 73 73 65 72 74 28 29 20 6d 61 63 72 ** assert() macr
3510: 6f 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 65 61 o is enabled, ea
3520: 63 68 20 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65 ch call into the
3530: 20 57 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65 Win32 native he
3540: 61 70 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 ap subsystem.**
3550: 77 69 6c 6c 20 63 61 75 73 65 20 48 65 61 70 56 will cause HeapV
3560: 61 6c 69 64 61 74 65 20 74 6f 20 62 65 20 63 61 alidate to be ca
3570: 6c 6c 65 64 2e 20 20 49 66 20 68 65 61 70 20 76 lled. If heap v
3580: 61 6c 69 64 61 74 69 6f 6e 20 73 68 6f 75 6c 64 alidation should
3590: 20 66 61 69 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73 fail, an.** ass
35a0: 65 72 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 74 ertion will be t
35b0: 72 69 67 67 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 riggered..**.**
35c0: 28 48 69 73 74 6f 72 69 63 61 6c 20 6e 6f 74 65 (Historical note
35d0: 3a 20 20 54 68 65 72 65 20 75 73 65 64 20 74 6f : There used to
35e0: 20 62 65 20 73 65 76 65 72 61 6c 20 6f 74 68 65 be several othe
35f0: 72 20 6f 70 74 69 6f 6e 73 2c 20 62 75 74 20 77 r options, but w
3600: 65 27 76 65 0a 2a 2a 20 70 61 72 65 64 20 69 74 e've.** pared it
3610: 20 64 6f 77 6e 20 74 6f 20 6a 75 73 74 20 74 68 down to just th
3620: 65 73 65 20 74 77 6f 2e 29 0a 2a 2a 0a 2a 2a 20 ese two.).**.**
3630: 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 If none of the a
3640: 62 6f 76 65 20 61 72 65 20 64 65 66 69 6e 65 64 bove are defined
3650: 2c 20 74 68 65 6e 20 73 65 74 20 53 51 4c 49 54 , then set SQLIT
3660: 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 E_SYSTEM_MALLOC
3670: 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c as.** the defaul
3680: 74 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 t..*/.#if define
3690: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f d(SQLITE_SYSTEM_
36a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 MALLOC)+defined(
36b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c SQLITE_WIN32_MAL
36c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c LOC)+defined(SQL
36d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a ITE_MEMDEBUG)>1.
36e0: 23 20 65 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 # error "At most
36f0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
3700: 6f 77 69 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 owing compile-ti
3710: 6d 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e me configuration
3720: 20 6f 70 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c options\. is al
3730: 6c 6f 77 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 lows: SQLITE_SYS
3740: 54 45 4d 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 TEM_MALLOC, SQLI
3750: 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c TE_WIN32_MALLOC,
3760: 20 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 SQLITE_MEMDEBUG
3770: 22 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 ".#endif.#if def
3780: 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 ined(SQLITE_SYST
3790: 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e EM_MALLOC)+defin
37a0: 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f ed(SQLITE_WIN32_
37b0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 MALLOC)+defined(
37c0: 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 SQLITE_MEMDEBUG)
37d0: 3d 3d 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ==0.# define SQL
37e0: 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f ITE_SYSTEM_MALLO
37f0: 43 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a C 1.#endif../*.*
3800: 2a 20 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c * If SQLITE_MALL
3810: 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 OC_SOFT_LIMIT is
3820: 20 6e 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 not zero, then
3830: 74 72 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a try to keep the.
3840: 2a 2a 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f ** sizes of memo
3850: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 ry allocations b
3860: 65 6c 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20 elow this value
3870: 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a where possible..
3880: 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 */.#if !defined(
3890: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f SQLITE_MALLOC_SO
38a0: 46 54 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 FT_LIMIT).# defi
38b0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 ne SQLITE_MALLOC
38c0: 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 _SOFT_LIMIT 1024
38d0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 .#endif../*.** W
38e0: 65 20 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65 e need to define
38f0: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 _XOPEN_SOURCE a
3900: 73 20 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 s follows in ord
3910: 65 72 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 er to enable.**
3920: 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 recursive mutexe
3930: 73 20 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 s on most Unix s
3940: 79 73 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 ystems. But Mac
3950: 20 4f 53 20 58 20 69 73 20 64 69 66 66 65 72 65 OS X is differe
3960: 6e 74 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 nt..** The _XOPE
3970: 4e 5f 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20 N_SOURCE define
3980: 63 61 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 causes problems
3990: 66 6f 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20 for Mac OS X we
39a0: 61 72 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 are told,.** so
39b0: 69 74 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68 it is omitted th
39c0: 65 72 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ere. See ticket
39d0: 20 23 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 #2673..**.** La
39e0: 74 65 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61 ter we learn tha
39f0: 74 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 t _XOPEN_SOURCE
3a00: 69 73 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 is poorly or inc
3a10: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c orrectly.** impl
3a20: 65 6d 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 emented on some
3a30: 73 79 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 systems. So we
3a40: 61 76 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69 avoid defining i
3a50: 74 20 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 t at all.** if i
3a60: 74 20 69 73 20 61 6c 72 65 61 64 79 20 64 65 66 t is already def
3a70: 69 6e 65 64 20 6f 72 20 69 66 20 69 74 20 69 73 ined or if it is
3a80: 20 75 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73 unneeded becaus
3a90: 65 20 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 e we are.** not
3aa0: 64 6f 69 6e 67 20 61 20 74 68 72 65 61 64 73 61 doing a threadsa
3ab0: 66 65 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 fe build. Ticke
3ac0: 74 20 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 t #2681..**.** S
3ad0: 65 65 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 ee also ticket #
3ae0: 32 37 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 2741..*/.#if !de
3af0: 66 69 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 fined(_XOPEN_SOU
3b00: 52 43 45 29 20 26 26 20 21 64 65 66 69 6e 65 64 RCE) && !defined
3b10: 28 5f 5f 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 (__DARWIN__) &&
3b20: 21 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 !defined(__APPLE
3b30: 5f 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48 __) && SQLITE_TH
3b40: 52 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69 READSAFE.# defi
3b50: 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 ne _XOPEN_SOURCE
3b60: 20 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 500 /* Needed
3b70: 74 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61 to enable pthrea
3b80: 64 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 d recursive mute
3b90: 78 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f xes */.#endif../
3ba0: 2a 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61 *.** The TCL hea
3bb0: 64 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 ders are only ne
3bc0: 65 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c eded when compil
3bd0: 69 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64 ing the TCL bind
3be0: 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 ings..*/.#if def
3bf0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 ined(SQLITE_TCL)
3c00: 20 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53 || defined(TCLS
3c10: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 H).# include <tc
3c20: 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a l.h>.#endif../*.
3c30: 2a 2a 20 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61 ** Many people a
3c40: 72 65 20 66 61 69 6c 69 6e 67 20 74 6f 20 73 65 re failing to se
3c50: 74 20 2d 44 4e 44 45 42 55 47 3d 31 20 77 68 65 t -DNDEBUG=1 whe
3c60: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69 n compiling SQLi
3c70: 74 65 2e 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e te..** Setting N
3c80: 44 45 42 55 47 20 6d 61 6b 65 73 20 74 68 65 20 DEBUG makes the
3c90: 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64 code smaller and
3ca0: 20 72 75 6e 20 66 61 73 74 65 72 2e 20 20 53 6f run faster. So
3cb0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a the following.*
3cc0: 2a 20 6c 69 6e 65 73 20 61 72 65 20 61 64 64 65 * lines are adde
3cd0: 64 20 74 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c d to automatical
3ce0: 6c 79 20 73 65 74 20 4e 44 45 42 55 47 20 75 6e ly set NDEBUG un
3cf0: 6c 65 73 73 20 74 68 65 20 2d 44 53 51 4c 49 54 less the -DSQLIT
3d00: 45 5f 44 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74 E_DEBUG=1.** opt
3d10: 69 6f 6e 20 69 73 20 73 65 74 2e 20 20 54 68 75 ion is set. Thu
3d20: 73 20 4e 44 45 42 55 47 20 62 65 63 6f 6d 65 73 s NDEBUG becomes
3d30: 20 61 6e 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 an opt-in rathe
3d40: 72 20 74 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 r than an opt-ou
3d50: 74 0a 2a 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f t.** feature..*/
3d60: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 .#if !defined(ND
3d70: 45 42 55 47 29 20 26 26 20 21 64 65 66 69 6e 65 EBUG) && !define
3d80: 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 20 d(SQLITE_DEBUG)
3d90: 0a 23 20 64 65 66 69 6e 65 20 4e 44 45 42 55 47 .# define NDEBUG
3da0: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 1.#endif../*.**
3db0: 20 54 68 65 20 74 65 73 74 63 61 73 65 28 29 20 The testcase()
3dc0: 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f macro is used to
3dd0: 20 61 69 64 20 69 6e 20 63 6f 76 65 72 61 67 65 aid in coverage
3de0: 20 74 65 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 testing. When
3df0: 0a 2a 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 .** doing covera
3e00: 67 65 20 74 65 73 74 69 6e 67 2c 20 74 68 65 20 ge testing, the
3e10: 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 condition inside
3e20: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
3e30: 0a 2a 2a 20 74 65 73 74 63 61 73 65 28 29 20 6d .** testcase() m
3e40: 75 73 74 20 62 65 20 65 76 61 6c 75 61 74 65 64 ust be evaluated
3e50: 20 62 6f 74 68 20 74 72 75 65 20 61 6e 64 20 66 both true and f
3e60: 61 6c 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f alse in order to
3e70: 0a 2a 2a 20 67 65 74 20 66 75 6c 6c 20 62 72 61 .** get full bra
3e80: 6e 63 68 20 63 6f 76 65 72 61 67 65 2e 20 20 54 nch coverage. T
3e90: 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 he testcase() ma
3ea0: 63 72 6f 20 69 73 20 69 6e 73 65 72 74 65 64 0a cro is inserted.
3eb0: 2a 2a 20 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 ** to help ensur
3ec0: 65 20 61 64 65 71 75 61 74 65 20 74 65 73 74 20 e adequate test
3ed0: 63 6f 76 65 72 61 67 65 20 69 6e 20 70 6c 61 63 coverage in plac
3ee0: 65 73 20 77 68 65 72 65 20 73 69 6d 70 6c 65 0a es where simple.
3ef0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 ** condition/dec
3f00: 69 73 69 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 ision coverage i
3f10: 73 20 69 6e 61 64 65 71 75 61 74 65 2e 20 20 46 s inadequate. F
3f20: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 or example, test
3f30: 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 case().** can be
3f40: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 used to make su
3f50: 72 65 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 re boundary valu
3f60: 65 73 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 es are tested.
3f70: 46 6f 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 For.** bitmask t
3f80: 65 73 74 73 2c 20 74 65 73 74 63 61 73 65 28 29 ests, testcase()
3f90: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
3fa0: 6d 61 6b 65 20 73 75 72 65 20 65 61 63 68 20 62 make sure each b
3fb0: 69 74 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 it.** is signifi
3fc0: 63 61 6e 74 20 61 6e 64 20 75 73 65 64 20 61 74 cant and used at
3fd0: 20 6c 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e least once. On
3fe0: 20 73 77 69 74 63 68 20 73 74 61 74 65 6d 65 6e switch statemen
3ff0: 74 73 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 ts.** where mult
4000: 69 70 6c 65 20 63 61 73 65 73 20 67 6f 20 74 6f iple cases go to
4010: 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 the same block
4020: 6f 66 20 63 6f 64 65 2c 20 74 65 73 74 63 61 73 of code, testcas
4030: 65 28 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 e().** can insur
4040: 65 20 74 68 61 74 20 61 6c 6c 20 63 61 73 65 73 e that all cases
4050: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 2e 0a are evaluated..
4060: 2a 2a 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c **.*/.#ifdef SQL
4070: 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 ITE_COVERAGE_TES
4080: 54 0a 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 T.SQLITE_PRIVATE
4090: 20 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 43 void sqlite3C
40a0: 6f 76 65 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 overage(int);.#
40b0: 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 define testcase(
40c0: 58 29 20 20 69 66 28 20 58 20 29 7b 20 73 71 6c X) if( X ){ sql
40d0: 69 74 65 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c ite3Coverage(__L
40e0: 49 4e 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a INE__); }.#else.
40f0: 23 20 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 # define testcas
4100: 65 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a e(X).#endif../*.
4110: 2a 2a 20 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 ** The TESTONLY
4120: 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f macro is used to
4130: 20 65 6e 63 6c 6f 73 65 20 76 61 72 69 61 62 6c enclose variabl
4140: 65 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f e declarations o
4150: 72 0a 2a 2a 20 6f 74 68 65 72 20 62 69 74 73 20 r.** other bits
4160: 6f 66 20 63 6f 64 65 20 74 68 61 74 20 61 72 65 of code that are
4170: 20 6e 65 65 64 65 64 20 74 6f 20 73 75 70 70 6f needed to suppo
4180: 72 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 rt the arguments
4190: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 65 73 74 63 .** within testc
41a0: 61 73 65 28 29 20 61 6e 64 20 61 73 73 65 72 74 ase() and assert
41b0: 28 29 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 () macros..*/.#i
41c0: 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 f !defined(NDEBU
41d0: 47 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 G) || defined(SQ
41e0: 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 LITE_COVERAGE_TE
41f0: 53 54 29 0a 23 20 64 65 66 69 6e 65 20 54 45 53 ST).# define TES
4200: 54 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 TONLY(X) X.#els
4210: 65 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f e.# define TESTO
4220: 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f NLY(X).#endif../
4230: 2a 0a 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 *.** Sometimes w
4240: 65 20 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 e need a small a
4250: 6d 6f 75 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 mount of code su
4260: 63 68 20 61 73 20 61 20 76 61 72 69 61 62 6c 65 ch as a variable
4270: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a initialization.
4280: 2a 2a 20 74 6f 20 73 65 74 75 70 20 66 6f 72 20 ** to setup for
4290: 61 20 6c 61 74 65 72 20 61 73 73 65 72 74 28 29 a later assert()
42a0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 statement. We
42b0: 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 do not want this
42c0: 20 63 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 code to.** appe
42d0: 61 72 20 77 68 65 6e 20 61 73 73 65 72 74 28 29 ar when assert()
42e0: 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 is disabled. T
42f0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 he following mac
4300: 72 6f 20 69 73 20 74 68 65 72 65 66 6f 72 65 0a ro is therefore.
4310: 2a 2a 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 ** used to conta
4320: 69 6e 20 74 68 61 74 20 73 65 74 75 70 20 63 6f in that setup co
4330: 64 65 2e 20 20 54 68 65 20 22 56 56 41 22 20 61 de. The "VVA" a
4340: 63 72 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f cronym stands fo
4350: 72 0a 2a 2a 20 22 56 65 72 69 66 69 63 61 74 69 r.** "Verificati
4360: 6f 6e 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 on, Validation,
4370: 61 6e 64 20 41 63 63 72 65 64 69 74 61 74 69 6f and Accreditatio
4380: 6e 22 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f n". In other wo
4390: 72 64 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 rds, the.** code
43a0: 20 77 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 within VVA_ONLY
43b0: 28 29 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e () will only run
43c0: 20 64 75 72 69 6e 67 20 76 65 72 69 66 69 63 61 during verifica
43d0: 74 69 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a tion processes..
43e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 */.#ifndef NDEBU
43f0: 47 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f G.# define VVA_O
4400: 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a NLY(X) X.#else.
4410: 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c # define VVA_ONL
4420: 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a Y(X).#endif../*.
4430: 2a 2a 20 54 68 65 20 41 4c 57 41 59 53 20 61 6e ** The ALWAYS an
4440: 64 20 4e 45 56 45 52 20 6d 61 63 72 6f 73 20 73 d NEVER macros s
4450: 75 72 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 urround boolean
4460: 65 78 70 72 65 73 73 69 6f 6e 73 20 77 68 69 63 expressions whic
4470: 68 20 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 h .** are intend
4480: 65 64 20 74 6f 20 61 6c 77 61 79 73 20 62 65 20 ed to always be
4490: 74 72 75 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 true or false, r
44a0: 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 53 75 espectively. Su
44b0: 63 68 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e ch.** expression
44c0: 73 20 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 s could be omitt
44d0: 65 64 20 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 ed from the code
44e0: 20 63 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 completely. Bu
44f0: 74 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e t they.** are in
4500: 63 6c 75 64 65 64 20 69 6e 20 61 20 66 65 77 20 cluded in a few
4510: 63 61 73 65 73 20 69 6e 20 6f 72 64 65 72 20 74 cases in order t
4520: 6f 20 65 6e 68 61 6e 63 65 20 74 68 65 20 72 65 o enhance the re
4530: 73 69 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 silience.** of S
4540: 51 4c 69 74 65 20 74 6f 20 75 6e 65 78 70 65 63 QLite to unexpec
4550: 74 65 64 20 62 65 68 61 76 69 6f 72 20 2d 20 74 ted behavior - t
4560: 6f 20 6d 61 6b 65 20 74 68 65 20 63 6f 64 65 20 o make the code
4570: 22 73 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a "self-healing".*
4580: 2a 20 6f 72 20 22 64 75 63 74 69 6c 65 22 20 72 * or "ductile" r
4590: 61 74 68 65 72 20 74 68 61 6e 20 62 65 69 6e 67 ather than being
45a0: 20 22 62 72 69 74 74 6c 65 22 20 61 6e 64 20 63 "brittle" and c
45b0: 72 61 73 68 69 6e 67 20 61 74 20 74 68 65 20 66 rashing at the f
45c0: 69 72 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 irst.** hint of
45d0: 75 6e 70 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 unplanned behavi
45e0: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 or..**.** In oth
45f0: 65 72 20 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 er words, ALWAYS
4600: 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 61 and NEVER are a
4610: 64 64 65 64 20 66 6f 72 20 64 65 66 65 6e 73 69 dded for defensi
4620: 76 65 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 ve code..**.** W
4630: 68 65 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 hen doing covera
4640: 67 65 20 74 65 73 74 69 6e 67 20 41 4c 57 41 59 ge testing ALWAY
4650: 53 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 S and NEVER are
4660: 68 61 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a hard-coded to.**
4670: 20 62 65 20 74 72 75 65 20 61 6e 64 20 66 61 6c be true and fal
4680: 73 65 20 73 6f 20 74 68 61 74 20 74 68 65 20 75 se so that the u
4690: 6e 72 65 61 63 68 61 62 6c 65 20 63 6f 64 65 20 nreachable code
46a0: 74 68 65 6e 20 73 70 65 63 69 66 79 20 77 69 6c then specify wil
46b0: 6c 0a 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e l.** not be coun
46c0: 74 65 64 20 61 73 20 75 6e 74 65 73 74 65 64 20 ted as untested
46d0: 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 code..*/.#if def
46e0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 ined(SQLITE_COVE
46f0: 52 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 RAGE_TEST).# def
4700: 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 ine ALWAYS(X)
4710: 20 20 20 28 31 29 0a 23 20 64 65 66 69 6e 65 20 (1).# define
4720: 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 NEVER(X) (
4730: 30 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 0).#elif !define
4740: 64 28 4e 44 45 42 55 47 29 0a 23 20 64 65 66 69 d(NDEBUG).# defi
4750: 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 ne ALWAYS(X)
4760: 20 20 28 28 58 29 3f 31 3a 28 61 73 73 65 72 74 ((X)?1:(assert
4770: 28 30 29 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 (0),0)).# define
4780: 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 NEVER(X)
4790: 28 28 58 29 3f 28 61 73 73 65 72 74 28 30 29 2c ((X)?(assert(0),
47a0: 31 29 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 1):0).#else.# de
47b0: 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 fine ALWAYS(X)
47c0: 20 20 20 20 28 58 29 0a 23 20 64 65 66 69 6e 65 (X).# define
47d0: 20 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 NEVER(X)
47e0: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a (X).#endif../*.*
47f0: 2a 20 52 65 74 75 72 6e 20 74 72 75 65 20 28 6e * Return true (n
4800: 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 20 on-zero) if the
4810: 69 6e 70 75 74 20 69 73 20 61 20 69 6e 74 65 67 input is a integ
4820: 65 72 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c er that is too l
4830: 61 72 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 arge.** to fit i
4840: 6e 20 33 32 2d 62 69 74 73 2e 20 20 54 68 69 73 n 32-bits. This
4850: 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 69 macro is used i
4860: 6e 73 69 64 65 20 6f 66 20 76 61 72 69 6f 75 73 nside of various
4870: 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d testcase().** m
4880: 61 63 72 6f 73 20 74 6f 20 76 65 72 69 66 79 20 acros to verify
4890: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 65 73 that we have tes
48a0: 74 65 64 20 53 51 4c 69 74 65 20 66 6f 72 20 6c ted SQLite for l
48b0: 61 72 67 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 arge-file suppor
48c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 t..*/.#define IS
48d0: 5f 42 49 47 5f 49 4e 54 28 58 29 20 20 28 28 28 _BIG_INT(X) (((
48e0: 58 29 26 7e 28 69 36 34 29 30 78 66 66 66 66 66 X)&~(i64)0xfffff
48f0: 66 66 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 fff)!=0)../*.**
4900: 54 68 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 The macro unlike
4910: 6c 79 28 29 20 69 73 20 61 20 68 69 6e 74 20 74 ly() is a hint t
4920: 68 61 74 20 73 75 72 72 6f 75 6e 64 73 20 61 20 hat surrounds a
4930: 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 boolean.** expre
4940: 73 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 ssion that is us
4950: 75 61 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 ually false. Ma
4960: 63 72 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 cro likely() sur
4970: 72 6f 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c rounds.** a bool
4980: 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 74 ean expression t
4990: 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 74 hat is usually t
49a0: 72 75 65 2e 20 20 47 43 43 20 69 73 20 61 62 6c rue. GCC is abl
49b0: 65 20 74 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 e to.** use thes
49c0: 65 20 68 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 e hints to gener
49d0: 61 74 65 20 62 65 74 74 65 72 20 63 6f 64 65 2c ate better code,
49e0: 20 73 6f 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 sometimes..*/.#
49f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 if defined(__GNU
4a00: 43 5f 5f 29 20 26 26 20 30 0a 23 20 64 65 66 69 C__) && 0.# defi
4a10: 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 ne likely(X)
4a20: 5f 5f 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 __builtin_expect
4a30: 28 28 58 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 ((X),1).# define
4a40: 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f unlikely(X) __
4a50: 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 builtin_expect((
4a60: 58 29 2c 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 X),0).#else.# de
4a70: 66 69 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 fine likely(X)
4a80: 20 20 21 21 28 58 29 0a 23 20 64 65 66 69 6e 65 !!(X).# define
4a90: 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 unlikely(X) !!
4aa0: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a (X).#endif../***
4ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c *********** Incl
4ac0: 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e ude sqlite3.h in
4ad0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 the middle of s
4ae0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a qliteInt.h *****
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a **********/./***
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 *********** Begi
4b10: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 n file sqlite3.h
4b20: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a **********/./*.*
4b50: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 * 2001 September
4b60: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 15.**.** The au
4b70: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
4b80: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
4b90: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
4ba0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
4bb0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
4bc0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
4bd0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
4be0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
4bf0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
4c00: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
4c10: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
4c20: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
4c30: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
4c40: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
4c50: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
4c60: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
4c70: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
4c80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4cc0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 **.** This heade
4cd0: 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 r file defines t
4ce0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 he interface tha
4cf0: 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 t the SQLite lib
4d00: 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 rary.** presents
4d10: 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 to client progr
4d20: 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e ams. If a C-fun
4d30: 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 ction, structure
4d40: 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f , datatype,.** o
4d50: 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e r constant defin
4d60: 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 ition does not a
4d70: 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 ppear in this fi
4d80: 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a le, then it is.*
4d90: 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 * not a publishe
4da0: 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c d API of SQLite,
4db0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
4dc0: 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a hange without.**
4dd0: 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f notice, and sho
4de0: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 uld not be refer
4df0: 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d enced by program
4e00: 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 s that use SQLit
4e10: 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 e..**.** Some of
4e20: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 the definitions
4e30: 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 that are in thi
4e40: 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 s file are marke
4e50: 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d d as.** "experim
4e60: 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d ental". Experim
4e70: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
4e80: 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 are normally ne
4e90: 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 w.** features re
4ea0: 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 cently added to
4eb0: 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e SQLite. We do n
4ec0: 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 ot anticipate ch
4ed0: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 anges.** to expe
4ee0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 rimental interfa
4ef0: 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 ces but reserve
4f00: 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b the right to mak
4f10: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a e minor changes.
4f20: 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 ** if experience
4f30: 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 from use "in th
4f40: 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 e wild" suggest
4f50: 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 such changes are
4f60: 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 prudent..**.**
4f70: 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c The official C-l
4f80: 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 anguage API docu
4f90: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 mentation for SQ
4fa0: 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a Lite is derived.
4fb0: 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 ** from comments
4fc0: 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 in this file.
4fd0: 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 This file is the
4fe0: 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 authoritative s
4ff0: 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 ource.** on how
5000: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
5010: 73 20 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f s are suppose to
5020: 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 operate..**.**
5030: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 The name of this
5040: 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 file under conf
5050: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 iguration manage
5060: 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e ment is "sqlite.
5070: 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 h.in"..** The ma
5080: 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d kefile makes som
5090: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 e minor changes
50a0: 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 to this file (su
50b0: 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a ch as inserting.
50c0: 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e ** the version n
50d0: 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 umber) and chang
50e0: 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 es its name to "
50f0: 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a sqlite3.h" as.**
5100: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 part of the bui
5110: 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 ld process..*/.#
5120: 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f ifndef _SQLITE3_
5130: 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 H_.#define _SQLI
5140: 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 TE3_H_.#include
5150: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f <stdarg.h> /
5160: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 * Needed for the
5170: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 definition of v
5180: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a a_list */../*.**
5190: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 Make sure we ca
51a0: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 n call this stuf
51b0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 f from C++..*/.#
51c0: 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 if 0.extern "C"
51d0: 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a {.#endif.../*.**
51e0: 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 Add the ability
51f0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 to override 'ex
5200: 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 tern'.*/.#ifndef
5210: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 SQLITE_EXTERN.#
5220: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 define SQLITE_E
5230: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e XTERN extern.#en
5240: 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c dif..#ifndef SQL
5250: 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 ITE_API.# define
5260: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 SQLITE_API.#end
5270: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 if.../*.** These
5280: 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 no-op macros ar
5290: 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 e used in front
52a0: 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f of interfaces to
52b0: 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 mark those.** i
52c0: 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 74 nterfaces as eit
52d0: 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 6f her deprecated o
52e0: 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 r experimental.
52f0: 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e New application
5300: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 s.** should not
5310: 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 69 use deprecated i
5320: 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 nterfaces - they
5330: 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 are support for
5340: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f backwards.** co
5350: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 mpatibility only
5360: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 . Application w
5370: 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 riters should be
5380: 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 aware that.** e
5390: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 xperimental inte
53a0: 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 rfaces are subje
53b0: 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 ct to change in
53c0: 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a point releases..
53d0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 **.** These macr
53e0: 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c os used to resol
53f0: 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 ve to various ki
5400: 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 nds of compiler
5410: 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f magic that.** wo
5420: 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 uld generate war
5430: 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 ning messages wh
5440: 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 en they were use
5450: 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 d. But that.**
5460: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 compiler magic e
5470: 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 nded up generati
5480: 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 ng such a flurry
5490: 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a of bug reports.
54a0: 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 ** that we have
54b0: 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 taken it all out
54c0: 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 and gone back t
54d0: 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a o using simple.*
54e0: 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a * noop macros..*
54f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5500: 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 _DEPRECATED.#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 ine SQLITE_EXPER
5520: 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 IMENTAL../*.** E
5530: 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 nsure these symb
5540: 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 ols were not def
5550: 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 ined by some pre
5560: 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c vious header fil
5570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
5580: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e ITE_VERSION.# un
5590: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
55a0: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 ON.#endif.#ifdef
55b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
55c0: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 NUMBER.# undef S
55d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
55e0: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a MBER.#endif../*.
55f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
5600: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 pile-Time Librar
5610: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 y Version Number
5620: 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 s.**.** ^(The [S
5630: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 QLITE_VERSION] C
5640: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
5650: 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 cro in the sqlit
5660: 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 e3.h header.** e
5670: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 valuates to a st
5680: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 ring literal tha
5690: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 t is the SQLite
56a0: 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a version in the.*
56b0: 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 * format "X.Y.Z"
56c0: 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20 where X is the
56d0: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 major version nu
56e0: 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 mber (always 3 f
56f0: 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 or.** SQLite3) a
5700: 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f nd Y is the mino
5710: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 r version number
5720: 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 and Z is the re
5730: 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a lease number.)^.
5740: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 ** ^(The [SQLITE
5750: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
5760: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
5770: 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 macro resolves t
5780: 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 o an integer.**
5790: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 with the value (
57a0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 X*1000000 + Y*10
57b0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 00 + Z) where X,
57c0: 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 Y, and Z are th
57d0: 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 e same.** number
57e0: 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 s used in [SQLIT
57f0: 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a E_VERSION].)^.**
5800: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 The SQLITE_VERS
5810: 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 ION_NUMBER for a
5820: 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 ny given release
5830: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
5840: 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 also.** be large
5850: 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 r than the relea
5860: 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 se from which it
5870: 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 is derived. Ei
5880: 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 ther Y will.** b
5890: 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 e held constant
58a0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e and Z will be in
58b0: 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 cremented or els
58c0: 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 e Y will be incr
58d0: 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a emented.** and Z
58e0: 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 will be reset t
58f0: 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 o zero..**.** Si
5900: 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e nce version 3.6.
5910: 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 18, SQLite sourc
5920: 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 e code has been
5930: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a stored in the.**
5940: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f <a href="http:/
5950: 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e /www.fossil-scm.
5960: 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e org/">Fossil con
5970: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 figuration manag
5980: 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c ement.** system<
5990: 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 /a>. ^The SQLIT
59a0: 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 E_SOURCE_ID macr
59b0: 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a o evaluates to.*
59c0: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 * a string which
59d0: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 identifies a pa
59e0: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 rticular check-i
59f0: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 n of SQLite.** w
5a00: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 ithin its config
5a10: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
5a20: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 nt system. ^The
5a30: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
5a40: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 D.** string cont
5a50: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e ains the date an
5a60: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 d time of the ch
5a70: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 eck-in (UTC) and
5a80: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 an SHA1.** hash
5a90: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 of the entire s
5aa0: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a ource tree..**.*
5ab0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
5ac0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
5ad0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
5ae0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
5af0: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 r()], [sqlite3_s
5b00: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b ourceid()],.** [
5b10: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
5b20: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
5b30: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 urce_id()]..*/.#
5b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
5b50: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e RSION "3.
5b60: 37 2e 38 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.8".#define SQL
5b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
5b80: 45 52 20 33 30 30 37 30 30 38 0a 23 64 65 66 69 ER 3007008.#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 ne SQLITE_SOURCE
5ba0: 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d 30 _ID "2011-0
5bb0: 38 2d 33 31 20 32 33 3a 35 37 3a 32 32 20 32 38 8-31 23:57:22 28
5bc0: 36 39 65 64 32 38 32 39 39 62 31 63 39 66 33 35 69ed28299b1c9f35
5bd0: 35 65 63 63 32 34 36 33 35 38 33 30 66 37 66 31 5ecc24635830f7f1
5be0: 32 34 39 31 32 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 249126"../*.** C
5bf0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
5c00: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
5c10: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 n Numbers.** KEY
5c20: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 WORDS: sqlite3_v
5c30: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f ersion, sqlite3_
5c40: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 sourceid.**.** T
5c50: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
5c60: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 provide the same
5c70: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 information as
5c80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 the [SQLITE_VERS
5c90: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 ION],.** [SQLITE
5ca0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d _VERSION_NUMBER]
5cb0: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f , and [SQLITE_SO
5cc0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
5cd0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a ocessor macros.*
5ce0: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 * but are associ
5cf0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 ated with the li
5d00: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
5d10: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
5d20: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a . ^(Cautious.**
5d30: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
5d40: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 ht include asser
5d50: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 t() statements i
5d60: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
5d70: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 ion to.** verify
5d80: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 that values ret
5d90: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 urned by these i
5da0: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 nterfaces match
5db0: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a the macros in.**
5dc0: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 the header, and
5dd0: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 thus insure tha
5de0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
5df0: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 n is.** compiled
5e00: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c with matching l
5e10: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 ibrary and heade
5e20: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c r files..**.** <
5e30: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
5e40: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 .** assert( sqli
5e50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
5e60: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f umber()==SQLITE_
5e70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 VERSION_NUMBER )
5e80: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
5e90: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 cmp(sqlite3_sour
5ea0: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f ceid(),SQLITE_SO
5eb0: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a URCE_ID)==0 );.*
5ec0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
5ed0: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 (sqlite3_libvers
5ee0: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 ion(),SQLITE_VER
5ef0: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c SION)==0 );.** <
5f00: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
5f10: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
5f20: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
5f30: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e ] string constan
5f40: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 t contains the t
5f50: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 ext of [SQLITE_V
5f60: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f ERSION].** macro
5f70: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
5f80: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e libversion() fun
5f90: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 ction returns a
5fa0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
5fb0: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
5fc0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
5fd0: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 g constant. The
5fe0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
5ff0: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f ion().** functio
6000: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f n is provided fo
6010: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
6020: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
6030: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
6040: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 e.** direct acce
6050: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e ss to string con
6060: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
6070: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 e DLL. ^The.**
6080: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
6090: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 on_number() func
60a0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 tion returns an
60b0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
60c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
60d0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 ION_NUMBER]. ^T
60e0: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 he sqlite3_sourc
60f0: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 eid() function r
6100: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 eturns .** a poi
6110: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 nter to a string
6120: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 constant whose
6130: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d value is the sam
6140: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 e as the .** [SQ
6150: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 LITE_SOURCE_ID]
6160: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
6170: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 acro..**.** See
6180: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 also: [sqlite_ve
6190: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
61a0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
61b0: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
61c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 const char sqli
61d0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 te3_version[] =
61e0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a SQLITE_VERSION;.
61f0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
6200: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c char *sqlite3_l
6210: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b ibversion(void);
6220: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
6230: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
6240: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a sourceid(void);.
6250: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
6260: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
6270: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
6280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6290: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
62a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
62b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
62c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
62d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
62e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
62f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
6300: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
6310: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
6320: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
6330: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
6340: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
6350: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
6360: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
6370: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
6380: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
6390: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
63a0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
63b0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
63c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
63d0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
63e0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
63f0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
6400: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
6410: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
6420: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
6430: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
6440: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
6450: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
6460: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
6470: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
6480: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
6490: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
64a0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
64b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
64c0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
64d0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
64e0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
64f0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
6500: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
6510: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
6520: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
6530: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
6540: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
6550: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
6560: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
6570: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
6580: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
6590: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
65a0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
65b0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
65c0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
65d0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
65e0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
65f0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
6600: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
6610: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
6620: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
6630: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
6640: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
6650: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
6660: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
6670: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
6680: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
6690: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e GS.SQLITE_API in
66a0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c t sqlite3_compil
66b0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e eoption_used(con
66c0: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d st char *zOptNam
66d0: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 e);.SQLITE_API c
66e0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
66f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
6700: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e _get(int N);.#en
6710: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
6720: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 REF: Test To See
6730: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 If The Library
6740: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a Is Threadsafe.**
6750: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
6760: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 _threadsafe() fu
6770: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a nction returns z
6780: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ero if and only
6790: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 if.** SQLite was
67a0: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 compiled mutexi
67b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
67c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
67d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
67e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
67f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
6800: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
6810: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
6820: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
6830: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
6840: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
6850: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
6860: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
6870: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
6880: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
6890: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
68a0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
68b0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
68c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
68d0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
68e0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
68f0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
6900: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
6910: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
6920: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
6930: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
6940: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
6950: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
6960: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
6970: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
6980: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
6990: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
69a0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
69b0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
69c0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
69d0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
69e0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
69f0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
6a00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
6a10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
6a20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
6a30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
6a40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
6a50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
6a60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
6a70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
6a80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
6a90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
6aa0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
6ab0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
6ac0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
6ad0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
6ae0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
6af0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
6b00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
6b10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
6b20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
6b30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
6b40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
6b50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
6b60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
6b70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
6b80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
6b90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
6ba0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
6bb0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
6bc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
6bd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
6be0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
6bf0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
6c00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
6c10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
6c20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
6c30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
6c40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
6c50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
6c60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
6c70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
6c80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
6c90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
6ca0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
6cb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
6cc0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
6cd0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
6ce0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
6cf0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
6d00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
6d10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
6d20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
6d30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
6d40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
6d50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
6d60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
6d70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
6d80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
6d90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
6da0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
6db0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
6dc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
6dd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
6de0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
6df0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
6e00: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
6e10: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
6e20: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
6e30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
6e40: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
6e50: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
6e60: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
6e70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
6e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
6e90: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
6ea0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
6eb0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
6ec0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
6ed0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
6ee0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
6ef0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
6f00: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
6f10: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
6f20: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
6f30: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
6f40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
6f50: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
6f60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
6f70: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
6f80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
6f90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
6fa0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
6fb0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
6fc0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 se()].** is its
6fd0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
6fe0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
6ff0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 r interfaces (su
7000: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 ch as.** [sqlite
7010: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
7020: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
7030: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e _function()], an
7040: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 d.** [sqlite3_bu
7050: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f sy_timeout()] to
7060: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 name but three)
7070: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 that are method
7080: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 s on an.** sqlit
7090: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 e3 object..*/.ty
70a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
70b0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f ite3 sqlite3;../
70c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 *.** CAPI3REF: 6
70d0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 4-Bit Integer Ty
70e0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
70f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
7100: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a lite_uint64.**.*
7110: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 * Because there
7120: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 is no cross-plat
7130: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 form way to spec
7140: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ify 64-bit integ
7150: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 er types.** SQLi
7160: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 te includes type
7170: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 defs for 64-bit
7180: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 signed and unsig
7190: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a ned integers..**
71a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
71b0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
71c0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 3_uint64 are the
71d0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 preferred type
71e0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 definitions..**
71f0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 The sqlite_int64
7200: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
7210: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 64 types are sup
7220: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
7230: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
7240: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ility only..**.*
7250: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
7260: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
7270: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
7280: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
7290: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
72a0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 -922337203685477
72b0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 5808 and +922337
72c0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 2036854775807 in
72d0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a clusive. ^The.*
72e0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 * sqlite3_uint64
72f0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
7300: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 64 types can sto
7310: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 re integer value
7320: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 s .** between 0
7330: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 and +18446744073
7340: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 709551615 inclus
7350: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ive..*/.#ifdef S
7360: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
7370: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
7380: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
7390: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
73a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
73b0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
73c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
73d0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
73e0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
73f0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
7400: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
7410: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
7420: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
7430: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
7440: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
7450: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
7460: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
7470: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
7480: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
7490: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
74a0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
74b0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
74c0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
74d0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
74e0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
74f0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
7500: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
7510: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
7520: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
7530: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
7540: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
7550: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
7560: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
7570: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
7580: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
7590: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
75a0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
75b0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
75c0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
75d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
75e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
75f0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 te3_close() rout
7600: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
7610: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
7620: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
7630: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
7640: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 ite3_close() ret
7650: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
7660: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
7670: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 bject is.** succ
7680: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 essfully destroy
7690: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
76a0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
76b0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
76c0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
76d0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
76e0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
76f0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
7700: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
7710: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
7720: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
7730: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
7740: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
7750: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
7760: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
7770: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
7780: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
7790: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
77a0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
77b0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
77c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
77d0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
77e0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
77f0: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
7800: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
7810: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
7820: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
7830: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
7840: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
7850: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
7860: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
7870: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
7880: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
7890: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
78a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
78b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
78c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
78d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
78e0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
78f0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
7900: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
7910: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
7920: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
7930: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
7940: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
7950: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
7960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
7970: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
7980: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
7990: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
79a0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
79b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
79c0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
79d0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
79e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
79f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
7a00: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ite3 *);../*.**
7a10: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
7a20: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
7a30: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
7a40: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
7a50: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
7a60: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
7a70: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
7a80: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
7a90: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
7aa0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 pedef int (*sqli
7ab0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
7ac0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
7ad0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
7ae0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
7af0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
7b00: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a on Interface.**.
7b10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
7b20: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
7b30: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
7b40: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
7b50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
7b60: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
7b70: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
7b80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
7b90: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 ze()],.** that a
7ba0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 llows an applica
7bb0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 tion to run mult
7bc0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 iple statements
7bd0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 of SQL.** withou
7be0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 t having to use
7bf0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
7c00: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
7c10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
7c20: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 rface runs zero
7c30: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e or more UTF-8 en
7c40: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f coded,.** semico
7c50: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c lon-separate SQL
7c60: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
7c70: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 ed into its 2nd
7c80: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 argument,.** in
7c90: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 the context of t
7ca0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
7cb0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 nection] passed
7cc0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a in as its 1st.**
7cd0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
7ce0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
7cf0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 ction of the 3rd
7d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
7d10: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
7d20: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
7d30: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 it is invoked f
7d40: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 or each result r
7d50: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 ow.** coming out
7d60: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 of the evaluate
7d70: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
7d80: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
7d90: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
7da0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c e3_exec() is rel
7db0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 ayed through to
7dc0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 the 1st argument
7dd0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c of each.** call
7de0: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e back invocation.
7df0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
7e00: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 ck pointer to sq
7e10: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
7e20: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f is NULL, then no
7e30: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 callback is eve
7e40: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 r invoked and re
7e50: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a sult rows are.**
7e60: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
7e70: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 ^If an error occ
7e80: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 urs while evalua
7e90: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 ting the SQL sta
7ea0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
7eb0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 nto.** sqlite3_e
7ec0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 xec(), then exec
7ed0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 ution of the cur
7ee0: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 rent statement s
7ef0: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 tops and.** subs
7f00: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 equent statement
7f10: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 s are skipped.
7f20: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
7f30: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
7f40: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f _exec().** is no
7f50: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 t NULL then any
7f60: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
7f70: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
7f80: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a mory obtained.**
7f90: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
7fa0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 alloc()] and pas
7fb0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 sed back through
7fc0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
7fd0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 er..** To avoid
7fe0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 memory leaks, th
7ff0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
8000: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c ould invoke [sql
8010: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 ite3_free()].**
8020: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 on error message
8030: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
8040: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 d through the 5t
8050: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a h parameter of.*
8060: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 * of sqlite3_exe
8070: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 c() after the er
8080: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
8090: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ng is no longer
80a0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 needed..** ^If t
80b0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
80c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
80d0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 () is not NULL a
80e0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 nd no errors.**
80f0: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 occur, then sqli
8100: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 te3_exec() sets
8110: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 the pointer in i
8120: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 ts 5th parameter
8130: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f to.** NULL befo
8140: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
8150: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 .** ^If an sqlit
8160: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
8170: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
8180: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ero, the sqlite3
8190: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 _exec().** routi
81a0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
81b0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 E_ABORT without
81c0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c invoking the cal
81d0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a lback again and.
81e0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 ** without runni
81f0: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e ng any subsequen
8200: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
8210: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 ..**.** ^The 2nd
8220: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
8230: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8240: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
8250: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 n is the.** numb
8260: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
8270: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 the result. ^T
8280: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
8290: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
82a0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 xec().** callbac
82b0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
82c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
82d0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 ings obtained as
82e0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c if from.** [sql
82f0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
8300: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 ()], one for eac
8310: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 h column. ^If a
8320: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a n element of a.*
8330: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 * result row is
8340: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f NULL then the co
8350: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 rresponding stri
8360: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 ng pointer for t
8370: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
8380: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
8390: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
83a0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d ^The 4th argum
83b0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 ent to the.** sq
83c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
83d0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 lback is an arra
83e0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
83f0: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 strings where e
8400: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 ach.** entry rep
8410: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 resents the name
8420: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e of correspondin
8430: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 g result column
8440: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 as obtained.** f
8450: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
8460: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a umn_name()]..**.
8470: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 ** ^If the 2nd p
8480: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
8490: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 te3_exec() is a
84a0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 NULL pointer, a
84b0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e pointer.** to an
84c0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f empty string, o
84d0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 r a pointer that
84e0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 contains only w
84f0: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 hitespace and/or
8500: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 .** SQL comment
8510: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 s, then no SQL s
8520: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 tatements are ev
8530: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 aluated and the
8540: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e database.** is n
8550: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a ot changed..**.*
8560: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a * Restrictions:.
8570: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
8580: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
8590: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 on must insure t
85a0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 hat the 1st para
85b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
85c0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 _exec().**
85d0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f is a valid and o
85e0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
85f0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c nnection]..** <l
8600: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
8610: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 on must not clos
8620: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
8630: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
8640: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 d by.** the
8650: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
8660: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
8670: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
8680: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
8690: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
86a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
86b0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 ot modify the SQ
86c0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
86d0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
86e0: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 the 2nd par
86f0: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
8700: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
8710: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
8720: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 running..** </u
8730: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l>.*/.SQLITE_API
8740: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 int sqlite3_exe
8750: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
8760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8780: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
8790: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
87a0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
87b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
87c0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
87d0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
87e0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 int (*callback)(
87f0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
8800: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 ,char**), /* Ca
8810: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
8820: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
8830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8850: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 /* 1st argument
8860: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 to callback */.
8870: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
8880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8890: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
88a0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
88b0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a here */.);../*.
88c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
88d0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
88e0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
88f0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
8900: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
8910: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
8920: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
8930: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
8940: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
8950: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
8960: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
8970: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
8980: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
8990: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 der to indicates
89a0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
89b0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
89c0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
89d0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
89e0: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
89f0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
8a00: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
8a10: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
8a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
8a30: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 ],.** [sqlite3_v
8a40: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
8a50: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 )] [SQLITE_ROLLB
8a60: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 ACK | result cod
8a70: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 es]..*/.#define
8a80: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
8a90: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
8aa0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
8ab0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
8ac0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
8ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
8ae0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
8af0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
8b00: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
8b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8b20: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
8b30: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
8b40: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
8b50: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
8b60: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
8b70: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
8b80: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
8b90: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
8ba0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
8bb0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
8bc0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
8bd0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
8be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8bf0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
8c00: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
8c10: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
8c20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8c30: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
8c40: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
8c50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
8c60: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
8c70: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
8c80: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
8c90: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
8ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8cb0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
8cc0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
8cd0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
8ce0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
8cf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
8d00: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
8d10: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
8d20: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
8d30: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
8d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
8d50: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
8d60: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
8d70: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
8d80: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
8d90: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
8da0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
8db0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
8dc0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
8dd0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
8de0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
8df0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 12 /* Unknown
8e00: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 opcode in sqlite
8e10: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
8e20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8e30: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 TE_FULL 1
8e40: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 3 /* Insertion
8e50: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 failed because
8e60: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c database is full
8e70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8e80: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 TE_CANTOPEN 1
8e90: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 4 /* Unable to
8ea0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
8eb0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
8ec0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 ne SQLITE_PROTOC
8ed0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 OL 15 /* Da
8ee0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
8ef0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
8f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
8f10: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
8f20: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
8f30: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
8f40: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
8f50: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
8f60: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
8f70: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
8f80: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
8f90: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
8fa0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
8fb0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
8fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
8fd0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
8fe0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
8ff0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
9000: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
9010: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
9020: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
9030: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
9040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9050: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
9060: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
9070: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
9080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
9090: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
90a0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
90b0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
90c0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
90d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
90e0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
90f0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
9100: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
9110: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
9120: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
9130: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
9140: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
9150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
9160: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
9170: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
9180: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
9190: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
91a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
91b0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
91c0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
91d0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
91e0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
91f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
9200: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
9210: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
9220: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
9230: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
9240: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
9250: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
9260: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
9270: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
9280: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
9290: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
92a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
92b0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
92c0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
92d0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
92e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
92f0: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a error codes}.**
9300: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
9310: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9320: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 } {extended resu
9330: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 lt codes}.**.**
9340: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 In its default c
9350: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 onfiguration, SQ
9360: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 Lite API routine
9370: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 s return one of
9380: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 26 integer.** [S
9390: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c QLITE_OK | resul
93a0: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 t codes]. Howev
93b0: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 er, experience h
93c0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 as shown that ma
93d0: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 ny of.** these r
93e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 esult codes are
93f0: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e too coarse-grain
9400: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 ed. They do not
9410: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d provide as.** m
9420: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 uch information
9430: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 about problems a
9440: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 s programmers mi
9450: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e ght like. In an
9460: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 effort to.** ad
9470: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 dress this, newe
9480: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
9490: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e Lite (version 3.
94a0: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 3.8 and later) i
94b0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 nclude.** suppor
94c0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c t for additional
94d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 result codes th
94e0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 at provide more
94f0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 detailed informa
9500: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 tion.** about er
9510: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 rors. The extend
9520: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
9530: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 are enabled or d
9540: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 isabled.** on a
9550: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e per database con
9560: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 nection basis us
9570: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
9580: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
9590: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 ult_codes()] API
95a0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 ..**.** Some of
95b0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 the available ex
95c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
95d0: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 des are listed h
95e0: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 ere..** One may
95f0: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 expect the numbe
9600: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 r of extended re
9610: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 sult codes will
9620: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 be expand.** ove
9630: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 r time. Softwar
9640: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 e that uses exte
9650: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9660: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a s should expect.
9670: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 ** to see new re
9680: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 sult codes in fu
9690: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
96a0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
96b0: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 he SQLITE_OK res
96c0: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 ult code will ne
96d0: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e ver be extended.
96e0: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 It will always
96f0: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a .** be exactly z
9700: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ero..*/.#define
9710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
9720: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 D (
9730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
9740: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
9750: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 QLITE_IOERR_SHOR
9760: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 T_READ (S
9770: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
9780: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
9790: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 LITE_IOERR_WRITE
97a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
97b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c LITE_IOERR | (3<
97c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
97d0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 ITE_IOERR_FSYNC
97e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
97f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c ITE_IOERR | (4<<
9800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
9810: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 TE_IOERR_DIR_FSY
9820: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 NC (SQLI
9830: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 TE_IOERR | (5<<8
9840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
9850: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 E_IOERR_TRUNCATE
9860: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
9870: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 E_IOERR | (6<<8)
9880: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
9890: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 _IOERR_FSTAT
98a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
98b0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 _IOERR | (7<<8))
98c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
98d0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 IOERR_UNLOCK
98e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
98f0: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a IOERR | (8<<8)).
9900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
9910: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 OERR_RDLOCK
9920: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
9930: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 OERR | (9<<8)).#
9940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9950: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ERR_DELETE
9960: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9970: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 ERR | (10<<8)).#
9980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9990: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 ERR_BLOCKED
99a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
99b0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 ERR | (11<<8)).#
99c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
99d0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ERR_NOMEM
99e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
99f0: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 ERR | (12<<8)).#
9a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9a10: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 ERR_ACCESS
9a20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9a30: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 ERR | (13<<8)).#
9a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9a50: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 ERR_CHECKRESERVE
9a60: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f DLOCK (SQLITE_IO
9a70: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 ERR | (14<<8)).#
9a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9a90: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 ERR_LOCK
9aa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9ab0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 ERR | (15<<8)).#
9ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9ad0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 ERR_CLOSE
9ae0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9af0: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 ERR | (16<<8)).#
9b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9b10: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 ERR_DIR_CLOSE
9b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9b30: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 ERR | (17<<8)).#
9b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9b50: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 ERR_SHMOPEN
9b60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9b70: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 ERR | (18<<8)).#
9b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9b90: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 ERR_SHMSIZE
9ba0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9bb0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 ERR | (19<<8)).#
9bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9bd0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 ERR_SHMLOCK
9be0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9bf0: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 ERR | (20<<8)).#
9c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9c10: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 ERR_SHMMAP
9c20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9c30: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 ERR | (21<<8)).#
9c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9c50: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 ERR_SEEK
9c60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9c70: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 ERR | (22<<8)).#
9c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
9c90: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 CKED_SHAREDCACHE
9ca0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f (SQLITE_LO
9cb0: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a CKED | (1<<8)).
9cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
9cd0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 USY_RECOVERY
9ce0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 (SQLITE_B
9cf0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 USY | (1<<8))
9d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9d10: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 CANTOPEN_NOTEMPD
9d20: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f IR (SQLITE_
9d30: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 CANTOPEN | (1<<8
9d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
9d50: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 E_CORRUPT_VTAB
9d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
9d70: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c E_CORRUPT | (1<<
9d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
9d90: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f TE_READONLY_RECO
9da0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 VERY (SQLI
9db0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 TE_READONLY | (1
9dc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
9dd0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 LITE_READONLY_CA
9de0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 NTLOCK (SQ
9df0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
9e00: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (2<<8))../*.** C
9e10: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
9e20: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
9e30: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
9e40: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
9e50: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
9e60: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
9e70: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
9e80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
9e90: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
9ea0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
9eb0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
9ec0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
9ed0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a .xOpen] method..
9ee0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9ef0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 E_OPEN_READONLY
9f00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
9f10: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 01 /* Ok for sq
9f20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
9f30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9f40: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
9f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
9f60: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 02 /* Ok for sq
9f70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
9f80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9f90: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 E_OPEN_CREATE
9fa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
9fb0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 04 /* Ok for sq
9fc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
9fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9fe0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
9ff0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 LOSE 0x000000
a000: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 08 /* VFS only
a010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a020: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
a030: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
a040: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 10 /* VFS only
a050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a060: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 E_OPEN_AUTOPROXY
a070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
a080: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 20 /* VFS only
a090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a0a0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 E_OPEN_URI
a0b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
a0c0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 40 /* Ok for sq
a0d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
a0e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a0f0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 E_OPEN_MAIN_DB
a100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
a110: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a130: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 E_OPEN_TEMP_DB
a140: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
a150: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a160: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a170: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
a180: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 _DB 0x000004
a190: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a1a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a1b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
a1c0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 NAL 0x000008
a1d0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a1e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a1f0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
a200: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 NAL 0x000010
a210: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a230: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
a240: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 L 0x000020
a250: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a260: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a270: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
a280: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 URNAL 0x000040
a290: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a2a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a2b0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 E_OPEN_NOMUTEX
a2c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 0x000080
a2d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
a2e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
a2f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a300: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
a310: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 0x000100
a320: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
a330: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
a340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a350: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
a360: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 HE 0x000200
a370: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
a380: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
a390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a3a0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
a3b0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 CHE 0x000400
a3c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
a3d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
a3e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a3f0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 E_OPEN_WAL
a400: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 0x000800
a410: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
a420: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a */../* Reserved:
a430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
a440: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 0x00F00
a450: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 000 */../*.** CA
a460: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
a470: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a haracteristics.*
a480: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
a490: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a4a0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
a4b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
a4c0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
a4d0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
a4e0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
a4f0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a r of the these.*
a500: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
a510: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
a520: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
a530: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
a540: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
a550: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
a560: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
a570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
a580: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
a590: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
a5a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
a5b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
a5c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
a5d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
a5e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
a5f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
a600: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
a610: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
a620: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
a630: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
a640: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
a650: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
a660: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
a670: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
a680: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
a690: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
a6a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
a6b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
a6c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
a6d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
a6e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
a6f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
a700: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
a710: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
a720: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
a730: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
a740: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
a750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
a760: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
a770: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
a780: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
a790: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
a7a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
a7b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
a7c0: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e ite()..*/.#defin
a7d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
a7e0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 TOMIC
a7f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
a800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a810: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
a820: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
a830: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
a840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a850: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 MIC1K
a860: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 0x00000004.#
a870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
a880: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 CAP_ATOMIC2K
a890: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
a8a0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 00008.#define SQ
a8b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
a8c0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C4K
a8d0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
a8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
a8f0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
a900: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
a910: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 020.#define SQLI
a920: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
a930: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 6K
a940: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
a950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
a960: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
a970: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
a980: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
a990: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
a9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
a9b0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
a9c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
a9d0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 FE_APPEND
a9e0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
a9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
aa00: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
aa20: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
aa30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
aa40: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
aa50: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f N 0x00000800../
aa60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
aa70: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
aa80: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
aa90: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
aaa0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
aab0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
aac0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
aad0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
aae0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
aaf0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
ab00: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
ab10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
ab20: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
ab30: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
ab40: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
ab50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
ab60: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
ab70: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
ab80: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
ab90: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
aba0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
abb0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
abc0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
abd0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
abe0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
abf0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
ac00: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
ac10: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
ac20: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
ac30: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
ac40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
ac50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
ac60: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
ac70: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
ac80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
ac90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
aca0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
acb0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
acc0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
acd0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
ace0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
acf0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
ad00: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
ad10: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
ad20: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
ad30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
ad40: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
ad50: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
ad60: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
ad70: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
ad80: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
ad90: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
ada0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
adb0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
adc0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
add0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
ade0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
adf0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
ae00: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
ae10: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
ae20: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
ae30: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
ae40: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
ae50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
ae60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
ae70: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
ae80: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
ae90: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
aea0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
aeb0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
aec0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
aed0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
aee0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
aef0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
af00: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
af10: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
af20: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
af30: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
af40: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
af50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
af60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
af70: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
af80: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
af90: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
afa0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
afb0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
afc0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
afd0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
afe0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
aff0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
b000: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
b010: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
b020: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
b030: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
b040: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
b050: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
b060: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
b070: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
b080: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
b090: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
b0a0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
b0b0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
b0c0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
b0d0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
b0e0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
b0f0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
b100: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
b110: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
b120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
b130: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
b140: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
b150: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
b160: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
b170: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
b180: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
b190: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
b1a0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
b1b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
b1c0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
b1d0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
b1e0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
b1f0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
b200: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
b210: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
b220: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
b230: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
b240: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
b250: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
b260: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
b270: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
b280: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
b290: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
b2a0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
b2b0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
b2c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
b2d0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
b2e0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
b2f0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
b300: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
b310: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
b320: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
b330: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
b340: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
b350: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
b360: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
b370: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
b380: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
b390: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
b3a0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
b3b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
b3c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
b3d0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
b3e0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
b3f0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
b400: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
b410: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
b420: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
b430: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
b440: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
b450: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
b460: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
b470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
b480: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
b490: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
b4a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
b4b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
b4c0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
b4d0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
b4e0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
b4f0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
b500: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
b510: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
b520: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
b530: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
b540: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
b550: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
b560: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
b570: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
b580: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
b590: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
b5a0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
b5b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
b5c0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
b5d0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
b5e0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
b5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
b600: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
b610: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
b620: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
b630: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
b640: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
b650: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
b660: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
b670: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
b680: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
b690: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
b6a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
b6b0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
b6c0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
b6d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
b6e0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
b6f0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
b700: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
b710: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
b720: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
b730: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
b740: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
b750: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
b760: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
b770: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
b780: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
b790: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
b7a0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
b7b0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
b7c0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
b7d0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
b7e0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
b7f0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
b800: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
b810: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
b820: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
b830: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
b840: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
b850: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
b860: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
b870: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
b880: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
b890: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
b8a0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
b8b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
b8c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
b8d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
b8e0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
b8f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
b900: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
b910: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
b920: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
b930: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
b940: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
b950: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
b960: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
b970: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
b980: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
b990: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
b9a0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
b9b0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
b9c0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
b9d0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
b9e0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
b9f0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
ba00: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
ba10: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
ba20: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
ba30: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
ba40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
ba50: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
ba60: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
ba70: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
ba80: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
ba90: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
baa0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
bab0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
bac0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
bad0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
bae0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
baf0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
bb00: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
bb10: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
bb20: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
bb30: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
bb40: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
bb50: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
bb60: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
bb70: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
bb80: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
bb90: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
bba0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
bbb0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
bbc0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
bbd0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
bbe0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
bbf0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
bc00: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
bc10: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
bc20: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
bc30: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
bc40: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
bc50: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
bc60: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
bc70: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
bc80: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
bc90: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
bca0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
bcb0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
bcc0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
bcd0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
bce0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f e..** A [SQLITE_
bcf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
bd00: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 | list of opcode
bd10: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 s] less than 100
bd20: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a is available..*
bd30: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
bd40: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 hat define a cus
bd50: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c tom xFileControl
bd60: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 method should u
bd70: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 se opcodes.** gr
bd80: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 eater than 100 t
bd90: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 o avoid conflict
bda0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e s. VFS implemen
bdb0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a tations should.*
bdc0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
bdd0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 _NOTFOUND] for f
bde0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
bdf0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f des that they do
be00: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a not.** recogniz
be10: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 e..**.** The xSe
be20: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f ctorSize() metho
be30: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 d returns the se
be40: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 ctor size of the
be50: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
be60: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 underlies the fi
be70: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 le. The sector
be80: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d size is the.** m
be90: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 inimum write tha
bea0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d t can be perform
beb0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 ed without distu
bec0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 rbing.** other b
bed0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
bee0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 . The xDeviceCh
bef0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a aracteristics().
bf00: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
bf10: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 s a bit vector d
bf20: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 escribing behavi
bf30: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e ors of the.** un
bf40: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a derlying device:
bf50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
bf60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
bf70: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 P_ATOMIC].** <li
bf80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
bf90: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c ATOMIC512].** <l
bfa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
bfb0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC1K].** <l
bfc0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
bfd0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC2K].** <l
bfe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
bff0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC4K].** <l
c000: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c010: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC8K].** <l
c020: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c030: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c _ATOMIC16K].** <
c040: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
c050: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 P_ATOMIC32K].**
c060: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
c070: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a AP_ATOMIC64K].**
c080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c090: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d CAP_SAFE_APPEND]
c0a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c0b0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
c0c0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a L].** </ul>.**.*
c0d0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 * The SQLITE_IOC
c0e0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 AP_ATOMIC proper
c0f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c ty means that al
c100: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 l writes of.** a
c110: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d ny size are atom
c120: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
c130: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 IOCAP_ATOMICnnn
c140: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 values.** mean t
c150: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c hat writes of bl
c160: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e ocks that are nn
c170: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 n bytes in size
c180: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e and.** are align
c190: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 ed to an address
c1a0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 which is an int
c1b0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 eger multiple of
c1c0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d .** nnn are atom
c1d0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
c1e0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
c1f0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a D value means.**
c200: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 that when data
c210: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 is appended to a
c220: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 file, the data
c230: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 is appended.** f
c240: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 irst then the si
c250: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 ze of the file i
c260: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 s extended, neve
c270: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 r the other.** w
c280: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 ay around. The
c290: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
c2a0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 UENTIAL property
c2b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 means that.** i
c2c0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 nformation is wr
c2d0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e itten to disk in
c2e0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 the same order
c2f0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 as calls.** to x
c300: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 Write()..**.** I
c310: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e f xRead() return
c320: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 s SQLITE_IOERR_S
c330: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 HORT_READ it mus
c340: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 t also fill.** i
c350: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 n the unread por
c360: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 tions of the buf
c370: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 fer with zeros.
c380: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 A VFS that.** f
c390: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c ails to zero-fil
c3a0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 l short reads mi
c3b0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b ght seem to work
c3c0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
c3d0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 ailure to zero-f
c3e0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
c3f0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 will eventually
c400: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 lead to.** datab
c410: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a ase corruption..
c420: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
c430: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
c440: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f hods sqlite3_io_
c450: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
c460: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
c470: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 ds {. int iVers
c480: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c ion;. int (*xCl
c490: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ose)(sqlite3_fil
c4a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 e*);. int (*xRe
c4b0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ad)(sqlite3_file
c4c0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 *, void*, int iA
c4d0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
c4e0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
c4f0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 (*xWrite)(sqlite
c500: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 3_file*, const v
c510: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
c520: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
c530: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 fst);. int (*xT
c540: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 runcate)(sqlite3
c550: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
c560: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 int64 size);. i
c570: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
c580: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 te3_file*, int f
c590: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
c5a0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 FileSize)(sqlite
c5b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
c5c0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a _int64 *pSize);.
c5d0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 int (*xLock)(s
c5e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
c5f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c t);. int (*xUnl
c600: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
c610: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
c620: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 (*xCheckReserved
c630: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
c640: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 le*, int *pResOu
c650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c t);. int (*xFil
c660: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 eControl)(sqlite
c670: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 3_file*, int op,
c680: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 void *pArg);.
c690: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
c6a0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
c6b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
c6c0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
c6d0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
c6e0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 );. /* Methods
c6f0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 above are valid
c700: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f for version 1 */
c710: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 . int (*xShmMap
c720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
c730: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 int iPg, int pg
c740: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f sz, int, void vo
c750: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 latile**);. int
c760: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c (*xShmLock)(sql
c770: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
c780: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 offset, int n, i
c790: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 nt flags);. voi
c7a0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 d (*xShmBarrier)
c7b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
c7c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d . int (*xShmUnm
c7d0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
c7e0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 *, int deleteFla
c7f0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 g);. /* Methods
c800: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
c810: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a for version 2 *
c820: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 /. /* Additiona
c830: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
c840: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
c850: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
c860: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
c870: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
c880: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
c890: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
c8a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
c8b0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
c8c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
c8d0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
c8e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
c8f0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
c900: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
c910: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
c920: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
c930: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c940: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
c950: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
c960: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
c970: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
c980: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
c990: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
c9a0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 write the curre
c9b0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 nt state of.** t
c9c0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 he lock (one of
c9d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
c9e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b E], [SQLITE_LOCK
c9f0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 _SHARED],.** [SQ
ca00: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
ca10: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ED], [SQLITE_LOC
ca20: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b K_PENDING], or [
ca30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
ca40: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 USIVE]).** into
ca50: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 an integer that
ca60: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
ca70: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 t points to. Thi
ca80: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 s capability.**
ca90: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 is used during t
caa0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 esting and only
cab0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 needs to be supp
cac0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 orted when SQLIT
cad0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 E_TEST.** is def
cae0: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ined..**.** The
caf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
cb00: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
cb10: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
cb20: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
cb30: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
cb40: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
cb50: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
cb60: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
cb70: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
cb80: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
cb90: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
cba0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
cbb0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
cbc0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
cbd0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
cbe0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
cbf0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
cc00: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
cc10: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
cc20: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
cc30: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
cc40: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
cc50: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
cc60: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
cc70: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
cc80: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
cc90: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
cca0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
ccb0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
ccc0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
ccd0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
cce0: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
ccf0: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
cd00: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
cd10: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
cd20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
cd30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
cd40: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
cd50: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
cd60: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
cd70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
cd80: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
cd90: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
cda0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
cdb0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
cdc0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
cdd0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
cde0: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
cdf0: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
ce00: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
ce10: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
ce20: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
ce30: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
ce40: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
ce50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
ce60: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
ce70: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
ce80: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
ce90: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
cea0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
ceb0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
cec0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
ced0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
cee0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
cef0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
cf00: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
cf10: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
cf20: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
cf30: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ation..**.** ^(T
cf40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
cf50: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f _SYNC_OMITTED] o
cf60: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
cf70: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
cf80: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 .** SQLite and s
cf90: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 ent to all VFSes
cfa0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 in place of a c
cfb0: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 all to the xSync
cfc0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 method.** when
cfd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
cfe0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 nection has [PRA
cff0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d GMA synchronous]
d000: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a set to OFF.)^.*
d010: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a * Some specializ
d020: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 ed VFSes need th
d030: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 is signal in ord
d040: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f er to operate co
d050: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 rrectly.** when
d060: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
d070: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e ous | PRAGMA syn
d080: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 chronous=OFF] is
d090: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a set, but most .
d0a0: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 ** VFSes do not
d0b0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c need this signal
d0c0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 and should sile
d0d0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
d0e0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c opcode..** Appl
d0f0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
d100: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 not call [sqlite
d110: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
d120: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f ] with this.** o
d130: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
d140: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 o may disrupt th
d150: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
d160: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
d170: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 FSes.** that do
d180: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
d190: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
d1a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
d1b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
d1c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
d1d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
d1e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
d1f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
d200: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
d210: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
d220: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
d230: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
d240: 77 6f 72 6b 20 74 6f 20 70 72 6f 76 69 64 65 20 work to provide
d250: 72 6f 62 75 73 74 6e 65 73 73 20 61 67 61 69 6e robustness again
d260: 73 74 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 st.** anti-virus
d270: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 programs. By d
d280: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 efault, the wind
d290: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 ows VFS will ret
d2a0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a ry file read,.**
d2b0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 file write, and
d2c0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 file delete ope
d2d0: 72 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 rtions up to 10
d2e0: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 times, with a de
d2f0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c lay.** of 25 mil
d300: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 liseconds before
d310: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 the first retry
d320: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 and with the de
d330: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a lay increasing.*
d340: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e * by an addition
d350: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e al 25 millisecon
d360: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 ds with each sub
d370: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 sequent retry.
d380: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 This.** opcode a
d390: 6c 6c 6f 77 73 20 74 68 6f 73 65 20 74 6f 20 76 llows those to v
d3a0: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 alues (10 retrie
d3b0: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 s and 25 millise
d3c0: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a conds of delay).
d3d0: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 ** to be adjuste
d3e0: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 d. The values a
d3f0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 re changed for a
d400: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ll database conn
d410: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 ections.** withi
d420: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 n the same proce
d430: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e ss. The argumen
d440: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
d450: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 o an array of tw
d460: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 o.** integers wh
d470: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e ere the first in
d480: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 teger i the new
d490: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 retry count and
d4a0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e the second.** in
d4b0: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c teger is the del
d4c0: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 ay. If either i
d4d0: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 nteger is negati
d4e0: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 ve, then the set
d4f0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 ting.** is not c
d500: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 hanged but inste
d510: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ad the prior val
d520: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 ue of that setti
d530: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a ng is written.**
d540: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 into the array
d550: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 entry, allowing
d560: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 the current retr
d570: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 y settings to be
d580: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 .** interrogated
d590: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 . The zDbName p
d5a0: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f arameter is igno
d5b0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
d5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
d5d0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 RSIST_WAL] opcod
d5e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
d5f0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
d600: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c persistent [WAL
d610: 20 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c | Write AHead L
d620: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 og] setting. By
d630: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 default, the au
d640: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 xiliary.** write
d650: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 ahead log and s
d660: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
d670: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e es used for tran
d680: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a saction control.
d690: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ** are automatic
d6a0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 ally deleted whe
d6b0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e n the latest con
d6c0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 nection to the d
d6d0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 atabase.** close
d6e0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 s. Setting pers
d6f0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
d700: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c causes those fil
d710: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 es to persist af
d720: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 ter.** close. P
d730: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 ersisting the fi
d740: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 les is useful wh
d750: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 en other process
d760: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a es that do not.*
d770: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 * have write per
d780: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 mission on the d
d790: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e irectory contain
d7a0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
d7b0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f file want.** to
d7c0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 read the databa
d7d0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 se file, as the
d7e0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d WAL and shared m
d7f0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 emory files must
d800: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 exist.** in ord
d810: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 er for the datab
d820: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 ase to be readab
d830: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 le. The fourth
d840: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
d850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
d860: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
d870: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
d880: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
d890: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
d8a0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
d8b0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 to disable pers
d8c0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
d8d0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 or 1 to enable p
d8e0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c ersistent.** WAL
d8f0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
d900: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
d910: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
d920: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
d930: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 rrent.** WAL per
d940: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 sistence setting
d950: 2e 0a 2a 2a 20 0a 2a 2f 0a 23 64 65 66 69 6e 65 ..** .*/.#define
d960: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
d970: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 CKSTATE 1
d980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d990: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
d9a0: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 E 2.#define
d9b0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b SQLITE_SET_LOCK
d9c0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 PROXYFILE 3
d9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d9e0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
d9f0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
da00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 SQLITE_FCNTL_SI
da10: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35 ZE_HINT 5
da20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
da30: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
da40: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
da50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 SQLITE_FCNTL_FI
da60: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 37 LE_POINTER 7
da70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
da80: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 FCNTL_SYNC_OMITT
da90: 45 44 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 ED 8.#define
daa0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
dab0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 39 N32_AV_RETRY 9
dac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dad0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
dae0: 4c 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 L 10../*.**
daf0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
db00: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 Handle.**.** The
db10: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
db20: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
db30: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
db40: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
db50: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
db60: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
db70: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
db80: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
db90: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
dba0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
dbb0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
dbc0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
dbd0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
dbe0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
dbf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
dc00: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
dc10: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
dc20: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
dc30: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
dc40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
dc50: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
dc60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
dc70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
dc80: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a OS Interface Obj
dc90: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ect.**.** An ins
dca0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
dcb0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
dcc0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
dcd0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
dce0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
dcf0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
dd00: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
dd10: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
dd20: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
dd30: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
dd40: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
dd50: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 l file system".
dd60: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 See.** the [VFS
dd70: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 | VFS documenta
dd80: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 tion] for furthe
dd90: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a r information..*
dda0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
ddb0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
ddc0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
ddd0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
dde0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
ddf0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
de00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
de10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
de20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
de30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
de40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
de50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
de60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
de70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
de80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
de90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
dea0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
deb0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
dec0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
ded0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
dee0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
def0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
df00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
df10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
df20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
df30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
df40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
df50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
df60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
df70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
df80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
df90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
dfa0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
dfb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
dfc0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
dfd0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
dfe0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
dff0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
e000: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
e010: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
e020: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
e030: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
e040: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
e050: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
e060: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
e070: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
e080: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
e090: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
e0a0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
e0b0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
e0c0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
e0d0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
e0e0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
e0f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
e100: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
e110: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
e120: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
e130: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
e140: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
e150: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
e160: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
e170: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
e180: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
e190: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
e1a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
e1b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
e1c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
e1d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
e1e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
e1f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
e200: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
e210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
e220: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
e230: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
e240: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
e250: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
e260: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
e270: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
e280: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
e290: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
e2a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
e2b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
e2c0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
e2d0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 xOpen]].** ^SQLi
e2e0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
e2f0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
e300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
e310: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
e320: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
e330: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
e340: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
e350: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 Pathname() with
e360: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 an optional suff
e370: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 ix added..** ^If
e380: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 a suffix is add
e390: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e ed to the zFilen
e3a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 ame parameter, i
e3b0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 t will.** consis
e3c0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d t of a single "-
e3d0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c " character foll
e3e0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 owed by no more
e3f0: 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61 than.** 10 alpha
e400: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 numeric and/or "
e410: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -" characters..*
e420: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 * ^SQLite furthe
e430: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 r guarantees tha
e440: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 t.** the string
e450: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e will be valid an
e460: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 d unchanged unti
e470: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a l xClose() is.**
e480: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 called. Because
e490: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 of the previous
e4a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 sentence,.** th
e4b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
e4c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 can safely stor
e4d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 e a pointer to t
e4e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 he.** filename i
e4f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 f it needs to re
e500: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e member the filen
e510: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ame for some rea
e520: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a son..** If the z
e530: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
e540: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 er to xOpen is a
e550: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
e560: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 en xOpen.** must
e570: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 invent its own
e580: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 temporary name f
e590: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 or the file. ^W
e5a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 henever the .**
e5b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 xFilename parame
e5c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 ter is NULL it w
e5d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 ill also be the
e5e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a case that the.**
e5f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
e600: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 will include [S
e610: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
e620: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a EONCLOSE]..**.**
e630: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
e640: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
e650: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
e660: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
e670: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
e680: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
e690: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
e6a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
e6b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
e6c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
e6d0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
e6e0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
e6f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
e700: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
e710: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
e720: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f .** If xOpen() o
e730: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 pens a file read
e740: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 -only then it se
e750: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f ts *pOutFlags to
e760: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c .** include [SQL
e770: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
e780: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 Y]. Other bits
e790: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 in *pOutFlags ma
e7a0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 y be set..**.**
e7b0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^(SQLite will al
e7c0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
e7d0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
e7e0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
e7f0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
e800: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
e810: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
e820: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e830: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
e840: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
e850: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
e860: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
e870: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e880: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
e890: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e8a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
e8b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
e8c0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
e8d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
e8e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
e8f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
e900: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
e910: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
e920: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
e930: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e EN_WAL].** </ul>
e940: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c )^.**.** The fil
e950: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 e I/O implementa
e960: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 tion can use the
e970: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 object type fla
e980: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 gs to.** change
e990: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
e9a0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
e9b0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
e9c0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
e9d0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
e9e0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
e9f0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
ea00: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 might make.** t
ea10: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 he open of a jou
ea20: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f rnal file a no-o
ea30: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 p. Writes to th
ea40: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 is journal would
ea50: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f .** also be no-o
ea60: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 ps, and any atte
ea70: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 mpt to read the
ea80: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 journal would re
ea90: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 turn.** SQLITE_I
eaa0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
eab0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
eac0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
ead0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 t a database.**
eae0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 file will be doi
eaf0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 ng page-aligned
eb00: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 sector reads and
eb10: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e writes in a ran
eb20: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 dom.** order and
eb30: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 set up its I/O
eb40: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 subsystem accord
eb50: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ingly..**.** SQL
eb60: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 ite might also a
eb70: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
eb80: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
eb90: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
eba0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
ebb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
ebc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
ebd0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
ebe0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
ebf0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
ec00: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
ec10: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
ec20: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
ec30: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a file should be.*
ec40: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 * deleted when i
ec50: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 t is closed. ^T
ec60: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
ec70: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
ec80: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f * will be set fo
ec90: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 r TEMP databases
eca0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e and their journ
ecb0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a als, transient.*
ecc0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 * databases, and
ecd0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
ece0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
ecf0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
ed00: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
ed10: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
ed20: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
ed30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
ed40: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
ed50: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
ed60: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
ed70: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
ed80: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
ed90: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
eda0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
edb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
edc0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
edd0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
ede0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
edf0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
ee00: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
ee10: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
ee20: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
ee30: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
ee40: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
ee50: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
ee60: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
ee70: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
ee80: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
ee90: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
eea0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
eeb0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
eec0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 * ^At least szOs
eed0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
eee0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
eef0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
ef00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
ef10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
ef20: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
ef30: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
ef40: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
ef50: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f The xOpen metho
ef60: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 d does not have
ef70: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 to.** allocate t
ef80: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 he structure; it
ef90: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c should just fil
efa0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 l it in. Note t
efb0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e hat.** the xOpen
efc0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 method must set
efd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
efe0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 e.pMethods to ei
eff0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 ther.** a valid
f000: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
f010: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 ods] object or t
f020: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d o NULL. xOpen m
f030: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 ust do.** this e
f040: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 ven if the open
f050: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 fails. SQLite e
f060: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 xpects that the
f070: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
f080: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 thods.** element
f090: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
f0a0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 fter xOpen retur
f0b0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ns regardless of
f0c0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 the success.**
f0d0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
f0e0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a e xOpen call..**
f0f0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
f100: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e s.xAccess]].** ^
f110: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
f120: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
f130: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
f140: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
f150: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
f160: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
f170: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
f180: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
f190: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
f1a0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
f1b0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
f1c0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
f1d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
f1e0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
f1f0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
f200: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
f210: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
f220: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
f230: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 .**.** ^SQLite w
f240: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
f250: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
f260: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 athname+1 bytes
f270: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 for the.** outpu
f280: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 t buffer xFullPa
f290: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 thname. The exa
f2a0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f ct size of the o
f2b0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
f2c0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 is also passed a
f2d0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f s a parameter to
f2e0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 both methods.
f2f0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
f300: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
f310: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
f320: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
f330: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
f340: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
f350: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
f360: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
f370: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
f380: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
f390: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
f3a0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
f3b0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
f3c0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
f3d0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
f3e0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
f3f0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
f400: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 eep(), xCurrentT
f410: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 ime(), and xCurr
f420: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a entTimeInt64().*
f430: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 * interfaces are
f440: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
f450: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
f460: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
f470: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
f480: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
f490: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
f4a0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
f4b0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
f4c0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
f4d0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
f4e0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
f4f0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
f500: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
f510: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
f520: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
f530: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
f540: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
f550: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 obtained..** The
f560: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
f570: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
f580: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
f590: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
f5a0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
f5b0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
f5c0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 iven. ^The xCur
f5d0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
f5e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
f5f0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
f600: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
f610: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 date and time a
f620: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 s.** a floating
f630: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 point value..**
f640: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
f650: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f660: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 returns, as an i
f670: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 nteger, the Juli
f680: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 an.** Day Number
f690: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 multiplied by 8
f6a0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
f6b0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
f6c0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
f6d0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
f6e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
f6f0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
f700: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
f710: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
f720: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
f730: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
f740: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
f750: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
f760: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
f770: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
f780: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
f790: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
f7a0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
f7b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
f7c0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
f7d0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
f7e0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
f7f0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
f800: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
f810: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
f820: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
f830: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
f840: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
f850: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
f860: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
f870: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
f880: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
f890: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
f8a0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
f8b0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
f8c0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
f8d0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
f8e0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
f8f0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
f900: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
f910: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
f920: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
f930: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
f940: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
f950: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
f960: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
f970: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
f980: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
f990: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
f9a0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
f9b0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
f9c0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
f9d0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
f9e0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
f9f0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
fa00: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
fa10: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
fa20: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
fa30: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
fa40: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
fa50: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
fa60: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
fa70: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
fa80: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
fa90: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
faa0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
fab0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
fac0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
fad0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
fae0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
faf0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
fb00: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
fb10: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
fb20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
fb30: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
fb40: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
fb50: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
fb60: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
fb70: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
fb80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
fb90: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
fba0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
fbb0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
fbc0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
fbd0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
fbe0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
fbf0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
fc00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
fc10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
fc20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
fc30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
fc40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
fc50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
fc60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
fc70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
fc80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
fc90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
fca0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
fcb0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
fcc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
fcd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
fce0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
fcf0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
fd00: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
fd10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
fd20: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
fd30: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
fd40: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
fd50: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
fd60: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
fd70: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
fd80: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fd90: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fda0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
fdb0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
fdc0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
fdd0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
fde0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
fdf0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
fe00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
fe10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
fe20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
fe30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
fe40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
fe50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
fe60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
fe70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
fe80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
fe90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
fea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
feb0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
fec0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
fed0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
fee0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
fef0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
ff00: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
ff10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
ff20: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
ff30: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
ff40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
ff50: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
ff60: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
ff70: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
ff80: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
ff90: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
ffa0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
ffb0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
ffc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
ffd0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
ffe0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
fff0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
10000 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
10010 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
10020 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
10030 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
10040 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
10050 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
10060 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
10070 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
10080 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
10090 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
100a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
100b0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
100c0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
100d0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
100e0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
100f0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
10100 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
10110 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
10120 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
10130 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
10140 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
10150 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
10160 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
10170 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
10180 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
10190 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
101a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
101b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
101c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
101d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
101e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
101f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
10200 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
10210 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
10220 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
10230 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
10240 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
10250 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
10260 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
10270 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
10280 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
10290 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
102a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
102b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
102c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
102d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
102e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
102f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
10300 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
10310 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
10320 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
10330 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
10340 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
10350 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
10360 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
10370 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
10380 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
10390 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
103a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
103b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
103c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
103d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
103e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
103f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
10400 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
10410 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
10420 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
10430 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
10440 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
10450 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
10460 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
10470 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
10480 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
10490 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
104a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
104b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
104c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
104d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
104e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
104f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
10500 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
10510 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
10520 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
10530 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
10540 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
10550 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
10560 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
10570 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
10580 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
10590 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
105a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
105b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
105c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
105d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
105e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
105f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
10600 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
10610 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
10620 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
10630 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
10640 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
10650 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
10660 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
10670 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
10680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10690 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
106a0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
106b0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
106c0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
106d0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
106e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
106f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
10700 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
10710 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
10720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10730 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
10740 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
10750 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
10760 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10770 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
10780 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
10790 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
107a0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
107b0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
107c0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
107d0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
107e0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
107f0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
10800 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
10810 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
10820 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
10830 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
10840 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
10850 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
10860 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
10870 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
10880 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
10890 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
108a0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
108b0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
108c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
108d0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
108e0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
108f0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
10900 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
10910 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
10920 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
10930 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
10940 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
10950 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 ven no the corre
10960 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
10970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
10980 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
10990 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
109a0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
109b0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
109c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
109d0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
109e0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
109f0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
10a00 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
10a10 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
10a20 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
10a30 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
10a40 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
10a50 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
10a60 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
10a70 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
10a80 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
10a90 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
10aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
10ab0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
10ac0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
10ad0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
10ae0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
10af0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
10b00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
10b10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
10b20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
10b30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
10b40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
10b50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
10b60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
10b70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
10b80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
10b90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
10ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10bb0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
10bc0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
10bd0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
10be0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
10bf0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
10c00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10c10 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
10c20 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
10c30 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
10c40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
10c50 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
10c60 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
10c70 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
10c80 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
10c90 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
10ca0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
10cb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
10cc0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
10cd0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
10ce0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
10cf0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
10d00 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
10d10 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
10d20 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
10d30 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
10d40 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
10d50 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
10d60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
10d70 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
10d80 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
10d90 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
10da0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
10db0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
10dc0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
10dd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
10de0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
10df0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
10e00 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
10e10 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
10e20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
10e30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
10e40 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
10e50 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
10e60 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
10e70 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
10e80 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
10e90 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
10ea0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
10eb0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
10ec0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
10ed0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
10ee0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
10ef0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
10f00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10f10 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
10f20 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
10f30 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
10f40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
10f50 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
10f60 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
10f70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
10f80 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
10f90 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
10fa0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10fb0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
10fc0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
10fd0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
10fe0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
10ff0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
11000 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
11010 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
11020 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11030 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
11040 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
11050 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
11060 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
11070 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
11080 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
11090 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
110a0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
110b0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
110c0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
110d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
110e0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
110f0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
11100 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
11110 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
11120 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
11130 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
11140 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
11150 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
11160 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
11170 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
11180 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
11190 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
111a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
111b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
111c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
111d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
111e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
111f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
11200 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
11210 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
11220 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
11230 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
11240 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
11250 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
11260 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
11270 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
11280 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
11290 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
112a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
112b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
112c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
112d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
112e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
112f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
11300 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11310 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
11320 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
11330 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
11340 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
11350 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
11360 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
11370 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
11380 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
11390 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
113a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
113b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
113c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
113d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
113e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
113f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
11400 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
11410 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
11420 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
11430 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
11440 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
11450 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
11460 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
11470 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
11480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11490 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
114a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
114b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
114c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
114d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
114e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
114f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
11500 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
11510 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
11520 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
11530 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
11540 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
11550 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
11560 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
11570 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
11580 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
11590 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
115a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
115b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
115d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
115e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
115f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
11600 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
11610 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
11620 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
11630 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
11640 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
11650 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
11660 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
11670 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11680 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
11690 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
116a0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
116b0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
116c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
116d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
116e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
116f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
11700 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
11710 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
11720 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
11730 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
11740 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
11750 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
11760 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
11770 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
11780 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
11790 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
117a0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
117b0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
117c0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
117d0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
117e0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
117f0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
11800 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
11810 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
11820 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
11830 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
11840 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
11850 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
11860 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
11870 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
11880 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
11890 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
118a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
118b0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
118c0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
118d0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
118e0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
118f0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
11900 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
11910 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
11920 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
11930 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
11940 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
11950 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
11960 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
11970 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
11980 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
11990 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
119a0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
119b0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
119c0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
119d0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
119e0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
119f0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
11a00 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
11a10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
11a20 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
11a30 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
11a40 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
11a50 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
11a60 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
11a70 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
11a80 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
11a90 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
11aa0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
11ab0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
11ac0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
11ad0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
11ae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
11af0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
11b00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
11b10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
11b20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
11b30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
11b40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
11b50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
11b60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
11b70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11b80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
11b90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
11ba0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
11bb0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
11bc0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
11bd0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
11be0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 failure..*/.SQLI
11bf0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
11c00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f e3_initialize(vo
11c10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
11c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 int sqlite3_shut
11c30 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 down(void);.SQLI
11c40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
11c50 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 e3_os_init(void)
11c60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
11c70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
11c80 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
11c90 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
11ca0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
11cb0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 ibrary.**.** The
11cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
11cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
11ce0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 sed to make glob
11cf0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e al configuration
11d00 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 .** changes to S
11d10 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
11d20 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f o tune SQLite to
11d30 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
11d40 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 eds of.** the ap
11d50 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
11d60 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
11d70 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 ation is recomme
11d80 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a nded for most.**
11d90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
11da0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e d so this routin
11db0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 e is usually not
11dc0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 necessary. It
11dd0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 is.** provided t
11de0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 o support rare a
11df0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 pplications with
11e00 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a unusual needs..
11e10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
11e20 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
11e30 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 face is not thre
11e40 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 adsafe. The app
11e50 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 lication.** must
11e60 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 insure that no
11e70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
11e80 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f erfaces are invo
11e90 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 ked by other.**
11ea0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 threads while sq
11eb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
11ec0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 s running. Furt
11ed0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 hermore, sqlite3
11ee0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 _config().** may
11ef0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
11f00 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
11f10 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
11f20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
11f30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
11f40 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
11f50 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
11f60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
11f70 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
11f80 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
11f90 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
11fa0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
11fb0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
11fc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
11fd0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
11fe0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
11ff0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
12000 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
12010 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
12020 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
12030 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
12040 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
12050 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
12060 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
12070 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
12080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12090 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
120a0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
120b0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 er.** [configura
120c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
120d0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
120e0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
120f0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
12100 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
12110 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
12120 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
12130 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e ding on the [con
12140 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12150 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
12160 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
12170 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
12180 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
12190 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
121a0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
121b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
121c0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
121d0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
121e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
121f0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
12200 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
12210 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
12220 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
12230 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 code]..*/.SQLITE
12240 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
12250 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
12260 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
12270 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
12280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12290 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
122a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
122b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
122c0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
122d0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
122e0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
122f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
12300 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
12310 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
12320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12330 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
12340 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
12350 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
12360 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12370 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
12380 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
12390 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
123a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
123b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
123c0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
123d0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
123e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
123f0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
12400 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
12410 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
12420 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
12430 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
12440 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
12450 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
12460 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
12470 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
12480 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
12490 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
124a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
124b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
124c0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
124d0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
124e0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
124f0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
12500 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
12510 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 successful..*/.S
12520 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
12530 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
12540 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
12550 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
12560 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
12570 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
12580 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
12590 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
125a0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
125b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
125c0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
125d0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
125e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
125f0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
12600 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
12610 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
12620 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
12630 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
12640 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
12650 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
12660 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
12670 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
12680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12690 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
126a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
126b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
126c0 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
126d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
126e0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
126f0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
12700 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
12710 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
12720 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
12730 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
12740 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
12750 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
12760 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
12770 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
12780 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
12790 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
127a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
127b0 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
127c0 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
127d0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
127e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
127f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
12800 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
12810 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
12820 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
12830 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
12840 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
12850 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
12860 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
12870 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
12880 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
12890 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
128a0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
128b0 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
128c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
128d0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
128e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
128f0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
12900 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
12910 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
12920 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
12930 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
12940 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
12950 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
12960 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
12970 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
12980 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
12990 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
129a0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
129b0 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
129c0 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
129d0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
129e0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
129f0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
12a00 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
12a10 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
12a20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
12a30 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
12a40 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
12a50 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
12a60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
12a70 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
12a80 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
12a90 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
12aa0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
12ab0 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
12ac0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
12ad0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
12ae0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
12af0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
12b00 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
12b10 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
12b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12b30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
12b40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
12b50 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
12b60 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
12b70 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
12b80 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
12b90 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
12ba0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
12bb0 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
12bc0 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
12bd0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
12be0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
12bf0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
12c00 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
12c10 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
12c20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
12c30 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
12c40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
12c50 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
12c60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12c70 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
12c80 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
12c90 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
12ca0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
12cb0 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
12cc0 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
12cd0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
12ce0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
12cf0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
12d00 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
12d10 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
12d20 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
12d30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
12d40 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
12d50 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
12d60 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
12d70 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
12d80 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
12d90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12da0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
12db0 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
12dc0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
12dd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
12de0 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 r. (For example
12df0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
12e00 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
12e10 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
12e20 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
12e30 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
12e40 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
12e50 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
12e60 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
12e70 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
12e80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
12e90 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
12ea0 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
12eb0 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
12ec0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
12ed0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
12ee0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
12ef0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
12f00 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
12f10 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
12f20 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
12f30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
12f40 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
12f50 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
12f60 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
12f70 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
12f80 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
12f90 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
12fa0 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
12fb0 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
12fc0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
12fd0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
12fe0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
12ff0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
13000 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
13010 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
13020 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
13030 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
13040 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
13050 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
13060 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
13070 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
13080 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
13090 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
130a0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
130b0 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
130c0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
130d0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
130e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
130f0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
13100 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
13110 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
13120 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
13130 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
13140 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
13150 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
13160 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
13170 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
13180 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
13190 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
131a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
131b0 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
131c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
131d0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
131e0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
131f0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
13200 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
13210 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13220 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
13230 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
13240 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13250 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
13260 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
13270 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
13280 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
13290 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
132a0 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
132b0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
132c0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
132d0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
132e0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
132f0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
13300 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
13310 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
13320 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
13330 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
13340 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
13350 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
13360 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
13370 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
13380 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
13390 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
133a0 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
133b0 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
133c0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
133d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
133e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
133f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
13400 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
13410 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
13420 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
13430 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
13440 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
13450 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
13460 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
13470 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
13480 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
13490 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
134a0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
134b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
134c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
134d0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on}.**.** These
134e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
134f0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
13500 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
13510 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
13520 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
13530 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
13540 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
13550 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13560 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
13570 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
13580 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
13590 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
135a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
135b0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
135c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
135d0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
135e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
135f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
13600 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
13610 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
13620 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
13630 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
13640 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
13650 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
13660 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
13680 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
13690 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
136a0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
136b0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
136c0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
136d0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
136e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
136f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
13700 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
13710 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAD]] <dt>SQLITE
13720 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
13730 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
13740 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
13750 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
13760 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
13770 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
13780 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
13790 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 e] to Single-thr
137a0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
137b0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
137c0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
137d0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
137e0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
137f0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
13800 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
13810 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
13820 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
13830 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
13840 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
13850 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
13860 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
13870 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
13880 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
13890 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
138a0 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 change the [thre
138b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d ading mode] from
138c0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 its default.**
138d0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d value of Single-
138e0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 thread and so [s
138f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13900 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a will return .**
13910 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
13920 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
13930 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13940 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a _SINGLETHREAD.**
13950 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
13960 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
13970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13980 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 G_MULTITHREAD]]
13990 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
139a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 G_MULTITHREAD</d
139b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
139c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
139d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
139e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
139f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
13a00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d ading mode] to M
13a10 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e ulti-thread. In
13a20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
13a30 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 disables.** mut
13a40 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 exing on [databa
13a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
13a60 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
13a70 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
13a80 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
13a90 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ion is responsib
13aa0 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 le for serializi
13ab0 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 ng access to.**
13ac0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13ad0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
13ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
13af0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 . But other mut
13b00 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
13b10 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 led so that SQLi
13b20 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 te will be safe
13b30 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 to use in a mult
13b40 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e i-threaded.** en
13b50 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e vironment as lon
13b60 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 g as no two thre
13b70 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ads attempt to u
13b80 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b se the same.** [
13b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13ba0 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 ion] at the same
13bb0 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 time. ^If SQLi
13bc0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
13bd0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
13be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
13bf0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
13c00 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
13c10 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
13c20 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
13c30 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d ble to set the M
13c40 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
13c50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
13c60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
13c70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
13c80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
13c90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
13ca0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
13cb0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
13cc0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
13cd0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
13ce0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
13cf0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 IG_SERIALIZED]]
13d00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13d10 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
13d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
13d30 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
13d40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
13d50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
13d60 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
13d70 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
13d80 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
13d90 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
13da0 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
13db0 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
13dc0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
13dd0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
13de0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
13df0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
13e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
13e10 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
13e20 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
13e30 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
13e40 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
13e50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
13e60 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
13e70 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
13e80 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
13e90 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
13ea0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
13eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13ec0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
13ed0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
13ee0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
13ef0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
13f00 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
13f10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
13f20 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
13f30 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
13f40 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
13f50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
13f60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
13f70 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
13f80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
13f90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
13fa0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
13fb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
13fc0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
13fd0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
13fe0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
13ff0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
14000 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
14010 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
14020 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
14030 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
14040 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
14050 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
14060 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
14070 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
14080 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14090 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
140a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
140b0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
140c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
140d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
140e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
140f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
14100 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
14110 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
14120 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
14130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14140 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
14150 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
14160 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
14170 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
14180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14190 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
141a0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
141b0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
141c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
141d0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
141e0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
141f0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
14200 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
14210 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
14220 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
14230 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
14240 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
14250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
14260 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
14270 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
14280 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14290 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e GETMALLOC]] <dt>
142a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
142b0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
142c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
142d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
142e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
142f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
14300 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
14310 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
14320 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
14330 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
14340 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
14350 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
14360 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
14370 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
14380 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
14390 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
143a0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
143b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
143c0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
143d0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
143e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
143f0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
14400 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 er that simulati
14410 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ons memory alloc
14420 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 ation failure or
14430 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 .** tracks memor
14440 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 y usage, for exa
14450 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a mple. </dd>.**.*
14460 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14470 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 G_MEMSTATUS]] <d
14480 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14490 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
144a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
144b0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
144c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
144d0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 e int, interpret
144e0 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c ed as a .** bool
144f0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
14500 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
14510 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
14520 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14530 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 on .** statistic
14540 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
14550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
14560 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
14570 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c led, the .** fol
14580 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
14590 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
145a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
145b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
145c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
145d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
145e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
145f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
14600 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
14610 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
14620 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
14630 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
14640 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f tatus()].** </
14650 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
14660 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
14670 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
14680 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
14690 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
146a0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
146b0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
146c0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
146d0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
146e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
146f0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
14700 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
14710 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
14720 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14730 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
14740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
14750 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
14760 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
14770 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
14780 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
14790 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
147a0 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 n use for.** scr
147b0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 atch memory. Th
147c0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
147d0 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e guments: A poin
147e0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
147f0 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
14800 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
14810 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c h the scratch al
14820 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
14830 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
14840 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
14850 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
14860 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
14870 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
14880 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
14890 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 ations (N). The
148a0 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 sz.** argument
148b0 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 must be a multip
148c0 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 le of 16..** The
148d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
148e0 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 must be a pointe
148f0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 r to an 8-byte a
14900 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a ligned buffer.**
14910 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
14920 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
14930 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
14940 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 ll use no more t
14950 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 han two scratch
14960 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
14970 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f ad. So.** N sho
14980 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 uld be set to tw
14990 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 ice the expected
149a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
149b0 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e of threads..** ^
149c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
149d0 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 r require a scra
149e0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
149f0 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a is more than 6.*
14a00 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 * times the data
14a10 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 base page size.
14a20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
14a30 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
14a40 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d l.** scratch mem
14a50 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ory beyond what
14a60 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
14a70 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
14a80 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a n option, then .
14a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
14aa0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 oc()] will be us
14ab0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
14ac0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c memory needed.<
14ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
14ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
14af0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
14b00 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
14b10 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
14b20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
14b30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
14b40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
14b50 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
14b60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 e for.** the dat
14b70 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 abase page cache
14b80 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c with the defaul
14b90 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
14ba0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a lementation. .*
14bb0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 * This configura
14bc0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 tion should not
14bd0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 be used if an ap
14be0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
14bf0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
14c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
14c10 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
14c20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14c30 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a PCACHE option..*
14c40 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
14c50 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 e arguments to t
14c60 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f his option: A po
14c70 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 inter to 8-byte
14c80 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 aligned.** memor
14c90 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 y, the size of e
14ca0 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 ach page buffer
14cb0 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 (sz), and the nu
14cc0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e mber of pages (N
14cd0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 )..** The sz arg
14ce0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
14cf0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
14d00 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 largest database
14d10 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 page.** (a powe
14d20 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e r of two between
14d30 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 512 and 32768)
14d40 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 plus a little ex
14d50 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tra for each.**
14d60 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
14d70 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 he page header s
14d80 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 ize is 20 to 40
14d90 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 bytes depending
14da0 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 on.** the host a
14db0 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 rchitecture. ^I
14dc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
14dd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
14de0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
14df0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 to make sz a lit
14e00 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 tle too large.
14e10 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
14e20 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
14e30 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
14e40 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
14e50 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
14e60 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 mory..** ^SQLite
14e70 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 will use the me
14e80 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 mory provided by
14e90 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
14ea0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 ent to satisfy i
14eb0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 ts.** memory nee
14ec0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 ds for the first
14ed0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 N pages that it
14ee0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 adds to cache.
14ef0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a ^If additional.
14f00 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 ** page cache me
14f10 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 mory is needed b
14f20 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
14f30 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f ovided by this o
14f40 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 ption, then.** S
14f50 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 QLite goes to [s
14f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
14f70 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f for the additio
14f80 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 nal storage spac
14f90 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 e..** The pointe
14fa0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 r in the first a
14fb0 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 rgument must.**
14fc0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
14fd0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
14fe0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
14ff0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
15000 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 e.** will be und
15010 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a efined.</dd>.**.
15020 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15030 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
15050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15060 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
15070 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
15080 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
15090 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
150a0 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 .** for all of i
150b0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
150c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
150d0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ds beyond those
150e0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
150f0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
15100 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b G_SCRATCH] and [
15110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
15120 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 GECACHE]..** The
15130 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
15140 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 uments: An 8-byt
15150 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
15160 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
15170 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
15180 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
15190 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
151a0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
151b0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
151c0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
151d0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
151e0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
151f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
15200 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
15210 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
15220 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
15230 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
15240 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
15250 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
15260 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
15270 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
15290 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
152a0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
152b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 s not NULL and e
152c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
152d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
152e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
152f0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 LE_MEMSYS5] are
15300 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 defined, then th
15310 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
15320 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
15330 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
15340 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
15350 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
15360 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
15370 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
15380 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
15390 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
153a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
153b0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
153c0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
153d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
153e0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
153f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
15400 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
15410 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
15420 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 t 2^12. Reasonab
15430 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
15440 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
15450 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
15460 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2^5 through 2^8
15470 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
15490 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
154a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 CONFIG_MUTEX</dt
154b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
154c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
154d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
154e0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
154f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
15500 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
15510 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
15520 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
15530 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
15540 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
15550 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
15560 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
15570 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
15580 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 ce.** the mutex
15590 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
155a0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
155b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
155c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f opy of the.** co
155d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
155e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
155f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
15600 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
15610 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
15620 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
15630 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
15640 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
15650 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
15660 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
15670 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
15680 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
15690 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
156a0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
156b0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
156c0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
156d0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
156e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
156f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
15700 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
15710 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
15720 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
15730 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
15740 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
15750 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15760 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
15770 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15780 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
15790 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
157a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
157b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
157c0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
157d0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
157e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
157f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
15800 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
15810 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
15820 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a mutex_methods].*
15830 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
15840 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
15850 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
15860 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
15870 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
15880 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
15890 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
158a0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f fault mutex allo
158b0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
158c0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
158d0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 r used to track
158e0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 mutex usage for
158f0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 performance.** p
15900 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 rofiling or test
15910 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 ing, for example
15920 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 . ^If SQLite i
15930 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
15940 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
15950 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
15960 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
15970 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
15980 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
15990 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
159a0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
159b0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
159c0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
159d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
159e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
159f0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
15a00 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f NFIG_GETMUTEX co
15a10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15a20 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
15a30 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
15a40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
15a60 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c KASIDE]] <dt>SQL
15a70 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
15a80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
15a90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
15aa0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
15ab0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
15ac0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a ne the default.*
15ad0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
15ae0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b ion for the look
15af0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
15b00 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a ocator on each.*
15b10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
15b20 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 ection]. The fi
15b30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
15b40 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
15b50 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
15b60 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
15b70 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
15b80 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
15b90 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
15ba0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
15bb0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 nnection.)^ ^(T
15bc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
15bd0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c the.** <i>defaul
15be0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
15bf0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
15c00 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
15c10 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f SIDE].** verb to
15c20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
15c30 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 fig()] can be us
15c40 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
15c50 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f lookaside.** co
15c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 nfiguration on i
15c70 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 ndividual connec
15c80 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a tions.)^ </dd>.*
15c90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
15ca0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64 NFIG_PCACHE]] <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15cc0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c PCACHE</dt>.** <
15cd0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
15ce0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
15cf0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
15d00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
15d10 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ** an [sqlite3_p
15d20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
15d30 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
15d40 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 ect specifies th
15d50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 e interface.** t
15d60 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
15d70 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
15d80 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 tion.)^ ^SQLite
15d90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
15da0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 the.** object a
15db0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 nd uses it for p
15dc0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
15dd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 allocations.</d
15de0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
15e00 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
15e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
15e20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
15e30 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
15e40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
15e50 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
15e60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
15e70 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
15e80 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
15e90 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 SQLite copies
15ea0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a of the current.*
15eb0 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 * page cache imp
15ec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f lementation into
15ed0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 that object.)^
15ee0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15ef0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d LITE_CONFIG_LOG]
15f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15f10 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 FIG_LOG</dt>.**
15f20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
15f30 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
15f40 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
15f50 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
15f60 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
15f70 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
15f80 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
15f90 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
15fa0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
15fb0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
15fc0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
15fd0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
15fe0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
15ff0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
16000 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
16010 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
16020 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
16030 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
16040 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
16050 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
16060 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
16070 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
16080 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
16090 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
160a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
160b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
160c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
160d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
160e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
160f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
16100 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
16110 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
16120 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
16130 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
16140 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
16150 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
16160 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
16170 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
16180 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
16190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
161a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
161b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
161c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
161d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
161e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
161f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
16200 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
16210 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
16220 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
16230 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
16240 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
16250 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
16260 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
16270 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
16280 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
16290 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
162a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
162b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
162c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
162d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
162e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
162f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
16300 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
16310 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
16320 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
16330 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
16340 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
16350 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
16360 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
16370 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16380 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 URI]] <dt>SQLITE
16390 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c _CONFIG_URI.** <
163a0 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 dd> This option
163b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
163c0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
163d0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f int. If non-zero
163e0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 , then.** URI ha
163f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
16400 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 ly enabled. If t
16410 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
16420 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 zero, then URI h
16430 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c andling.** is gl
16440 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e obally disabled.
16450 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 If URI handling
16460 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 is globally ena
16470 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 bled, all filena
16480 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f mes.** passed to
16490 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
164a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
164b0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
164c0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a _open16()] or.**
164d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
164e0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 rt of [ATTACH] c
164f0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 ommands are inte
16500 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c rpreted as URIs,
16510 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f regardless.** o
16520 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
16530 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
16540 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 N_URI] flag is s
16550 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 et when the data
16560 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
16570 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 on is opened. If
16580 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 it is globally
16590 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 disabled, filena
165a0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 mes are.** only
165b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
165c0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 RIs if the SQLIT
165d0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 E_OPEN_URI flag
165e0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a is set when the.
165f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
16600 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
16610 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 . By default, UR
16620 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
16630 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c obally.** disabl
16640 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 ed. The default
16650 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 value may be cha
16660 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e nged by compilin
16670 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 g with the.** [S
16680 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 QLITE_USE_URI] s
16690 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a ymbol defined..*
166a0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
166b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
166c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
166d0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
166e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
166f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
16700 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
16710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16720 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
16730 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
16740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16750 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
16760 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
16770 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
16780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16790 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
167a0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
167b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
167c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
167d0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
167e0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
167f0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
16800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16810 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
16820 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
16830 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
16840 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
16850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
16860 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
16870 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
16880 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
16890 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
168a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
168b0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
168c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
168d0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
168e0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
168f0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
16900 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
16910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
16920 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
16930 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
16940 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
16950 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
16960 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
16970 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
16980 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
16990 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
169a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
169b0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
169c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
169d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
169e0 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 14 /* sqli
169f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
16a00 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
16a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16a20 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a PCACHE 15 /*
16a30 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
16a40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
16a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16a60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 G_LOG 1
16a70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 6 /* xFunc, voi
16a80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d* */.#define SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
16aa0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 17 /*
16ab0 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 int */../*.** CA
16ac0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
16ad0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 Connection Conf
16ae0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
16af0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
16b00 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
16b10 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
16b20 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
16b30 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
16b40 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
16b50 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
16b60 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
16b70 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
16b80 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
16b90 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
16ba0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
16bb0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
16bc0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
16bd0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
16be0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
16bf0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
16c00 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
16c10 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
16c20 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
16c30 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
16c40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
16c50 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
16c60 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
16c70 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
16c80 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 ^The [sqlite3_d
16c90 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
16ca0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
16cb0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
16cc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
16cd0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
16ce0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
16cf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
16d00 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
16d10 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
16d20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
16d30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
16d40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
16d50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 option takes th
16d60 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 ree additional a
16d70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
16d80 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 termine the .**
16d90 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 [lookaside memor
16da0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e y allocator] con
16db0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 figuration for t
16dc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
16dd0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 nection]..** ^Th
16de0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16df0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 (the third para
16e00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
16e10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
16e20 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
16e30 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 o a memory buffe
16e40 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f r to use for loo
16e50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a kaside memory..*
16e60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
16e70 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 ument after the
16e80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16e90 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a LOOKASIDE verb.*
16ea0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e * may be NULL in
16eb0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
16ec0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
16ed0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 the.** lookasid
16ee0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 e buffer itself
16ef0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
16f00 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 alloc()]. ^The s
16f10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
16f20 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
16f30 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
16f40 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 buffer slot. ^T
16f50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
16f60 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 t is the number
16f70 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 of.** slots. Th
16f80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 e size of the bu
16f90 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 ffer in the firs
16fa0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
16fb0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a be greater than.
16fc0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 ** or equal to t
16fd0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 he product of th
16fe0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
16ff0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 rd arguments. T
17000 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 he buffer.** mus
17010 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
17020 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
17030 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 ry. ^If the sec
17040 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
17050 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ** SQLITE_DBCONF
17060 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 IG_LOOKASIDE is
17070 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f not a multiple o
17080 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 f 8, it is inter
17090 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 nally.** rounded
170a0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 down to the nex
170b0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 t smaller multip
170c0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 le of 8. ^(The
170d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
170e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
170f0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 n for a database
17100 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 connection can
17110 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 only be changed
17120 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e when that.** con
17130 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 nection is not c
17140 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c urrently using l
17150 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c ookaside memory,
17160 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 or in other wor
17170 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 ds.** when the "
17180 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 current value" r
17190 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
171a0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 qlite3_db_status
171b0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ](D,[SQLITE_CONF
171c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e IG_LOOKASIDE],..
171d0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 .) is zero..** A
171e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 ny attempt to ch
171f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 ange the lookasi
17200 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 de memory config
17210 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f uration when loo
17220 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 kaside.** memory
17230 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 is in use leave
17240 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 s the configurat
17250 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e ion unchanged an
17260 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 d returns .** [S
17270 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f QLITE_BUSY].)^</
17280 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
17290 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
172a0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a ABLE_FKEY</dt>.*
172b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
172c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
172d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
172e0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 the enforcement
172f0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 of.** [foreign
17300 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d key constraints]
17310 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 . There should
17320 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
17330 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
17340 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
17350 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
17360 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
17370 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 isable FK enforc
17380 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 ement,.** positi
17390 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 ve to enable FK
173a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e enforcement or n
173b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
173c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a FK enforcement.
173d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 ** unchanged. T
173e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
173f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
17400 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 to an integer i
17410 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 nto which.** is
17420 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 written 0 or 1 t
17430 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 o indicate wheth
17440 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e er FK enforcemen
17450 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a t is off or on.*
17460 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
17470 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
17480 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
17490 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
174a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
174b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f case the FK enfo
174c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 rcement setting
174d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
174e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
174f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
17500 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 ONFIG_ENABLE_TRI
17510 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 GGER</dt>.** <dd
17520 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
17530 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
17540 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 or disable [CRE
17550 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
17560 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 iggers]..** Ther
17570 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
17580 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
17590 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
175a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
175b0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
175c0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
175d0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 triggers,.** pos
175e0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
175f0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 triggers or nega
17600 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
17610 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e e setting unchan
17620 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ged..** The seco
17630 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
17640 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
17650 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
17660 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
17670 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
17680 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 ate whether trig
17690 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 gers are disable
176a0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
176b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
176c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
176d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
176e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
176f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
17700 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 se the trigger s
17710 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
17720 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
17730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
17740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17750 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
17760 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 IDE 1001
17770 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
17780 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17790 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
177a0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 LE_FKEY 1002
177b0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f /* int int* */
177c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
177d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
177e0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f TRIGGER 1003 /
177f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a * int int* */...
17800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17810 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
17820 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c e Extended Resul
17830 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 t Codes.**.** ^T
17840 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
17850 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
17860 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
17870 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
17880 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
17890 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
178a0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
178b0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
178c0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
178d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
178e0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
178f0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
17900 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ity..*/.SQLITE_A
17910 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
17920 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
17930 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 odes(sqlite3*, i
17940 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
17950 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 * CAPI3REF: Last
17960 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a Insert Rowid.**
17970 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 .** ^Each entry
17980 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 in an SQLite tab
17990 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 le has a unique
179a0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 64-bit signed.**
179b0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c integer key cal
179c0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c led the [ROWID |
179d0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 "rowid"]. ^The
179e0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 rowid is always
179f0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 available.** as
17a00 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f an undeclared co
17a10 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 lumn named ROWID
17a20 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 , OID, or _ROWID
17a30 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f _ as long as tho
17a40 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 se.** names are
17a50 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 not also used by
17a60 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
17a70 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 ared columns. ^I
17a80 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
17a90 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
17aa0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 ype [INTEGER PRI
17ab0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 MARY KEY] then t
17ac0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
17ad0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
17ae0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
17af0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
17b00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 e returns the [r
17b10 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 owid] of the mos
17b20 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 t recent.** succ
17b30 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
17b40 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
17b50 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 e from the [data
17b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17b70 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
17b80 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 argument. ^As
17b90 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
17ba0 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f n 3.7.7, this ro
17bb0 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 utines.** record
17bc0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
17bd0 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 t rowid of both
17be0 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 ordinary tables
17bf0 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 and [virtual tab
17c00 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 les]..** ^If no
17c10 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
17c20 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 RT]s.** have eve
17c30 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 r occurred on th
17c40 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e at database conn
17c50 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 ection, zero is
17c60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
17c70 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
17c80 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
17c90 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 trigger or with
17ca0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 in a [virtual ta
17cb0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 ble].** method,
17cc0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
17cd0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 e will return th
17ce0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
17cf0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 inserted.** row
17d00 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
17d10 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
17d20 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
17d30 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
17d40 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
17d50 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
17d60 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 able method ends
17d70 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
17d80 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 rned .** by this
17d90 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 routine reverts
17da0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 to what it was
17db0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
17dc0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a er or virtual.**
17dd0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 table method be
17de0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e gan.)^.**.** ^An
17df0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
17e00 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
17e10 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
17e20 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
17e30 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
17e40 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
17e50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
17e60 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
17e70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
17e80 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
17e90 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
17ea0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
17eb0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
17ec0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
17ed0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
17ee0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
17ef0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
17f00 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
17f10 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
17f20 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
17f30 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
17f40 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
17f50 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
17f60 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
17f70 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
17f80 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
17f90 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
17fa0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
17fb0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
17fc0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
17fd0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
17fe0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
17ff0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
18000 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
18010 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
18020 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
18030 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
18040 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
18050 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
18060 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
18070 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
18080 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
18090 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
180a0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
180b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
180c0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
180d0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
180e0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
180f0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
18100 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
18110 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
18120 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
18130 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
18140 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
18150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18160 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
18170 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18180 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
18190 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
181a0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
181b0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
181c0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
181d0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
181e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
181f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
18200 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
18210 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
18220 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
18230 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
18240 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
18250 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
18260 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
18270 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
18280 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18290 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b rowid(sqlite3*);
182a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
182b0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 : Count The Numb
182c0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
182d0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ied.**.** ^This
182e0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
182f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
18300 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
18310 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
18320 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
18330 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
18340 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
18350 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
18360 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
18370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
18380 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
18390 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
183a0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c ameter..** ^(Onl
183b0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 y changes that a
183c0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 re directly spec
183d0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e ified by the [IN
183e0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c SERT], [UPDATE],
183f0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 .** or [DELETE]
18400 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f statement are co
18410 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 unted. Auxiliar
18420 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 y changes caused
18430 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 by.** triggers
18440 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 or [foreign key
18450 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 actions] are not
18460 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 counted.)^ Use
18470 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
18480 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
18490 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e function to fin
184a0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 d the total numb
184b0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a er of changes.**
184c0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 including chang
184d0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 es caused by tri
184e0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 ggers and foreig
184f0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a n key actions..*
18500 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f *.** ^Changes to
18510 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 a view that are
18520 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e simulated by an
18530 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
18540 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 gger].** are not
18550 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 counted. Only
18560 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 real table chang
18570 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a es are counted..
18580 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 **.** ^(A "row c
18590 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e hange" is a chan
185a0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 ge to a single r
185b0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 ow of a single t
185c0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 able.** caused b
185d0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c y an INSERT, DEL
185e0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 ETE, or UPDATE s
185f0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 tatement. Rows
18600 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e that.** are chan
18610 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 ged as side effe
18620 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d cts of [REPLACE]
18630 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
18640 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 lution,.** rollb
18650 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 ack, ABORT proce
18660 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 ssing, [DROP TAB
18670 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f LE], or by any o
18680 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 ther.** mechanis
18690 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 ms do not count
186a0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 as direct row ch
186b0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 anges.)^.**.** A
186c0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 "trigger contex
186d0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 t" is a scope of
186e0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 execution that
186f0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e begins and.** en
18700 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 ds with the scri
18710 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 pt of a [CREATE
18720 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
18730 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c r]. .** Most SQL
18740 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a statements are.
18750 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 ** evaluated out
18760 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 side of any trig
18770 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 ger. This is th
18780 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a e "top level".**
18790 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
187a0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 . If a trigger
187b0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 fires from the t
187c0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e op level, a.** n
187d0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
187e0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f xt is entered fo
187f0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f r the duration o
18800 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 f that one.** tr
18810 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 igger. Subtrigg
18820 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f ers create subco
18830 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 ntexts for their
18840 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a duration..**.**
18850 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 ^Calling [sqlit
18860 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 e3_exec()] or [s
18870 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
18880 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a ecursively does.
18890 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 ** not create a
188a0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
188b0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ext..**.** ^This
188c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
188d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
188e0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
188f0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 es in the.** mos
18900 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
18910 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
18920 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
18930 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 hin the same.**
18940 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
18950 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 .**.** ^Thus, wh
18960 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 en called from t
18970 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 he top level, th
18980 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
18990 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 rns the.** numbe
189a0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 r of changes in
189b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
189c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
189d0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
189e0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 t also occurred
189f0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c at the top level
18a00 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 . ^(Within the
18a10 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 body of a trigge
18a20 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 r,.** the sqlite
18a30 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 3_changes() inte
18a40 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c rface can be cal
18a50 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 led to find the
18a60 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
18a70 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
18a80 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 recently comple
18a90 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ted INSERT, UPDA
18aa0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
18ab0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
18ac0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 n the body of th
18ad0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a e same trigger..
18ae0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
18af0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 number returned
18b00 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
18b10 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 changes.** caus
18b20 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 ed by subtrigger
18b30 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 s since those ha
18b40 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e ve their own con
18b50 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 text.)^.**.** Se
18b60 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
18b70 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
18b80 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
18b90 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
18ba0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
18bb0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 nd the [changes(
18bc0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
18bd0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
18be0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
18bf0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
18c00 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
18c10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
18c20 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
18c30 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
18c40 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
18c50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
18c60 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
18c70 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
18c80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
18c90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
18ca0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
18cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18cc0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
18cd0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
18ce0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
18cf0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
18d00 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 umber of row cha
18d10 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b nges caused by [
18d20 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 INSERT],.** [UPD
18d30 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d ATE] or [DELETE]
18d40 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 statements sinc
18d50 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
18d60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 connection] was
18d70 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 opened..** ^(The
18d80 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 count returned
18d90 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c by sqlite3_total
18da0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 _changes() inclu
18db0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a des all changes.
18dc0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 ** from all [CRE
18dd0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
18de0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 igger] contexts
18df0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 and changes made
18e00 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 by.** [foreign
18e10 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f key actions]. Ho
18e20 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f wever,.** the co
18e30 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
18e40 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 lude changes use
18e50 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b d to implement [
18e60 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
18e70 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c ints,.** do roll
18e80 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 backs or ABORT p
18e90 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 rocessing, or [D
18ea0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 ROP TABLE] proce
18eb0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 ssing. The.** c
18ec0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e ount does not in
18ed0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 clude rows of vi
18ee0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e ews that fire an
18ef0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
18f00 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 gger],.** though
18f10 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 if the INSTEAD
18f20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 OF trigger makes
18f30 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 changes of its
18f40 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 own, those chang
18f50 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 es .** are count
18f60 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 ed.)^.** ^The sq
18f70 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
18f80 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ges() function c
18f90 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 ounts the change
18fa0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 s as soon as.**
18fb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 the statement th
18fc0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 at makes them is
18fd0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e completed (when
18fe0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
18ff0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 andle.** is pass
19000 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ed to [sqlite3_r
19010 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
19020 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 te3_finalize()])
19030 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
19040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
19050 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
19060 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
19070 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
19080 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 ], and the [tota
19090 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 l_changes() SQL
190a0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
190b0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
190c0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
190d0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
190e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
190f0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
19100 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
19110 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
19120 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
19130 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 .** returned is
19140 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
19150 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
19160 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
19170 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 int sqlite3_tota
19180 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 l_changes(sqlite
19190 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
191a0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 3REF: Interrupt
191b0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 A Long-Running Q
191c0 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 uery.**.** ^This
191d0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
191e0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 any pending dat
191f0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 abase operation
19200 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 to abort and.**
19210 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 return at its ea
19220 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 rliest opportuni
19230 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 ty. This routine
19240 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a is typically.**
19250 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f called in respo
19260 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 nse to a user ac
19270 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 tion such as pre
19280 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a ssing "Cancel".*
19290 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 * or Ctrl-C wher
192a0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 e the user wants
192b0 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 a long query op
192c0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a eration to halt.
192d0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ** immediately..
192e0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 **.** ^It is saf
192f0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
19300 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 outine from a th
19310 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 read different f
19320 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 rom the.** threa
19330 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e d that is curren
19340 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 tly running the
19350 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
19360 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 on. But it.** i
19370 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 s not safe to ca
19380 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
19390 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
193a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
193b0 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f t.** is closed o
193c0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 r might close be
193d0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 fore sqlite3_int
193e0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 errupt() returns
193f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 ..**.** ^If an S
19400 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
19410 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 very nearly fini
19420 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 shed at the time
19430 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 when.** sqlite3
19440 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 _interrupt() is
19450 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 called, then it
19460 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 might not have a
19470 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a n opportunity.**
19480 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 to be interrupt
19490 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e ed and might con
194a0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 tinue to complet
194b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 ion..**.** ^An S
194c0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 QL operation tha
194d0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 t is interrupted
194e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
194f0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e LITE_INTERRUPT].
19500 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 .** ^If the inte
19510 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 rrupted SQL oper
19520 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 ation is an INSE
19530 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
19540 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 ELETE.** that is
19550 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 inside an expli
19560 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
19570 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 then the entire
19580 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 transaction.**
19590 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 will be rolled b
195a0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ack automaticall
195b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
195c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
195d0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 D) call is in ef
195e0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 fect until all c
195f0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
19600 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
19610 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ts on [database
19620 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f connection] D co
19630 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 mplete. ^Any ne
19640 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
19650 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
19660 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
19670 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19680 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f () call and befo
19690 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 re the .** runni
196a0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 ng statements re
196b0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 aches zero are i
196c0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 nterrupted as if
196d0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a they had been.*
196e0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 * running prior
196f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 to the sqlite3_i
19700 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e nterrupt() call.
19710 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 ^New SQL state
19720 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
19730 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
19740 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 the running stat
19750 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 ement count reac
19760 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 hes zero are.**
19770 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 not effected by
19780 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
19790 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 rrupt()..** ^A c
197a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
197b0 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
197c0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
197d0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
197e0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
197f0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
19800 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
19810 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
19820 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
19830 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
19840 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
19850 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
19860 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 s..**.** If the
19870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
19880 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 ion closes while
19890 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
198a0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e upt()].** is run
198b0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
198c0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
198d0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 happen..*/.SQLI
198e0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
198f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 te3_interrupt(sq
19900 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
19910 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
19920 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
19930 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c atement Is Compl
19940 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ete.**.** These
19950 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
19960 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 ful during comma
19970 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f nd-line input to
19980 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 determine if th
19990 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 e.** currently e
199a0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d ntered text seem
199b0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 s to form a comp
199c0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
199d0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 nt or.** if addi
199e0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 tional input is
199f0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 needed before se
19a00 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 nding the text i
19a10 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f nto.** SQLite fo
19a20 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 r parsing. ^The
19a30 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
19a40 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 rn 1 if the inpu
19a50 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
19a60 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
19a70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
19a80 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e nt. ^A statemen
19a90 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 t is judged to b
19aa0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 e.** complete if
19ab0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 it ends with a
19ac0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 semicolon token
19ad0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 and is not a pre
19ae0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c fix of a.** well
19af0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 -formed CREATE T
19b00 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
19b10 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 . ^Semicolons t
19b20 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 hat are embedded
19b30 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e within.** strin
19b40 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 g literals or qu
19b50 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 oted identifier
19b60 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 names or comment
19b70 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 s are not.** ind
19b80 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 ependent tokens
19b90 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f (they are part o
19ba0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 f the token in w
19bb0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a hich they are.**
19bc0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 embedded) and t
19bd0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 hus do not count
19be0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 as a statement
19bf0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 terminator. ^Wh
19c00 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 itespace.** and
19c10 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f comments that fo
19c20 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 llow the final s
19c30 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e emicolon are ign
19c40 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ored..**.** ^The
19c50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
19c60 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 rn 0 if the stat
19c70 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c ement is incompl
19c80 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d ete. ^If a.** m
19c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
19ca0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c fails, then SQL
19cb0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 ITE_NOMEM is ret
19cc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
19cd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 ese routines do
19ce0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 not parse the SQ
19cf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 L statements thu
19d00 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 s.** will not de
19d10 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c tect syntactical
19d20 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c ly incorrect SQL
19d30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c ..**.** ^(If SQL
19d40 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ite has not been
19d50 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 initialized usi
19d60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ng [sqlite3_init
19d70 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 ialize()] prior
19d80 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 .** to invoking
19d90 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
19da0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 16() then sqlite
19db0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
19dc0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 s invoked.** aut
19dd0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
19de0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
19df0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 (). If that ini
19e00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c tialization fail
19e10 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 s,.** then the r
19e20 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
19e30 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
19e40 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f e16() will be no
19e50 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 n-zero.** regard
19e60 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
19e70 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 or not the input
19e80 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 SQL is complete
19e90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e .)^.**.** The in
19ea0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
19eb0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 complete()] must
19ec0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
19ed0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 nated.** UTF-8 s
19ee0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
19ef0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
19f00 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
19f10 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
19f20 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
19f30 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
19f40 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
19f50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
19f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
19f70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 lete(const char
19f80 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 *sql);.SQLITE_AP
19f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
19fa0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
19fb0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
19fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
19fd0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
19fe0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
19ff0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a _BUSY Errors.**.
1a000 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1a010 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b sets a callback
1a020 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d function that m
1a030 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
1a040 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 whenever.** an a
1a050 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 ttempt is made t
1a060 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 o open a databas
1a070 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f e table that ano
1a080 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f ther thread.** o
1a090 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f r process has lo
1a0a0 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 cked..**.** ^If
1a0b0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
1a0c0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 k is NULL, then
1a0d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 [SQLITE_BUSY] or
1a0e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
1a0f0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 LOCKED].** is re
1a100 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
1a110 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
1a120 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 ring the lock.
1a130 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
1a140 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 lback.** is not
1a150 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 NULL, then the c
1a160 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 allback might be
1a170 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 invoked with tw
1a180 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a o arguments..**.
1a190 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
1a1a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 gument to the bu
1a1b0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 sy handler is a
1a1c0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
1a1d0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
1a1e0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
1a1f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
1a200 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1a210 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 (). ^The second
1a220 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
1a230 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
1a250 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
1a260 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
1a270 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
1a280 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 en invoked for t
1a290 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e his locking even
1a2a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 t. ^If the.** b
1a2b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 usy callback ret
1a2c0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 urns 0, then no
1a2d0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d additional attem
1a2e0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a pts are made to.
1a2f0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 ** access the da
1a300 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 tabase and [SQLI
1a310 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
1a320 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
1a330 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a D] is returned..
1a340 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 ** ^If the callb
1a350 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
1a360 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 zero, then anoth
1a370 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 er attempt.** is
1a380 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 made to open th
1a390 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 e database for r
1a3a0 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 eading and the c
1a3b0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
1a3c0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
1a3d0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
1a3e0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
1a3f0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 antee that it wi
1a400 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
1a410 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
1a420 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 ock contention.
1a430 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 ^If SQLite deter
1a440 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
1a450 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 ing the busy.**
1a460 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 handler could re
1a470 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f sult in a deadlo
1a480 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 ck, it will go a
1a490 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 head and return
1a4a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
1a4b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1a4c0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 R_BLOCKED] inste
1a4d0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 ad of invoking t
1a4e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1a4f0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 .** Consider a s
1a500 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e cenario where on
1a510 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c e process is hol
1a520 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b ding a read lock
1a530 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 that.** it is t
1a540 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 rying to promote
1a550 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c to a reserved l
1a560 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 ock and.** a sec
1a570 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 ond process is h
1a580 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 olding a reserve
1a590 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 d lock that it i
1a5a0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 s trying.** to p
1a5b0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 romote to an exc
1a5c0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 lusive lock. Th
1a5d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
1a5e0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a cannot proceed.*
1a5f0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 * because it is
1a600 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 blocked by the s
1a610 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 econd and the se
1a620 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e cond process can
1a630 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 not.** proceed b
1a640 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1a650 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 cked by the firs
1a660 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 t. If both proc
1a670 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 esses.** invoke
1a680 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a690 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 s, neither will
1a6a0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 make any progres
1a6b0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a s. Therefore,.*
1a6c0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 * SQLite returns
1a6d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 [SQLITE_BUSY] f
1a6e0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f or the first pro
1a6f0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 cess, hoping tha
1a700 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 t this.** will i
1a710 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 nduce the first
1a720 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 process to relea
1a730 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b se its read lock
1a740 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 and allow.** th
1a750 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
1a760 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a to proceed..**.
1a770 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1a780 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
1a790 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NULL..**.** ^Th
1a7a0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 e [SQLITE_BUSY]
1a7b0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 error is convert
1a7c0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f ed to [SQLITE_IO
1a7d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 ERR_BLOCKED].**
1a7e0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 when SQLite is i
1a7f0 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 n the middle of
1a800 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 a large transact
1a810 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 ion where all th
1a820 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c e.** changes wil
1a830 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 l not fit into t
1a840 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 he in-memory cac
1a850 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c he. SQLite will
1a860 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 .** already hold
1a870 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b a RESERVED lock
1a880 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
1a890 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 file, but it ne
1a8a0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 eds.** to promot
1a8b0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 e this lock to E
1a8c0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 XCLUSIVE so that
1a8d0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 it can spill ca
1a8e0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 che.** pages int
1a8f0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
1a900 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d ile without harm
1a910 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a to concurrent.*
1a920 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 * readers. ^If
1a930 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
1a940 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b promote the lock
1a950 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 , then the in-me
1a960 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 mory.** cache wi
1a970 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e ll be left in an
1a980 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 inconsistent st
1a990 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 ate and so the e
1a9a0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 rror.** code is
1a9b0 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 promoted from th
1a9c0 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e e relatively ben
1a9d0 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 ign [SQLITE_BUSY
1a9e0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ] to.** the more
1a9f0 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f severe [SQLITE_
1aa00 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 IOERR_BLOCKED].
1aa10 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 ^This error cod
1aa20 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 e promotion.** f
1aa30 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 orces an automat
1aa40 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 ic rollback of t
1aa50 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 he changes. See
1aa60 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
1aa70 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 "/cvstrac/wiki?p
1aa80 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f =CorruptionFollo
1aa90 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a wingBusyError">.
1aaa0 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ** CorruptionFol
1aab0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c lowingBusyError<
1aac0 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f /a> wiki page fo
1aad0 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f r a discussion o
1aae0 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 f why.** this is
1aaf0 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a important..**.*
1ab00 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
1ab10 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
1ab20 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
1ab30 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ned for each.**
1ab40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1ab50 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 tion]. Setting
1ab60 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
1ab70 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a er clears any.**
1ab80 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1ab90 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 handler.)^ ^Not
1aba0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b e that calling [
1abb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1abc0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 eout()].** will
1abd0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 also set or clea
1abe0 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c r the busy handl
1abf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 er..**.** The bu
1ac00 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 sy callback shou
1ac10 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 ld not take any
1ac20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f actions which mo
1ac30 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 dify the.** data
1ac40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1ac50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1ac60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 busy handler.
1ac70 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 Any such actions
1ac80 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e .** result in un
1ac90 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
1aca0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 ..** .** A busy
1acb0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
1acc0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
1acd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1ace0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
1acf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
1ad00 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
1ad10 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 handler..*/.SQLI
1ad20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1ad30 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1ad40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
1ad50 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
1ad60 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1ad70 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
1ad80 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e Timeout.**.** ^
1ad90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
1ada0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
1adb0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
1adc0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 handler] that s
1add0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 leeps.** for a s
1ade0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 pecified amount
1adf0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 of time when a t
1ae00 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
1ae10 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a ^The handler.**
1ae20 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 will sleep mult
1ae30 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c iple times until
1ae40 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1ae50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1ae60 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 leeping.** have
1ae70 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 accumulated. ^A
1ae80 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d fter at least "m
1ae90 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
1aea0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
1aeb0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
1aec0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
1aed0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
1aee0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
1aef0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
1af00 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
1af10 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 BLOCKED]..**.**
1af20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f ^Calling this ro
1af30 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
1af40 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
1af50 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
1af60 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
1af70 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
1af80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
1af90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
1afa0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
1afb0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
1afc0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
1afd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 connection] any
1afe0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
1aff0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
1b000 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
1b010 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
1b020 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1b030 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
1b040 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
1b050 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
1b060 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
1b070 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
1b080 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
1b090 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 I int sqlite3_bu
1b0a0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 sy_timeout(sqlit
1b0b0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f e3*, int ms);../
1b0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1b0d0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 onvenience Routi
1b0e0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 nes For Running
1b0f0 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Queries.**.** Th
1b100 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
1b110 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
1b120 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
1b130 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1b140 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
1b150 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
1b160 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
1b170 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
1b180 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
1b190 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
1b1a0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
1b1b0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
1b1c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1b1d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
1b1e0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
1b1f0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
1b200 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
1b210 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
1b220 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
1b230 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
1b240 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
1b250 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
1b260 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
1b270 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
1b280 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
1b290 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
1b2a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1b2b0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
1b2c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
1b2d0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
1b2e0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
1b2f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
1b300 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
1b310 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1b320 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1b330 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
1b340 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
1b350 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1b360 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
1b370 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
1b380 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
1b390 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
1b3a0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
1b3b0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
1b3c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1b3d0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
1b3e0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
1b3f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
1b400 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
1b410 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
1b420 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
1b430 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
1b440 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
1b450 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
1b460 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
1b470 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
1b480 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
1b490 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
1b4a0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
1b4b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1b4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
1b4d0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
1b4e0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
1b4f0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
1b500 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
1b510 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
1b520 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
1b530 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
1b540 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
1b550 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
1b560 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1b570 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
1b580 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
1b590 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1b5a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
1b5b0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
1b5c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1b5d0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
1b5e0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
1b5f0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
1b600 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1b610 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1b620 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
1b630 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
1b640 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1b650 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
1b660 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
1b670 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
1b680 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
1b690 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
1b6a0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
1b6b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1b6c0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
1b6d0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
1b6e0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
1b6f0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
1b700 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
1b710 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
1b720 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
1b730 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
1b740 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
1b750 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
1b760 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
1b770 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
1b780 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
1b790 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1b7a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b7b0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
1b7c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b7d0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
1b7e0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
1b7f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
1b800 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
1b810 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1b820 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
1b830 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1b840 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
1b850 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b860 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
1b870 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1b880 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
1b890 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
1b8a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
1b8b0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
1b8c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1b8d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1b8e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1b8f0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
1b900 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
1b910 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
1b920 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
1b930 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
1b940 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1b950 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
1b960 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
1b970 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
1b980 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
1b990 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
1b9a0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
1b9b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1b9c0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
1b9d0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
1b9e0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
1b9f0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
1ba00 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
1ba10 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
1ba20 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
1ba30 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
1ba40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
1ba50 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
1ba60 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
1ba70 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
1ba80 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
1ba90 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
1baa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1bab0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
1bac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1bad0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
1bae0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
1baf0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
1bb00 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
1bb10 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
1bb20 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
1bb30 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
1bb40 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
1bb50 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
1bb60 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
1bb70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1bb80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
1bb90 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
1bba0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
1bbb0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
1bbc0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
1bbd0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
1bbe0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
1bbf0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
1bc00 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
1bc10 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
1bc20 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
1bc30 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
1bc40 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
1bc50 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
1bc60 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
1bc70 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
1bc80 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
1bc90 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
1bca0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
1bcb0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
1bcc0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
1bcd0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
1bce0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
1bcf0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
1bd00 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
1bd10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
1bd20 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
1bd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1bd40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1bd50 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1bd60 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e , /* An
1bd70 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
1bd80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1bd90 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c zSql, /* SQL
1bda0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
1bdb0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 */. char ***pa
1bdc0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 zResult, /* R
1bdd0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 esults of the qu
1bde0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ery */. int *pn
1bdf0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f Row, /
1be00 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1be10 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 lt rows written
1be20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 here */. int *p
1be30 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 nColumn,
1be40 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1be50 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 ult columns writ
1be60 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 ten here */. ch
1be70 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 ar **pzErrmsg
1be80 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
1be90 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1bea0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .);.SQLITE_API v
1beb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
1bec0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
1bed0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
1bee0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
1bef0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
1bf00 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a g Functions.**.*
1bf10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1bf20 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 are work-alikes
1bf30 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 of the "printf(
1bf40 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e )" family of fun
1bf50 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 ctions.** from t
1bf60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
1bf70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 brary..**.** ^Th
1bf80 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 e sqlite3_mprint
1bf90 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f f() and sqlite3_
1bfa0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 vmprintf() routi
1bfb0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a nes write their.
1bfc0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 ** results into
1bfd0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
1bfe0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
1bff0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lloc()]..** The
1c000 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
1c010 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f by these two ro
1c020 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 utines should be
1c030 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 .** released by
1c040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1c050 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 . ^Both routine
1c060 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
1c070 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
1c080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1c090 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
1c0a0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
1c0b0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
1c0c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
1c0d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ring..**.** ^(Th
1c0e0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e e sqlite3_snprin
1c0f0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
1c100 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
1c110 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
1c120 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
1c130 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
1c140 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
1c150 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
1c160 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
1c170 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1c180 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
1c190 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
1c1a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1c1b0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
1c1c0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
1c1d0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
1c1e0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
1c1f0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
1c200 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a .)^ This is an.
1c210 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
1c220 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
1c230 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
1c240 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
1c250 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1c260 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 ibility. ^(Note
1c270 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
1c280 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1c290 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1c2a0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
1c2b0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1c2c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
1c2d0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
1c2e0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1c2f0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 e buffer.)^ We
1c300 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
1c310 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1c320 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
1c330 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
1c340 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
1c350 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
1c360 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
1c370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1c380 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1c390 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
1c3a0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
1c3b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
1c3c0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ^As long as the
1c3d0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 buffer size is
1c3e0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
1c3f0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 o, sqlite3_snpri
1c400 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 ntf().** guarant
1c410 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 ees that the buf
1c420 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 fer is always ze
1c430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
1c440 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 ^The first.** pa
1c450 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
1c460 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
1c470 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
1c480 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
1c490 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
1c4a0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
1c4b0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
1c4c0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
1c4d0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
1c4e0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
1c4f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
1c500 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e ^The sqlite3_vsn
1c510 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1c520 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 is a varargs ve
1c530 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 rsion of sqlite3
1c540 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a _snprintf()..**.
1c550 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1c560 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 s all implement
1c570 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
1c580 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 formatting.** op
1c590 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 tions that are u
1c5a0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 seful for constr
1c5b0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 ucting SQL state
1c5c0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 ments..** All of
1c5d0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 the usual print
1c5e0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f f() formatting o
1c5f0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 ptions apply. I
1c600 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 n addition, ther
1c610 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 e.** is are "%q"
1c620 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 , "%Q", and "%z"
1c630 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 options..**.**
1c640 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 ^(The %q option
1c650 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
1c660 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
1c670 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d utes a null-term
1c680 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
1c690 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 from the argume
1c6a0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 nt list. But %q
1c6b0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 also doubles ev
1c6c0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 ery '\'' charact
1c6d0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 er..** %q is des
1c6e0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e igned for use in
1c6f0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 side a string li
1c700 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 teral.)^ By dou
1c710 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a bling each '\''.
1c720 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 ** character it
1c730 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 escapes that cha
1c740 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 racter and allow
1c750 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 s it to be inser
1c760 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ted into.** the
1c770 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f string..**.** Fo
1c780 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d r example, assum
1c790 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 e the string var
1c7a0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 iable zText cont
1c7b0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c ains text as fol
1c7c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1c7d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1c7e0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 char *zText =
1c7f0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 "It's a happy da
1c800 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!";.** </pre></
1c810 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1c820 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 * One can use th
1c830 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 is text in an SQ
1c840 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 L statement as f
1c850 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1c860 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1c870 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
1c880 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
1c890 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
1c8a0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 ble VALUES('%q')
1c8b0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1c8c0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1c8d0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1c8e0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1c8f0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1c900 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1c910 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
1c920 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e %q format strin
1c930 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 g is used, the '
1c940 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e \'' character in
1c950 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 zText.** is esc
1c960 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c aped and the SQL
1c970 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 generated is as
1c980 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1c990 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c9a0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
1c9b0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
1c9c0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 'It''s a happy d
1c9d0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!').** </pre><
1c9e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1c9f0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 ** This is corre
1ca00 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 ct. Had we used
1ca10 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %s instead of %
1ca20 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 q, the generated
1ca30 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 SQL.** would ha
1ca40 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 ve looked like t
1ca50 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 his:.**.** <bloc
1ca60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1ca70 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1ca80 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 le1 VALUES('It's
1ca90 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b a happy day!');
1caa0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1cab0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1cac0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c is second exampl
1cad0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 e is an SQL synt
1cae0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 ax error. As a
1caf0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 general rule you
1cb00 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 should.** alway
1cb10 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 s use %q instead
1cb20 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 of %s when inse
1cb30 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 rting text into
1cb40 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1cb50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 ..**.** ^(The %Q
1cb60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1cb70 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 ke %q except it
1cb80 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 also adds single
1cb90 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a quotes around.*
1cba0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 * the outside of
1cbb0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e the total strin
1cbc0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 g. Additionally
1cbd0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 , if the paramet
1cbe0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 er in the.** arg
1cbf0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 ument list is a
1cc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 NULL pointer, %Q
1cc10 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 substitutes the
1cc20 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 text "NULL" (wi
1cc30 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 thout.** single
1cc40 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 quotes).)^ So,
1cc50 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 for example, one
1cc60 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a could say:.**.*
1cc70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1cc80 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
1cc90 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
1cca0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
1ccb0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 O table VALUES(%
1ccc0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 Q)", zText);.**
1ccd0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1cce0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1ccf0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1cd00 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1cd10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1cd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
1cd30 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 above will rende
1cd40 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 r a correct SQL
1cd50 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
1cd60 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c zSQL.** variabl
1cd70 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 e even if the zT
1cd80 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 ext variable is
1cd90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1cda0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 **.** ^(The "%z"
1cdb0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1cdc0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 on works like "%
1cdd0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a s" but with the.
1cde0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 ** addition that
1cdf0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e after the strin
1ce00 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 g has been read
1ce10 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a and copied into.
1ce20 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b ** the result, [
1ce30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1ce40 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 is called on the
1ce50 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e input string.)^
1ce60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
1ce70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 har *sqlite3_mpr
1ce80 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
1ce90 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,...);.SQLITE_AP
1cea0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1ceb0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
1cec0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1ced0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
1cee0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 *sqlite3_snprint
1cef0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 f(int,char*,cons
1cf00 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 t char*, ...);.S
1cf10 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
1cf20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 sqlite3_vsnprint
1cf30 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 f(int,char*,cons
1cf40 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1cf50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1cf60 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
1cf70 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a ation Subsystem.
1cf80 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
1cf90 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 core uses these
1cfa0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 three routines
1cfb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f for all of its o
1cfc0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d wn.** internal m
1cfd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1cfe0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 needs. "Core" i
1cff0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 n the previous s
1d000 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 entence.** does
1d010 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 not include oper
1d020 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
1d030 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d cific VFS implem
1d040 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a entation. The.*
1d050 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 * Windows VFS us
1d060 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 es native malloc
1d070 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f () and free() fo
1d080 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e r some operation
1d090 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
1d0a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
1d0b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
1d0c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c pointer to a bl
1d0d0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 ock.** of memory
1d0e0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
1d0f0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 s in length, whe
1d100 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 re N is the para
1d110 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 meter..** ^If sq
1d120 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
1d130 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 s unable to obta
1d140 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 in sufficient fr
1d150 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 ee.** memory, it
1d160 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1d170 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 pointer. ^If th
1d180 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f e parameter N to
1d190 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1d1a0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 oc() is zero or
1d1b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 negative then sq
1d1c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
1d1d0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c eturns.** a NULL
1d1e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1d1f0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
1d200 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 _free() with a p
1d210 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c ointer previousl
1d220 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 y returned.** by
1d230 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1d240 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1d250 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 lloc() releases
1d260 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a that memory so.*
1d270 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 * that it might
1d280 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 be reused. ^The
1d290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1d2a0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
1d2b0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
1d2c0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
1d2d0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
1d2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
1d2f0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
1d300 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
1d310 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
1d320 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
1d330 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
1d340 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
1d350 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
1d360 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
1d370 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
1d380 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
1d390 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
1d3a0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
1d3b0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
1d3c0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
1d3d0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1d3e0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
1d3f0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
1d400 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
1d410 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
1d420 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
1d430 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
1d440 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
1d450 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
1d460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1d470 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1d480 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ()..**.** ^(The
1d490 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d4a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
1d4b0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 mpts to resize a
1d4c0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 .** prior memory
1d4d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 allocation to b
1d4e0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
1d4f0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 es, where N is t
1d500 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
1d510 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d ameter. The mem
1d520 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
1d530 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 o be resized is
1d540 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 the first.** par
1d550 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 ameter.)^ ^ If t
1d560 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1d570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1d580 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 alloc().** is a
1d590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
1d5a0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 n its behavior i
1d5b0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 s identical to c
1d5c0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
1d5d0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 3_malloc(N) wher
1d5e0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
1d5f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
1d600 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1d610 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 ..** ^If the sec
1d620 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1d630 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1d640 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a () is zero or.**
1d650 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 negative then t
1d660 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 he behavior is e
1d670 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 xactly the same
1d680 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 as calling.** sq
1d690 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 lite3_free(P) wh
1d6a0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 ere P is the fir
1d6b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
1d6c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d6d0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
1d6e0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
1d6f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1d700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d710 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
1d720 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
1d730 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 or NULL if suff
1d740 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 icient memory is
1d750 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
1d760 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 ^If M is the si
1d770 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ze of the prior
1d780 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e allocation, then
1d790 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a min(N,M) bytes.
1d7a0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ** of the prior
1d7b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 allocation are c
1d7c0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 opied into the b
1d7d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 eginning of buff
1d7e0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 er returned.** b
1d7f0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f y sqlite3_reallo
1d800 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f c() and the prio
1d810 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1d820 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
1d830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1d840 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 returns NULL, th
1d850 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c en the prior all
1d860 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f ocation.** is no
1d870 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e t freed..**.** ^
1d880 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 The memory retur
1d890 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ned by sqlite3_m
1d8a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 alloc() and sqli
1d8b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
1d8c0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e is always align
1d8d0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 ed to at least a
1d8e0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8 byte boundar
1d8f0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 y, or to a.** 4
1d900 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 byte boundary if
1d910 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 the [SQLITE_4_B
1d920 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c YTE_ALIGNED_MALL
1d930 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 OC] compile-time
1d940 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 .** option is us
1d950 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c ed..**.** In SQL
1d960 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
1d970 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 0 and 3.5.1, it
1d980 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 was possible to
1d990 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 define.** the SQ
1d9a0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 LITE_OMIT_MEMORY
1d9b0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 _ALLOCATION whic
1d9c0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 h would cause th
1d9d0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d e built-in.** im
1d9e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1d9f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 these routines t
1da00 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 o be omitted. T
1da10 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a hat capability.*
1da20 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 * is no longer p
1da30 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 rovided. Only b
1da40 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
1da50 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 llocators can be
1da60 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 used..**.** The
1da70 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 Windows OS inte
1da80 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c rface layer call
1da90 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 s.** the system
1daa0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
1dab0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
1dac0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
1dad0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
1dae0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
1daf0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
1db00 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
1db10 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
1db20 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
1db30 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
1db40 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 Windows.** insta
1db50 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
1db60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
1db70 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c rs are detected,
1db80 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 but.** they are
1db90 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
1dba0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
1dbb0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
1dbc0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
1dbd0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
1dbe0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 EM]..**.** The p
1dbf0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
1dc00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
1dc10 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
1dc20 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1dc30 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e must be either N
1dc40 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e ULL or else poin
1dc50 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ters obtained fr
1dc60 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e om a prior.** in
1dc70 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
1dc80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
1dc90 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
1dca0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a oc()] that have.
1dcb0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 ** not yet been
1dcc0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
1dcd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
1dce0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 must not read or
1dcf0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 write any part
1dd00 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 of.** a block of
1dd10 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
1dd20 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
1dd30 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
1dd40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 ite3_free()] or
1dd50 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1dd60 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
1dd70 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
1dd80 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 _malloc(int);.SQ
1dd90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
1dda0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 qlite3_realloc(v
1ddb0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 oid*, int);.SQLI
1ddc0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
1ddd0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b te3_free(void*);
1dde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ddf0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1de00 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a or Statistics.**
1de10 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 .** SQLite provi
1de20 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e des these two in
1de30 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 terfaces for rep
1de40 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 orting on the st
1de50 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b atus.** of the [
1de60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1de70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ], [sqlite3_free
1de80 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
1de90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1dea0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 routines, which
1deb0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 form the built-i
1dec0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
1ded0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a ion subsystem..*
1dee0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
1def0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1df00 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
1df10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1df20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f bytes.** of memo
1df30 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 ry currently out
1df40 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 standing (malloc
1df50 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 ed but not freed
1df60 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 )..** ^The [sqli
1df70 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1df80 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 ater()] routine
1df90 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 returns the maxi
1dfa0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 mum.** value of
1dfb0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1dfc0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 used()] since th
1dfd0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
1dfe0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 k.** was last re
1dff0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 set. ^The value
1e000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
1e010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1e020 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
1e030 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1e040 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 hwater()] includ
1e050 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a e any overhead.*
1e060 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 * added by SQLit
1e070 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 e in its impleme
1e080 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ntation of [sqli
1e090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a te3_malloc()],.*
1e0a0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 * but not overhe
1e0b0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 ad added by the
1e0c0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 any underlying s
1e0d0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a ystem library.**
1e0e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b routines that [
1e0f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1e100 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a ] may call..**.*
1e110 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 * ^The memory hi
1e120 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 gh-water mark is
1e130 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 reset to the cu
1e140 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a rrent value of.*
1e150 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
1e160 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 y_used()] if and
1e170 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 only if the par
1e180 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
1e190 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1e1a0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
1e1b0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 e. ^The value r
1e1c0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
1e1d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1e1e0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 ghwater(1)] is t
1e1f0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1e200 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 rk.** prior to t
1e210 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c he reset..*/.SQL
1e220 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1e230 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
1e240 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
1e250 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
1e260 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
1e270 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1e280 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 er(int resetFlag
1e290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1e2a0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f EF: Pseudo-Rando
1e2b0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 m Number Generat
1e2c0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 or.**.** SQLite
1e2d0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d contains a high-
1e2e0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 quality pseudo-r
1e2f0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e andom number gen
1e300 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 erator (PRNG) us
1e310 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 ed to.** select
1e320 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 random [ROWID |
1e330 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 ROWIDs] when ins
1e340 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 erting new recor
1e350 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 ds into a table
1e360 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 that.** already
1e370 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 uses the largest
1e380 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 possible [ROWID
1e390 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 ]. The PRNG is
1e3a0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a also used for.**
1e3b0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 the build-in ra
1e3c0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f ndom() and rando
1e3d0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 mblob() SQL func
1e3e0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 tions. This int
1e3f0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a erface allows.**
1e400 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f applications to
1e410 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 access the same
1e420 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 PRNG for other
1e430 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 purposes..**.**
1e440 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 ^A call to this
1e450 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
1e460 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
1e470 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
1e480 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 P..**.** ^The f
1e490 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 irst time this r
1e4a0 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 outine is invoke
1e4b0 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e d (either intern
1e4c0 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 ally or by.** th
1e4d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 e application) t
1e4e0 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 he PRNG is seede
1e4f0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
1e500 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ss obtained.** f
1e510 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e rom the xRandomn
1e520 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ess method of th
1e530 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1e540 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
1e550 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 ** ^On all subse
1e560 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
1e570 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 s, the pseudo-ra
1e580 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
1e590 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
1e5a0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
1e5b0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
1e5c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
1e5d0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
1e5e0 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 hod..*/.SQLITE_A
1e5f0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
1e600 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e randomness(int N
1e610 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a , void *P);../*.
1e620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
1e630 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 pile-Time Author
1e640 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ization Callback
1e650 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
1e660 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
1e670 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
1e680 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
1e690 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
1e6a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1e6b0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
1e6c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1e6d0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
1e6e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1e6f0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
1e700 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
1e710 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
1e720 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
1e730 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
1e740 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
1e750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
1e760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1e770 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 pare16()] and [s
1e780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e790 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 _v2()]. ^At var
1e7a0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
1e7b0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
1e7c0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
1e7d0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
1e7e0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
1e7f0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
1e800 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
1e810 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1e820 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
1e830 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
1e840 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
1e850 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 d. ^The authori
1e860 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
1e870 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
1e880 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
1e890 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
1e8a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
1e8b0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
1e8c0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
1e8d0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
1e8e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
1e8f0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
1e900 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
1e910 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
1e920 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
1e930 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1e940 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
1e950 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
1e960 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 ^If the author
1e970 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
1e980 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
1e990 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
1e9a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
1e9b0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
1e9c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
1e9d0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
1e9e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1e9f0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
1ea00 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
1ea10 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
1ea20 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
1ea30 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
1ea40 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
1ea50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1ea60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
1ea70 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
1ea80 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
1ea90 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
1eaa0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 ^When the callba
1eab0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
1eac0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
1ead0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1eae0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
1eaf0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
1eb00 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
1eb10 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
1eb20 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
1eb30 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
1eb40 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
1eb50 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
1eb60 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 .**.** ^The fir
1eb70 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
1eb80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1eb90 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
1eba0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a y of the third.*
1ebb0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 * parameter to t
1ebc0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
1ebd0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 uthorizer() inte
1ebe0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f rface. ^The seco
1ebf0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
1ec00 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1ec10 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
1ec20 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
1ec30 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
1ec40 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
1ec50 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
1ec60 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
1ec70 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 ed. ^The third t
1ec80 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
1ec90 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 ameters.** to th
1eca0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a e callback are z
1ecb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1ecc0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
1ecd0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ain additional.*
1ece0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 * details about
1ecf0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 the action to be
1ed00 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
1ed10 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
1ed20 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
1ed30 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 E_READ].** and t
1ed40 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1ed50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f rns [SQLITE_IGNO
1ed60 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 RE] then the.**
1ed70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1ed80 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 ent] statement i
1ed90 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f s constructed to
1eda0 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 substitute.** a
1edb0 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 NULL value in p
1edc0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c lace of the tabl
1edd0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f e column that wo
1ede0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e uld have.** been
1edf0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 read if [SQLITE
1ee00 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 _OK] had been re
1ee10 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 turned. The [SQ
1ee20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 LITE_IGNORE].**
1ee30 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 return can be us
1ee40 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e ed to deny an un
1ee50 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 trusted user acc
1ee60 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 ess to individua
1ee70 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 l.** columns of
1ee80 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 a table..** ^If
1ee90 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
1eea0 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 is [SQLITE_DELET
1eeb0 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 E] and the callb
1eec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b ack returns.** [
1eed0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
1eee0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d hen the [DELETE]
1eef0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 operation proce
1ef00 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b eds but the.** [
1ef10 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a truncate optimiz
1ef20 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c ation] is disabl
1ef30 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 ed and all rows
1ef40 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 are deleted indi
1ef50 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 vidually..**.**
1ef60 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 An authorizer is
1ef70 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 used when [sqli
1ef80 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
1ef90 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 eparing].** SQL
1efa0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 statements from
1efb0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 an untrusted sou
1efc0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 rce, to ensure t
1efd0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 hat the SQL stat
1efe0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 ements.** do not
1eff0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 try to access d
1f000 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 ata they are not
1f010 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c allowed to see,
1f020 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f or that they do
1f030 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 not.** try to e
1f040 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 xecute malicious
1f050 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
1f060 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 damage the data
1f070 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 base. For.** ex
1f080 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
1f090 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 ation may allow
1f0a0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 a user to enter
1f0b0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c arbitrary.** SQL
1f0c0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 queries for eva
1f0d0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 luation by a dat
1f0e0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 abase. But the
1f0f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
1f100 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 .** not want the
1f110 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 user to be able
1f120 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 to make arbitra
1f130 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ry changes to th
1f140 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 e.** database.
1f150 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f An authorizer co
1f160 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 uld then be put
1f170 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 in place while t
1f180 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 he.** user-enter
1f190 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 ed SQL is being
1f1a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f1b0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 | prepared] tha
1f1c0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 t.** disallows e
1f1d0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 verything except
1f1e0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1f1f0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ents..**.** Appl
1f200 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 ications that ne
1f210 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 ed to process SQ
1f220 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 L from untrusted
1f230 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 sources.** migh
1f240 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 t also consider
1f250 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 lowering resourc
1f260 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b e limits using [
1f270 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
1f280 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 .** and limiting
1f290 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 database size u
1f2a0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 sing the [max_pa
1f2b0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
1f2c0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f A].** in additio
1f2d0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 n to using an au
1f2e0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 thorizer..**.**
1f2f0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^(Only a single
1f300 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 authorizer can b
1f310 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 e in place on a
1f320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f330 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 ion.** at a time
1f340 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 . Each call to
1f350 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1f360 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 orizer overrides
1f370 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 the.** previous
1f380 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 call.)^ ^Disab
1f390 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 le the authorize
1f3a0 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 r by installing
1f3b0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e a NULL callback.
1f3c0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
1f3d0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 er is disabled b
1f3e0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
1f3f0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
1f400 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
1f410 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
1f420 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
1f430 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
1f440 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1f450 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f nvoked the autho
1f460 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a rizer callback..
1f470 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
1f480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1f490 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
1f4a0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
1f4b0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
1f4c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1f4d0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
1f4e0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
1f4f0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
1f500 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 ..**.** ^When [s
1f510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f520 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 2()] is used to
1f530 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
1f540 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 ent, the.** stat
1f550 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 ement might be r
1f560 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e e-prepared durin
1f570 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1f580 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 )] due to a .**
1f590 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 schema change.
1f5a0 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 Hence, the appli
1f5b0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e cation should en
1f5c0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a sure that the.**
1f5d0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 correct authori
1f5e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d zer callback rem
1f5f0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 ains in place du
1f600 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 ring the [sqlite
1f610 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_step()]..**.**
1f620 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
1f630 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1f640 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ack is invoked o
1f650 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 nly during.** [s
1f660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1f670 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
1f680 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f s. Authorizatio
1f690 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 n is not.** perf
1f6a0 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 ormed during sta
1f6b0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f tement evaluatio
1f6c0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 n in [sqlite3_st
1f6d0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a ep()], unless.**
1f6e0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 as stated in th
1f6f0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 e previous parag
1f700 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 raph, sqlite3_st
1f710 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 ep() invokes.**
1f720 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f730 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 v2() to reprepar
1f740 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 e a statement af
1f750 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 ter a schema cha
1f760 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 nge..*/.SQLITE_A
1f770 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
1f780 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
1f790 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
1f7a0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
1f7b0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
1f7c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1f7d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1f7e0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
1f7f0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
1f800 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1f810 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
1f820 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1f830 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1f840 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1f850 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1f860 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
1f870 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
1f880 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
1f890 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
1f8a0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
1f8b0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
1f8c0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
1f8d0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
1f8e0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
1f8f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1f900 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1f910 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
1f920 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
1f930 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1f940 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
1f950 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
1f960 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
1f970 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 used as a [SQLIT
1f980 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 E_ROLLBACK | ret
1f990 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f urn code].** fro
1f9a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
1f9b0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
1f9c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
1f9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f9e0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
1f9f0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
1fa00 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
1fa10 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
1fa20 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
1fa30 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
1fa40 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
1fa50 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
1fa60 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
1fa70 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1fa80 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a er Action Codes.
1fa90 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1faa0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1fab0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 r()] interface r
1fac0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
1fad0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
1fae0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
1faf0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 to authorize cer
1fb00 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 tain SQL stateme
1fb10 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 nt actions. The
1fb20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
1fb30 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
1fb40 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
1fb50 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 er code that spe
1fb60 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 cifies.** what a
1fb70 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 ction is being a
1fb80 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 uthorized. Thes
1fb90 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 e are the intege
1fba0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 r action codes t
1fbb0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f hat.** the autho
1fbc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
1fbd0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a ay be passed..**
1fbe0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e .** These action
1fbf0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 code values sig
1fc00 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f nify what kind o
1fc10 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 f operation is t
1fc20 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a o be.** authoriz
1fc30 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 ed. The 3rd and
1fc40 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
1fc50 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 to the authoriza
1fc60 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
1fc70 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 function will b
1fc80 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
1fc90 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f NULL depending o
1fca0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 n which of these
1fcb0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 .** codes is use
1fcc0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1fcd0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 parameter. ^(Th
1fce0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
1fcf0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
1fd00 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1fd10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1fd20 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
1fd30 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
1fd40 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
1fd50 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 e.)^ ^The 6th p
1fd60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1fd70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1fd80 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
1fd90 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
1fda0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1fdb0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1fdc0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1fdd0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
1fde0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
1fdf0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
1fe00 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
1fe10 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
1fe20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a SQL code..*/./**
1fe30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1fe40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1fe50 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a ********* 3rd **
1fe60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a ********** 4th *
1fe70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 **********/.#def
1fe80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1fe90 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 E_INDEX
1fea0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 1 /* Index Na
1feb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1fec0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1fed0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1fee0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1fef0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 2 /* Table Nam
1ff00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ff10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ff20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1ff30 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 TEMP_INDEX 3
1ff40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1ff50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1ff60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ff70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1ff80 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 EMP_TABLE 4
1ff90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1ffa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1ffb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1ffc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1ffd0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 MP_TRIGGER 5
1ffe0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1fff0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
20000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20010 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
20020 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 P_VIEW 6
20030 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
20040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20060 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 LITE_CREATE_TRIG
20070 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f GER 7 /
20080 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
20090 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
200a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
200b0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 ITE_CREATE_VIEW
200c0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 8 /*
200d0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
200e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
200f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20100 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 TE_DELETE
20110 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 9 /*
20120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20150 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 E_DROP_INDEX
20160 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 10 /* I
20170 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
20180 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
201a0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 _DROP_TABLE
201b0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 11 /* Ta
201c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
201d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
201e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
201f0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 DROP_TEMP_INDEX
20200 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 12 /* Ind
20210 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
20220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
20240 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ROP_TEMP_TABLE
20250 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 13 /* Tabl
20260 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
20270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
20280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
20290 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 OP_TEMP_TRIGGER
202a0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 14 /* Trigg
202b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
202c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
202d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
202e0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 P_TEMP_VIEW
202f0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 15 /* View N
20300 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
20310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
20330 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
20340 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 16 /* Trigger
20350 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
20360 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
20370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
20380 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 VIEW
20390 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 17 /* View Nam
203a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
203b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
203c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 ne SQLITE_INSERT
203d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
203e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
203f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
20400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20410 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 e SQLITE_PRAGMA
20420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
20430 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d /* Pragma Nam
20440 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 e 1st arg or
20450 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 NULL */.#define
20460 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 SQLITE_READ
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20
20480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
20490 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
204a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
204b0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 SQLITE_SELECT
204c0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 21
204d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
204e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
204f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20500 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f QLITE_TRANSACTIO
20510 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 N 22
20520 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
20530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20550 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 LITE_UPDATE
20560 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 23 /
20570 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20580 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
20590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
205a0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 ITE_ATTACH
205b0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 24 /*
205c0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 Filename
205d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
205e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
205f0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 TE_DETACH
20600 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 25 /*
20610 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
20620 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20640 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 E_ALTER_TABLE
20650 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 26 /* D
20660 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 atabase Name T
20670 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20690 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 _REINDEX
206a0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 27 /* In
206b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 dex Name NU
206c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
206d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
206e0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 ANALYZE
206f0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 28 /* Tab
20700 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
20710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
20720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20730 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 REATE_VTABLE
20740 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 29 /* Tabl
20750 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
20760 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
20770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
20780 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 OP_VTABLE
20790 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 30 /* Table
207a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
207b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
207c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e efine SQLITE_FUN
207d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 CTION
207e0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 31 /* NULL
207f0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 Functi
20800 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 on Name */.#de
20810 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 fine SQLITE_SAVE
20820 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 POINT
20830 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 32 /* Operati
20840 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 on Savepoi
20850 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 nt Name */.#def
20860 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 ine SQLITE_COPY
20870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20880 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 0 /* No longe
20890 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a r used */../*.**
208a0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 CAPI3REF: Traci
208b0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 ng And Profiling
208c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
208d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
208e0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
208f0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
20900 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
20910 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
20920 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
20930 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
20940 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
20950 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
20960 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
20970 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
20980 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
20990 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
209a0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
209b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
209c0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
209d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
209e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
209f0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ce() callback is
20a00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 invoked with a
20a10 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
20a20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 of the.** SQL st
20a30 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 atement text as
20a40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
20a50 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
20a60 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 ting..** ^(Addit
20a70 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 ional sqlite3_tr
20a80 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 ace() callbacks
20a90 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 might occur.** a
20aa0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
20ab0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
20ac0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
20ad0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
20ae0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
20af0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
20b00 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
20b10 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 es the trigger.)
20b20 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c ^.**.** ^The cal
20b30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
20b40 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
20b50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 ite3_profile() i
20b60 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 s invoked.** as
20b70 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
20b80 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 nt finishes. ^T
20b90 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
20ba0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 ack contains.**
20bb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
20bc0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 tement text and
20bd0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 an estimate of w
20be0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a all-clock time.*
20bf0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 * of how long th
20c00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f at statement too
20c10 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 k to run. ^The
20c20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
20c30 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 .** time is in u
20c40 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f nits of nanoseco
20c50 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 nds, however the
20c60 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 current impleme
20c70 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e ntation.** is on
20c80 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 ly capable of mi
20c90 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 llisecond resolu
20ca0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 tion so the six
20cb0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e least significan
20cc0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 t.** digits in t
20cd0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e he time are mean
20ce0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 ingless. Future
20cf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
20d00 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f ite.** might pro
20d10 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 vide greater res
20d20 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 olution on the p
20d30 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b rofiler callback
20d40 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
20d50 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 3_profile() func
20d60 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 tion is consider
20d70 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 ed experimental
20d80 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 and is.** subjec
20d90 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 t to change in f
20da0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
20db0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c f SQLite..*/.SQL
20dc0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
20dd0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
20de0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
20df0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
20e00 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
20e10 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
20e20 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
20e30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
20e40 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
20e50 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
20e60 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
20e70 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
20e80 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
20e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
20ea0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
20eb0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
20ec0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 e sqlite3_progre
20ed0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 ss_handler(D,N,X
20ee0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ,P) interface ca
20ef0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 uses the callbac
20f00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 k.** function X
20f10 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 to be invoked pe
20f20 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
20f30 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 g long running c
20f40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
20f50 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
20f60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
20f70 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 d [sqlite3_get_t
20f80 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 able()] for.** d
20f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20fa0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c on D. An exampl
20fb0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
20fc0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
20fd0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
20fe0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
20ff0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
21000 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
21010 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f P is passed thro
21020 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ugh as the only
21030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
21040 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 .** callback fu
21050 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 nction X. ^The
21060 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 parameter N is t
21070 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a he number of .**
21080 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e [virtual machin
21090 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 e instructions]
210a0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 that are evaluat
210b0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 ed between succe
210c0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 ssive.** invocat
210d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c ions of the call
210e0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f back X..**.** ^O
210f0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
21100 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 gress handler ma
21110 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 y be defined at
21120 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 one time per.**
21130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
21140 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 tion]; setting a
21150 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 new progress ha
21160 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 ndler cancels th
21170 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e e.** old one. ^
21180 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 Setting paramete
21190 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 r X to NULL disa
211a0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 bles the progres
211b0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 s handler..** ^T
211c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
211d0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 ler is also disa
211e0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 bled by setting
211f0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 N to a value les
21200 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a s.** than 1..**.
21210 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 ** ^If the progr
21220 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
21230 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
21240 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a he operation is.
21250 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 ** interrupted.
21260 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 This feature ca
21270 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 n be used to imp
21280 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e lement a.** "Can
21290 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
212a0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 GUI progress di
212b0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
212c0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
212d0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 dler callback mu
212e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
212f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
21300 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
21310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
21320 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
21330 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
21340 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
21350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21360 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
21370 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
21380 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
21390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
213a0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
213b0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
213c0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
213d0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 ph..**.*/.SQLITE
213e0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
213f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
21400 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
21410 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
21420 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
21430 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e CAPI3REF: Openin
21440 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 g A New Database
21450 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a Connection.**.*
21460 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
21470 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 s open an SQLite
21480 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 database file a
21490 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 s specified by t
214a0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 he .** filename
214b0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 argument. ^The f
214c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
214d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
214e0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 as UTF-8 for.**
214f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
21500 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
21510 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d v2() and as UTF-
21520 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
21530 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 byte.** order f
21540 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 or sqlite3_open1
21550 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 6(). ^(A [databa
21560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
21570 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
21580 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
21590 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
215a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
215b0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
215c0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
215d0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
215e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
215f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
21600 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
21610 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
21620 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
21630 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
21640 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
21650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
21660 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 * object.)^ ^(If
21670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
21680 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 opened (and/or
21690 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 created) success
216a0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b fully, then.** [
216b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
216c0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 turned. Otherwi
216d0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
216e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 e] is returned.)
216f0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ^ ^The.** [sqlit
21700 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 e3_errmsg()] or
21710 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
21720 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6()] routines ca
21730 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
21740 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 ain.** an Englis
21750 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 h language descr
21760 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 iption of the er
21770 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ror following a
21780 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a failure of any.*
21790 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
217a0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 _open() routines
217b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 ..**.** ^The def
217c0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f ault encoding fo
217d0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 r the database w
217e0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a ill be UTF-8 if.
217f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
21800 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
21810 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 n_v2() is called
21820 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 and.** UTF-16 i
21830 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
21840 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 e order if sqlit
21850 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 e3_open16() is u
21860 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 sed..**.** Wheth
21870 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 er or not an err
21880 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 or occurs when i
21890 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 t is opened, res
218a0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 ources.** associ
218b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 ated with the [d
218c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
218d0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c on] handle shoul
218e0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 d be released by
218f0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 .** passing it t
21900 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
21910 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e ()] when it is n
21920 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 o longer require
21930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
21940 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
21950 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c nterface works l
21960 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ike sqlite3_open
21970 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 ().** except tha
21980 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f t it accepts two
21990 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 additional para
219a0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 meters for addit
219b0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ional control.**
219c0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 over the new da
219d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
219e0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 n. ^(The flags
219f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
21a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21a10 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f ) can take one o
21a20 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 f.** the followi
21a30 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c ng three values,
21a40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
21a50 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ined with the .*
21a60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e * [SQLITE_OPEN_N
21a70 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 OMUTEX], [SQLITE
21a80 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
21a90 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 , [SQLITE_OPEN_S
21aa0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 HAREDCACHE],.**
21ab0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 [SQLITE_OPEN_PRI
21ac0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f VATECACHE], and/
21ad0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
21ae0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a URI] flags:)^.**
21af0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 .** <dl>.** ^(<d
21b00 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
21b10 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a EADONLY]</dt>.**
21b20 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
21b30 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 e is opened in r
21b40 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 ead-only mode.
21b50 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
21b60 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 does not.** alre
21b70 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 ady exist, an er
21b80 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
21b90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
21ba0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
21bb0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e _READWRITE]</dt>
21bc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
21bd0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
21be0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
21bf0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 riting if possib
21c00 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a le, or reading.*
21c10 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 * only if the fi
21c20 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 le is write prot
21c30 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 ected by the ope
21c40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
21c50 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 In either.** cas
21c60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d e the database m
21c70 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 ust already exis
21c80 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 t, otherwise an
21c90 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
21ca0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
21cb0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
21cc0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
21cd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
21ce0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATE]</dt>.** <dd
21cf0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
21d00 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
21d10 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c ing and writing,
21d20 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 and is created
21d30 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f if.** it does no
21d40 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e t already exist.
21d50 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 This is the beh
21d60 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c avior that is al
21d70 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a ways used for.**
21d80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
21d90 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
21da0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 16().</dd>)^.**
21db0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 </dl>.**.** If t
21dc0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
21dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
21de0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 _v2() is not one
21df0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 of the.** combi
21e00 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 nations shown ab
21e10 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 ove optionally c
21e20 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 ombined with oth
21e30 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 er.** [SQLITE_OP
21e40 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 EN_READONLY | SQ
21e50 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 LITE_OPEN_* bits
21e60 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 ].** then the be
21e70 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
21e80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ned..**.** ^If t
21e90 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
21ea0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 NOMUTEX] flag is
21eb0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 set, then the d
21ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21ed0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 on.** opens in t
21ee0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 he multi-thread
21ef0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
21f00 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
21f10 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a single-thread.**
21f20 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 mode has not be
21f30 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c en set at compil
21f40 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
21f50 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a time. ^If the.*
21f60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 * [SQLITE_OPEN_F
21f70 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 ULLMUTEX] flag i
21f80 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 s set then the d
21f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21fa0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 on opens.** in t
21fb0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 he serialized [t
21fc0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 hreading mode] u
21fd0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 nless single-thr
21fe0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 ead was.** previ
21ff0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 ously selected a
22000 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
22010 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a r start-time..**
22020 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
22030 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 EN_SHAREDCACHE]
22040 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 flag causes the
22050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22060 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 ion to be.** eli
22070 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 gible to use [sh
22080 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
22090 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 , regardless of
220a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
220b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 hared.** cache i
220c0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 s enabled using
220d0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
220e0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e shared_cache()].
220f0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ^The.** [SQLIT
22100 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
22110 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
22120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
22130 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a nnection to not.
22140 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 ** participate i
22150 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 n [shared cache
22160 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 mode] even if it
22170 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a is enabled..**.
22180 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 ** ^The fourth p
22190 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
221a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
221b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
221c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 .** [sqlite3_vfs
221d0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
221e0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 fines the operat
221f0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 ing system inter
22200 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 face that.** the
22210 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
22220 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 nnection should
22230 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f use. ^If the fo
22240 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
22250 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
22260 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 ter then the def
22270 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
22280 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 s] object is use
22290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
222a0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d filename is ":m
222b0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 emory:", then a
222c0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
222d0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 ry in-memory dat
222e0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 abase.** is crea
222f0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e ted for the conn
22300 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 ection. ^This i
22310 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
22320 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 e will vanish wh
22330 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 en.** the databa
22340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
22350 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 closed. Future
22360 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
22370 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b ite might.** mak
22380 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f e use of additio
22390 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 nal special file
223a0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e names that begin
223b0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 with the ":" ch
223c0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 aracter..** It i
223d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
223e0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 at when a databa
223f0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 se filename actu
22400 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 ally does begin
22410 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 with.** a ":" ch
22420 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 aracter you shou
22430 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 ld prefix the fi
22440 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 lename with a pa
22450 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a thname such as.*
22460 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 * "./" to avoid
22470 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a ambiguity..**.**
22480 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
22490 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 e is an empty st
224a0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 ring, then a pri
224b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a vate, temporary.
224c0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 ** on-disk datab
224d0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 ase will be crea
224e0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 ted. ^This priv
224f0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c ate database wil
22500 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 l be.** automati
22510 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 cally deleted as
22520 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 soon as the dat
22530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22540 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a is closed..**.*
22550 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 * [[URI filename
22560 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 s in sqlite3_ope
22570 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 n()]] <h3>URI Fi
22580 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a lenames</h3>.**.
22590 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 ** ^If [URI file
225a0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 name] interpreta
225b0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c tion is enabled,
225c0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d and the filenam
225d0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 e argument.** be
225e0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a gins with "file:
225f0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 ", then the file
22600 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 name is interpre
22610 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 ted as a URI. ^U
22620 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 RI.** filename i
22630 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
22640 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
22650 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
22660 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 ] flag is.** set
22670 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 in the fourth a
22680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
22690 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 e3_open_v2(), or
226a0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 if it has.** be
226b0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 en enabled globa
226c0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 lly using the [S
226d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
226e0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 ] option with th
226f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
22700 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f nfig()] method o
22710 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 r by the [SQLITE
22720 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c _USE_URI] compil
22730 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a e-time option..*
22740 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 * As of SQLite v
22750 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 ersion 3.7.7, UR
22760 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 I filename inter
22770 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 pretation is tur
22780 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 ned off.** by de
22790 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 fault, but futur
227a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
227b0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c Lite might enabl
227c0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a e URI filename.*
227d0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e * interpretation
227e0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 by default. Se
227f0 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 e "[URI filename
22800 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e s]" for addition
22810 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
22820 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c n..**.** URI fil
22830 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 enames are parse
22840 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 d according to R
22850 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 FC 3986. ^If the
22860 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e URI contains an
22870 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 .** authority, t
22880 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 hen it must be e
22890 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 ither an empty s
228a0 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 tring or the str
228b0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f ing .** "localho
228c0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 st". ^If the aut
228d0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e hority is not an
228e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
228f0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e "localhost", an
22900 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 .** error is re
22910 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 turned to the ca
22920 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d ller. ^The fragm
22930 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ent component of
22940 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 a URI, if .** p
22950 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 resent, is ignor
22960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ed..**.** ^SQLit
22970 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 e uses the path
22980 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 component of the
22990 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 URI as the name
229a0 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c of the disk fil
229b0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 e.** which conta
229c0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ins the database
229d0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 . ^If the path b
229e0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 egins with a '/'
229f0 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 character, .**
22a00 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 then it is inter
22a10 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 preted as an abs
22a20 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 olute path. ^If
22a30 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f the path does no
22a40 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 t begin .** with
22a50 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 a '/' (meaning
22a60 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
22a70 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d ty section is om
22a80 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 itted from the U
22a90 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 RI).** then the
22aa0 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 path is interpre
22ab0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 ted as a relativ
22ac0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 e path. .** ^On
22ad0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 windows, the fir
22ae0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 st component of
22af0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 an absolute path
22b00 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 .** is a drive
22b10 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 specification (e
22b20 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a .g. "C:")..**.**
22b30 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 [[core URI quer
22b40 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a y parameters]].*
22b50 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 * The query comp
22b60 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d onent of a URI m
22b70 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d ay contain param
22b80 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 eters that are i
22b90 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 nterpreted.** ei
22ba0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 ther by SQLite i
22bb0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b tself, or by a [
22bc0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 VFS | custom VFS
22bd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d implementation]
22be0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 ..** SQLite inte
22bf0 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f rprets the follo
22c00 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 wing three query
22c10 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a parameters:.**.
22c20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
22c30 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 > <b>vfs</b>: ^T
22c40 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 he "vfs" paramet
22c50 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 er may be used t
22c60 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 o specify the na
22c70 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 me of.** a V
22c80 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 FS object that p
22c90 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 rovides the oper
22ca0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
22cb0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 erface that shou
22cc0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 ld.** be use
22cd0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 d to access the
22ce0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e database file on
22cf0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 disk. ^If this
22d00 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
22d10 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 .** an empty
22d20 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 string the defa
22d30 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 ult VFS object i
22d40 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 s used. ^Specify
22d50 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a ing an unknown.*
22d60 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 * VFS is an
22d70 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 error. ^If sqlit
22d80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
22d90 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 used and the vfs
22da0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
22db0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 present, then
22dc0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 the VFS specifie
22dd0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 d by the option
22de0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 takes precedence
22df0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 over.** the
22e00 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
22e10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
22e20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
22e30 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
22e40 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 * <li> <b>mode
22e50 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 </b>: ^(The mode
22e60 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
22e70 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
22e80 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a "ro", "rw" or.**
22e90 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 "rwc". Atte
22ea0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
22eb0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
22ec0 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 lue is an error)
22ed0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 ^. .** ^If "
22ee0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 ro" is specified
22ef0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
22f00 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
22f10 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 r read-only .**
22f20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 access, just
22f30 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 as if the [SQLI
22f40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
22f50 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 ] flag had been
22f60 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 set in the .**
22f70 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e third argumen
22f80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 t to sqlite3_pre
22f90 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 pare_v2(). ^If t
22fa0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
22fb0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 s set to .**
22fc0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 "rw", then the
22fd0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
22fe0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 ed for read-writ
22ff0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 e (but not creat
23000 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 e) .** acces
23010 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f s, as if SQLITE_
23020 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 OPEN_READWRITE (
23030 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f but not SQLITE_O
23040 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 PEN_CREATE) had
23050 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 .** been set
23060 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 . ^Value "rwc" i
23070 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
23080 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a setting both .**
23090 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
230a0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 _READWRITE and S
230b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
230c0 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f E. ^If sqlite3_o
230d0 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 pen_v2() is .**
230e0 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 used, it is
230f0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 an error to spec
23100 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 ify a value for
23110 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
23120 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 er that is .**
23130 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 less restrict
23140 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 ive than that sp
23150 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
23160 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74 lags passed as t
23170 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 he third .**
23180 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
23190 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
231a0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
231b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
231c0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
231d0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
231e0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
231f0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
23200 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
23210 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
23220 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
23230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
23240 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
23250 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
23260 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
23270 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
23280 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
23290 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
232a0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
232b0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
232c0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
232d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
232e0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
232f0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
23300 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
23310 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
23320 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
23330 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
23340 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
23350 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
23360 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
23370 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 our requested by
23380 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 setting.**
23390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
233a0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 ATECACHE or SQLI
233b0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
233c0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 CHE flag..** </u
233d0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 l>.**.** ^Specif
233e0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 ying an unknown
233f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
23400 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
23410 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 of a URI is not
23420 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 an.** error. F
23430 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
23440 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 f SQLite might u
23450 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 nderstand additi
23460 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 onal query.** pa
23470 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 rameters. See "
23480 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 [query parameter
23490 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d s with special m
234a0 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 eaning to SQLite
234b0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 ]" for.** additi
234c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
234d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
234e0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d lename examples]
234f0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 ] <h3>URI filena
23500 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e me examples</h3>
23510 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
23520 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 rder="1" align=c
23530 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e enter cellpaddin
23540 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e g=5>.** <tr><th>
23550 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c URI filenames <
23560 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c th> Results.** <
23570 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
23580 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
23590 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
235a0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
235b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
235c0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e rectory..** <tr>
235d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
235e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e fred/data.db<br>
235f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
23600 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 e:///home/fred/d
23610 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 ata.db <br> .**
23620 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
23630 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 localhost/home/f
23640 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
23650 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
23660 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 Open the data
23670 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 base file "/home
23680 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a /fred/data.db"..
23690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
236a0 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 ://darkstar/home
236b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 /fred/data.db <t
236c0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
236d0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 An error. "darks
236e0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 tar" is not a re
236f0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 cognized authori
23700 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 ty..** <tr><td s
23710 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 tyle="white-spac
23720 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 e:nowrap"> .**
23730 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
23740 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 C:/Documents%20a
23750 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 nd%20Settings/fr
23760 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e ed/Desktop/data.
23770 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 db.** <td> W
23780 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 indows only: Ope
23790 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 n the file "data
237a0 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 .db" on fred's d
237b0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a esktop on drive.
237c0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 ** C:.
237d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 Note that the %2
237e0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 0 escaping in th
237f0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f is example is no
23800 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 t strictly .**
23810 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 necessar
23820 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 y - space charac
23830 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 ters can be used
23840 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 literally.**
23850 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 in URI fi
23860 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e lenames..** <tr>
23870 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
23880 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d b?mode=ro&cache=
23890 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a private <td> .**
238a0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
238b0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
238c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
238d0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d ectory for read-
238e0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 only access..**
238f0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c Regardl
23900 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
23910 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 r not shared-cac
23920 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c he mode is enabl
23930 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
23940 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 default, use a
23950 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a private cache..
23960 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
23970 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
23980 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c .db?vfs=unix-nol
23990 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 ock <td>.**
239a0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
239b0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
239c0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 db". Use the spe
239d0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e cial VFS "unix-n
239e0 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c olock"..** <tr><
239f0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
23a00 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c ?mode=readonly <
23a10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
23a20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 An error. "read
23a30 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 only" is not a v
23a40 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 alid option for
23a50 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d the "mode" param
23a60 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eter..** </table
23a70 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 >.**.** ^URI hex
23a80 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
23a90 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 sequences (%HH)
23aa0 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 are supported wi
23ab0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e thin the path an
23ac0 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f d.** query compo
23ad0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 nents of a URI.
23ae0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 A hexadecimal es
23af0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f cape sequence co
23b00 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 nsists of a.** p
23b10 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 ercent sign - "%
23b20 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 " - followed by
23b30 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 exactly two hexa
23b40 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a decimal digits .
23b50 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e ** specifying an
23b60 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 octet value. ^B
23b70 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f efore the path o
23b80 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e r query componen
23b90 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 ts of a.** URI f
23ba0 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 ilename are inte
23bb0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 rpreted, they ar
23bc0 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 e encoded using
23bd0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a UTF-8 and all .*
23be0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 * hexadecimal es
23bf0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 cape sequences r
23c00 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e eplaced by a sin
23c10 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e gle byte contain
23c20 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 ing the.** corre
23c30 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 sponding octet.
23c40 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 If this process
23c50 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 generates an inv
23c60 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 alid UTF-8 encod
23c70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 ing,.** the resu
23c80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
23c90 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 d..**.** <b>Note
23ca0 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 to Windows user
23cb0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f s:</b> The enco
23cc0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 ding used for th
23cd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
23ce0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ent.** of sqlite
23cf0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
23d00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d ite3_open_v2() m
23d10 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
23d20 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
23d30 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
23d40 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
23d50 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
23d60 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
23d70 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
23d80 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
23d90 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
23da0 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
23db0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f into.** sqlite3_
23dc0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
23dd0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 3_open_v2()..*/.
23de0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
23df0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
23e00 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
23e10 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
23e20 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
23e30 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
23e40 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
23e50 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
23e60 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
23e70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
23e80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
23e90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
23ea0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
23eb0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
23ec0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
23ed0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
23ee0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
23ef0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
23f00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
23f10 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
23f20 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
23f30 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
23f40 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
23f50 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
23f60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
23f70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
23f80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
23f90 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
23fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
23fb0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
23fc0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
23fd0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
23fe0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
23ff0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
24000 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 I3REF: Obtain Va
24010 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 lues For URI Par
24020 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 ameters.**.** Th
24030 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 is is a utility
24040 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 routine, useful
24050 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 to VFS implement
24060 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 ations, that che
24070 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 cks.** to see if
24080 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
24090 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 was a URI that
240a0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 contained a spec
240b0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 ific query .** p
240c0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 arameter, and if
240d0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 so obtains the
240e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65 value of the que
240f0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ry parameter..**
24100 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d .** The zFilenam
24110 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 e argument is th
24120 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 e filename point
24130 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 er passed into t
24140 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 he xOpen().** me
24150 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d thod of a VFS im
24160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 plementation. T
24170 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 he zParam argume
24180 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f nt is the name o
24190 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 f the.** query p
241a0 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b arameter we seek
241b0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . This routine
241c0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
241d0 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a e of the zParam.
241e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
241f0 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74 it exists. If t
24200 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65 he parameter doe
24210 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69 s not exist, thi
24220 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 s routine.** ret
24230 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
24240 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ter..**.** If th
24250 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 e zFilename argu
24260 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e ment to this fun
24270 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 ction is not a p
24280 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 ointer that SQLi
24290 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 te.** passed int
242a0 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20 o the xOpen VFS
242b0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 method, then the
242c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 behavior of thi
242d0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 s routine.** is
242e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
242f0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
24300 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 le..*/.SQLITE_AP
24310 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
24320 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
24330 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ter(const char *
24340 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 zFilename, const
24350 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a char *zParam);.
24360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24370 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
24380 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a d Messages.**.**
24390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
243a0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
243b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
243c0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
243d0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
243e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
243f0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
24400 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
24410 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a te3_* API call.*
24420 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
24430 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
24440 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 nnection]. If a
24450 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 prior API call f
24460 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 ailed.** but the
24470 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
24480 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c call succeeded,
24490 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
244a0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 e from.** sqlite
244b0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
244c0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 ndefined. ^The
244d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
244e0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
244f0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
24500 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
24510 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
24520 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
24530 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
24540 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
24550 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
24560 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
24570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
24580 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e ite3_errmsg() an
24590 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 d sqlite3_errmsg
245a0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 16() return Engl
245b0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 ish-language.**
245c0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 text that descri
245d0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 bes the error, a
245e0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
245f0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 r UTF-16 respect
24600 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f ively..** ^(Memo
24610 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
24620 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
24630 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
24640 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
24650 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
24660 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
24670 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
24680 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
24690 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
246a0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
246b0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
246c0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
246d0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
246e0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
246f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
24700 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a functions.)^.**
24710 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 .** When the ser
24720 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
24730 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 ng mode] is in u
24740 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 se, it might be
24750 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 the.** case that
24760 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 a second error
24770 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 occurs on a sepa
24780 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 rate thread in b
24790 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 etween.** the ti
247a0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 me of the first
247b0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 error and the ca
247c0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 ll to these inte
247d0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 rfaces..** When
247e0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 that happens, th
247f0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 e second error w
24800 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 ill be reported
24810 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 since these.** i
24820 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 nterfaces always
24830 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 report the most
24840 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 recent result.
24850 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 To avoid.** thi
24860 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 s, each thread c
24870 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 an obtain exclus
24880 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b ive use of the [
24890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
248a0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 ion] D.** by inv
248b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
248c0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c utex_enter]([sql
248d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
248e0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e )) before beginn
248f0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 ing.** to use D
24900 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 and invoking [sq
24910 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
24920 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d e]([sqlite3_db_m
24930 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a utex](D)) after.
24940 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 ** all calls to
24950 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c the interfaces l
24960 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 isted here are c
24970 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ompleted..**.**
24980 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 If an interface
24990 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 fails with SQLIT
249a0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d E_MISUSE, that m
249b0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 eans the interfa
249c0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 ce.** was invoke
249d0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 d incorrectly by
249e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
249f0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c . In that case,
24a00 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f the.** error co
24a10 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d de and message m
24a20 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 ay or may not be
24a30 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f set..*/.SQLITE_
24a40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
24a50 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
24a60 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
24a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
24a80 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
24a90 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
24aa0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
24ab0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
24ac0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c g(sqlite3*);.SQL
24ad0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
24ae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d id *sqlite3_errm
24af0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a sg16(sqlite3*);.
24b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
24b10 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
24b20 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
24b30 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
24b40 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
24b50 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
24b60 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
24b70 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
24b80 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
24b90 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
24ba0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
24bb0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
24bc0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
24bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
24be0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
24bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
24c00 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
24c10 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
24c20 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
24c30 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
24c40 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
24c50 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
24c60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
24c70 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
24c80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
24c90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
24ca0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
24cb0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
24cc0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
24cd0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
24ce0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
24cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
24d00 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
24d10 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
24d20 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
24d30 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
24d40 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
24d50 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
24d60 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
24d70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24d80 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
24d90 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
24da0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
24db0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
24dc0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
24dd0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
24de0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24df0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
24e00 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
24e10 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
24e20 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
24e30 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
24e40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
24e50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
24e60 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
24e70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
24e80 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
24e90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
24ea0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
24eb0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
24ec0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
24ed0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
24ee0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
24ef0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
24f00 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
24f10 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
24f20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
24f30 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
24f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
24f50 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
24f60 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
24f70 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
24f80 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
24f90 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
24fa0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
24fb0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
24fc0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
24fd0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
24fe0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
24ff0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
25000 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
25010 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
25020 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
25030 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
25040 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
25050 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
25060 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
25070 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
25080 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
25090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
250a0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
250b0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
250c0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
250d0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
250e0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
250f0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
25100 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
25110 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
25120 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
25130 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
25140 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
25150 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
25160 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
25170 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
25180 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
25190 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
251a0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
251b0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
251c0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
251d0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
251e0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
251f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
25200 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
25210 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
25220 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
25230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
25240 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
25250 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
25260 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
25270 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
25280 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
25290 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
252a0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
252b0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
252c0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
252d0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
252e0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
252f0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
25300 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
25310 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
25320 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
25330 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
25340 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
25350 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
25360 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
25370 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
25380 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
25390 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
253a0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
253b0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
253c0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
253d0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
253e0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
253f0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
25400 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
25410 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
25420 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
25430 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
25440 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
25450 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
25460 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
25470 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
25480 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
25490 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
254a0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
254b0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
254c0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
254d0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
254e0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
254f0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
25500 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
25510 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
25520 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
25530 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
25540 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
25550 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
25560 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
25570 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
25580 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
25590 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
255a0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
255b0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
255c0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
255d0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
255e0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
255f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
25600 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
25610 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
25620 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
25630 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
25640 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 eases..*/.SQLITE
25650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
25660 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c _limit(sqlite3*,
25670 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 int id, int new
25680 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Val);../*.** CAP
25690 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
256a0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 Limit Categories
256b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c .** KEYWORDS: {l
256c0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b imit category} {
256d0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 *limit categorie
256e0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
256f0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
25700 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 various performa
25710 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 nce limits.** th
25720 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 at can be lowere
25730 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 d at run-time us
25740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
25750 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 it()]..** The sy
25760 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 nopsis of the me
25770 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
25780 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 rious limits is
25790 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 shown below..**
257a0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 Additional infor
257b0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 mation is availa
257c0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c ble at [limits |
257d0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 Limits in SQLit
257e0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a e]..**.** <dl>.*
257f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
25800 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
25810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
25820 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
25830 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 The maximum size
25840 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f of any string o
25850 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 r BLOB or table
25860 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 row, in bytes.<d
25870 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
25880 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
25890 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
258a0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
258b0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
258c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
258d0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
258e0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 atement, in byte
258f0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
25900 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
25910 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 OLUMN]] ^(<dt>SQ
25920 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
25930 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 N</dt>.** <dd>Th
25940 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
25950 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
25960 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f table definitio
25970 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 n or in the.** r
25980 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
25990 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d SELECT] or the m
259a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
259b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 columns in an i
259c0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e ndex.** or in an
259d0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f ORDER BY or GRO
259e0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 UP BY clause.</d
259f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
25a00 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
25a10 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
25a20 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
25a30 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
25a40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
25a50 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 th of the parse
25a60 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 tree on any expr
25a70 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a ession.</dd>)^.*
25a80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
25a90 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
25aa0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ECT]] ^(<dt>SQLI
25ab0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
25ac0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</dt>.**
25ad0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
25ae0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
25af0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
25b00 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
25b10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
25b20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
25b30 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c E_OP]] ^(<dt>SQL
25b40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
25b50 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
25b60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
25b70 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 of instructions
25b80 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 in a virtual ma
25b90 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a chine program.**
25ba0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
25bb0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d nt an SQL statem
25bc0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 ent. This limit
25bd0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
25be0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 y.** enforced, t
25bf0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 hough that might
25c00 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d be added in som
25c10 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
25c20 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f of.** SQLite.</
25c30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
25c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
25c50 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e ION_ARG]] ^(<dt>
25c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
25c70 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a CTION_ARG</dt>.*
25c80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25c90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 m number of argu
25ca0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 ments on a funct
25cb0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
25cc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
25cd0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 _ATTACHED]] ^(<d
25ce0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
25cf0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
25d00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
25d10 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
25d20 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
25d30 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a abases].)^</dd>.
25d40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
25d50 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
25d60 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 N_LENGTH]].** ^(
25d70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
25d80 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
25d90 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
25da0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
25db0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
25dc0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
25dd0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
25de0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
25df0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
25e00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
25e10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a RIABLE_NUMBER]].
25e20 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
25e30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
25e40 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
25e50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e d>The maximum in
25e60 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e dex number of an
25e70 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e y [parameter] in
25e80 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
25e90 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c t.)^.**.** [[SQL
25ea0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
25eb0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
25ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
25ed0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
25ee0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
25ef0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
25f00 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
25f10 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f rs.</dd>)^.** </
25f20 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
25f30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
25f40 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
25f50 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
25f60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
25f70 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
25f80 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
25f90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
25fa0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
25fb0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
25fc0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
25fd0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
25fe0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
25ff0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26000 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
26010 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
26020 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
26030 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
26040 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
26050 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
26060 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
26070 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
26080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
26090 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
260a0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
260b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
260c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
260d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
260e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
260f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
26100 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
26110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26120 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
26130 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
26140 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
26150 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
26160 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
26170 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
26180 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
26190 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
261a0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
261b0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
261c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
261d0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
261e0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
261f0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
26200 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
26210 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
26220 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
26230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
26240 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
26250 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
26260 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
26270 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
26280 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
26290 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
262a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
262b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
262c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
262d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
262e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
262f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
26300 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
26310 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
26320 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
26330 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
26340 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
26350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
26360 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
26370 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
26380 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
26390 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
263a0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
263b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
263c0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
263d0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 F-16..**.** ^If
263e0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 the nByte argume
263f0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
26400 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 zero, then zSql
26410 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
26420 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
26430 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
26440 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
26450 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
26460 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
26470 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
26480 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
26490 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 . ^When nByte i
264a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
264b0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
264c0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
264d0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
264e0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
264f0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
26500 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
26510 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
26520 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
26530 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
26540 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
26550 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
26560 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
26570 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
26580 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
26590 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
265a0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
265b0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
265c0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
265d0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
265e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
265f0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
26600 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
26610 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
26620 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a rminator bytes..
26630 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c **.** ^If pzTail
26640 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
26650 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 n *pzTail is mad
26660 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
26670 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 e first byte.**
26680 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
26690 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
266a0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
266b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
266c0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 only.** compile
266d0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
266e0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f ment in zSql, so
266f0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 *pzTail is left
26700 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 pointing to.**
26710 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 what remains unc
26720 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ompiled..**.** ^
26730 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 *ppStmt is left
26740 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f pointing to a co
26750 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 mpiled [prepared
26760 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
26770 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 can be.** execu
26780 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
26790 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 e3_step()]. ^If
267a0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
267b0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
267c0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
267d0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 ^If the input te
267e0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
267f0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
26800 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
26810 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
26820 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
26830 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
26840 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 ..** The calling
26850 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 procedure is re
26860 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 sponsible for de
26870 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 leting the compi
26880 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 led.** SQL state
26890 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
268a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
268b0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
268c0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
268d0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 * ppStmt may not
268e0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
268f0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 ^On success, the
26900 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
26910 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 () family of rou
26920 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
26930 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 LITE_OK];.** oth
26940 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
26950 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
26960 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
26970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
26980 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
26990 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
269a0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
269b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
269c0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
269d0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
269e0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
269f0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
26a00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
26a10 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
26a20 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
26a30 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
26a40 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
26a50 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
26a60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
26a70 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
26a80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
26a90 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
26aa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
26ab0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
26ac0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
26ad0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
26ae0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
26af0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
26b00 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
26b10 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
26b20 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
26b30 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
26b40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
26b50 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
26b60 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
26b70 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
26b80 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
26b90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
26ba0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
26bb0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
26bc0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
26bd0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
26be0 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 un it again..**
26bf0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
26c00 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 .** ^When an err
26c10 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
26c20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
26c30 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
26c40 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
26c50 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
26c60 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
26c70 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 codes]. ^The le
26c80 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
26c90 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
26ca0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
26cb0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
26cc0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
26cd0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
26ce0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 e.** and the app
26cf0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 lication would h
26d00 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
26d10 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
26d20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
26d30 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 * in order to fi
26d40 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
26d50 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
26d60 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
26d70 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
26d80 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
26d90 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
26da0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
26db0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
26dc0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
26dd0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
26de0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
26df0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f c value bound to
26e00 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f [parameter | ho
26e10 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e st parameter] in
26e20 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 the .** WHERE c
26e30 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c lause might infl
26e40 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 uence the choice
26e50 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 of query plan f
26e60 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a or a statement,.
26e70 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 ** then the stat
26e80 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 ement will be au
26e90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
26ea0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 mpiled, as if th
26eb0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a ere had been .**
26ec0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
26ed0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 , on the first
26ee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
26ef0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 call following
26f00 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f any change.** to
26f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
26f20 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e nd_text | bindin
26f30 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 gs] of that [par
26f40 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 ameter]. .** ^Th
26f50 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
26f60 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 of WHERE-clause
26f70 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 [parameter] mig
26f80 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
26f90 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 .** choice of q
26fa0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 uery plan if the
26fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
26fc0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 e left-hand side
26fd0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 of a [LIKE].**
26fe0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 or [GLOB] operat
26ff0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 or or if the par
27000 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 ameter is compar
27010 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 ed to an indexed
27020 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 column.** and t
27030 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c he [SQLITE_ENABL
27040 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 E_STAT2] compile
27050 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
27060 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 enabled..** the
27070 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f .** </li>.** </o
27080 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l>.*/.SQLITE_API
27090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 int sqlite3_pre
270a0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 pare(. sqlite3
270b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
270c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
270d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
270e0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
270f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
27100 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
27110 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
27120 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
27130 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
27140 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
27150 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
27160 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
27170 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
27180 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
27190 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
271a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
271b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
271c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
271d0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
271e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
271f0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 re_v2(. sqlite3
27200 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
27210 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
27220 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
27230 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
27240 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
27250 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
27260 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
27280 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
27290 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
272a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
272b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
272c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
272d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
272e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
272f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
27300 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
27310 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
27320 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
27330 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
27340 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
27350 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
27360 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
27370 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
27380 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
27390 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
273a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
273b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
273c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
273d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
273e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
273f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
27400 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
27410 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
27420 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
27430 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
27440 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
27450 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
27460 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
27470 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
27480 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 int sqlite3_pre
27490 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
274a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
274b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
274c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
274d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
274e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
274f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
27500 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
27510 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
27520 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
27530 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
27540 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
27550 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
27560 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
27570 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
27580 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
27590 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
275a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
275b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
275c0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a Sql */.);../*.**
275d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
275e0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
275f0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 SQL.**.** ^This
27600 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
27610 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
27620 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
27630 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
27640 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
27650 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
27660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27670 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
27680 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
27690 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
276a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
276b0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
276c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
276d0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
276e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
276f0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 lite3_sql(sqlite
27700 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
27710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27720 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
27730 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 SQL Statement W
27740 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 rites The Databa
27750 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 se.**.** ^The sq
27760 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
27770 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 nly(X) interface
27780 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e returns true (n
27790 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 on-zero) if.** a
277a0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b nd only if the [
277b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
277c0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 nt] X makes no d
277d0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f irect changes to
277e0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
277f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
27800 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 file..**.** Note
27810 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 that [applicati
27820 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
27830 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 unctions] or.**
27840 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
27850 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 might change th
27860 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 e database indir
27870 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 ectly as a side
27880 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 effect. .** ^(F
27890 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 or example, if a
278a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 n application de
278b0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e fines a function
278c0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a "eval()" that .
278d0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 ** calls [sqlite
278e0 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 3_exec()], then
278f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 the following SQ
27900 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c L statement woul
27910 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 d.** change the
27920 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 database file th
27930 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 rough side-effec
27940 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ts:.**.** <block
27950 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
27960 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 SELECT eval('D
27970 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 ELETE FROM t1')
27980 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 FROM t2;.** </pr
27990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
279a0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 **.** But becaus
279b0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 e the [SELECT] s
279c0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
279d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 t change the dat
279e0 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 abase file.** di
279f0 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f rectly, sqlite3_
27a00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 stmt_readonly()
27a10 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 would still retu
27a20 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a rn true.)^.**.**
27a30 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f ^Transaction co
27a40 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 ntrol statements
27a50 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d such as [BEGIN]
27a60 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c , [COMMIT], [ROL
27a70 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 LBACK],.** [SAVE
27a80 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c POINT], and [REL
27a90 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 EASE] cause sqli
27aa0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
27ab0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
27ac0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 ue,.** since the
27ad0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d statements them
27ae0 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 selves do not ac
27af0 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 tually modify th
27b00 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a e database but.*
27b10 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f * rather they co
27b20 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 ntrol the timing
27b30 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 of when other s
27b40 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 tatements modify
27b50 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 the .** databas
27b60 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 e. ^The [ATTACH
27b70 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 ] and [DETACH] s
27b80 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 tatements also c
27b90 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ause.** sqlite3_
27ba0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 stmt_readonly()
27bb0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 to return true s
27bc0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 ince, while thos
27bd0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 e statements.**
27be0 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 change the confi
27bf0 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 guration of a da
27c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
27c10 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d n, they do not m
27c20 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 ake .** changes
27c30 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f to the content o
27c40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
27c50 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f iles on disk..*/
27c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
27c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
27c80 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 donly(sqlite3_st
27c90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
27ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
27cb0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
27cc0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
27cd0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
27ce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
27cf0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
27d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
27d10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
27d20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
27d30 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
27d40 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
27d50 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
27d60 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
27d70 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
27d80 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
27d90 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
27da0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
27db0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
27dc0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
27dd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
27de0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
27df0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
27e00 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
27e10 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
27e20 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
27e30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
27e40 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
27e50 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
27e60 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
27e70 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
27e80 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
27e90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27ea0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
27eb0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
27ec0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
27ed0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
27ee0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
27ef0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
27f00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
27f10 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
27f20 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
27f30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
27f40 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
27f50 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
27f60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
27f80 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
27f90 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
27fa0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
27fb0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
27fc0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 ex is held. An
27fd0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
27fe0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
27ff0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
28000 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
28010 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
28020 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
28030 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
28040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
28050 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
28060 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
28070 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
28080 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
28090 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
280a0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
280b0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
280c0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
280d0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
280e0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
280f0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
28100 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
28110 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
28120 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
28130 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
28140 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
28150 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
28160 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
28170 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
28180 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
28190 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
281a0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
281b0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
281c0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
281d0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
281e0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
281f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
28200 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
28210 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
28220 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
28230 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
28240 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
28250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
28260 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
28270 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
28280 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
28290 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
282a0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
282b0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
282c0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
282d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
282e0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
282f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
28300 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
28310 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
28320 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
28330 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
28340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
28350 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
28360 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
28370 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
28380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
28390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
283a0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
283b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
283c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
283d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
283e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
283f0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
28400 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
28410 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
28420 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
28430 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
28440 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
28450 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
28460 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
28470 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
28480 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
28490 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
284a0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
284b0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
284c0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
284d0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
284e0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
284f0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
28500 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
28510 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
28520 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
28530 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
28540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
28550 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
28560 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
28570 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
28580 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
28590 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
285a0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
285b0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
285c0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
285d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
285e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
285f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
28600 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
28610 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
28620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
28630 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
28640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
28650 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
28660 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
28670 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
28680 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
28690 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
286a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
286b0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
286c0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
286d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
286e0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
286f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
28700 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
28710 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
28720 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
28730 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
28740 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
28750 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
28760 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
28770 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
28780 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a r binding}.**.**
28790 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ^(In the SQL st
287a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 atement text inp
287b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
287c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
287d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
287e0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
287f0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
28800 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
28810 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
28820 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
28830 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
28840 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
28850 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
28860 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
28870 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
28880 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
28890 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
288a0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
288b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
288c0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
288d0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
288e0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
288f0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 meric identifier
28900 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 .)^ ^The values
28910 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 of these.** par
28920 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 ameters (also ca
28930 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d lled "host param
28940 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 eter names" or "
28950 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 SQL parameters")
28960 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 .** can be set u
28970 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
28980 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
28990 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e es defined here.
289a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
289b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
289c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
289d0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
289e0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
289f0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
28a00 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
28a10 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
28a20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28a30 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
28a40 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e ariants..**.** ^
28a50 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
28a60 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
28a70 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 of the SQL para
28a80 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e meter to be set.
28a90 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 .** ^The leftmos
28aa0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 t SQL parameter
28ab0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
28ac0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 1. ^When the sa
28ad0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
28ae0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
28af0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
28b00 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
28b10 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
28b20 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
28b30 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
28b40 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
28b50 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 ce..** ^The inde
28b60 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 x for named para
28b70 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f meters can be lo
28b80 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 oked up using th
28b90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 e.** [sqlite3_bi
28ba0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
28bb0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 ex()] API if des
28bc0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 ired. ^The inde
28bd0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 x.** for "?NNN"
28be0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 parameters is th
28bf0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a e value of NNN..
28c00 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 ** ^The NNN valu
28c10 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
28c20 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
28c30 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
28c40 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
28c50 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
28c60 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
28c70 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
28c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
28c90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
28ca0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 value to bind t
28cb0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e o the parameter.
28cc0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
28cd0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
28ce0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
28cf0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
28d00 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
28d10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
28d20 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
28d30 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
28d40 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
28d50 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
28d60 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
28d70 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
28d80 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
28d90 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
28da0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
28db0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
28dc0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
28dd0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 string is.** the
28de0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
28df0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
28e00 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
28e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 ..**.** ^The fif
28e20 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
28e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
28e40 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 (), sqlite3_bind
28e50 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 _text(), and.**
28e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
28e70 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 t16() is a destr
28e80 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 uctor used to di
28e90 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
28ea0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 B or.** string a
28eb0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 fter SQLite has
28ec0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
28ed0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 . ^The destruct
28ee0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 or is called.**
28ef0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
28f00 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 e BLOB or string
28f10 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c even if the cal
28f20 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e l to sqlite3_bin
28f30 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c d_blob(),.** sql
28f40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
28f50 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e , or sqlite3_bin
28f60 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 d_text16() fails
28f70 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 . .** ^If the f
28f80 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
28f90 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
28fa0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 value [SQLITE_ST
28fb0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 ATIC], then SQLi
28fc0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
28fd0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 the.** informati
28fe0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c on is in static,
28ff0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 unmanaged space
29000 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 and does not ne
29010 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a ed to be freed..
29020 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
29030 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 argument has th
29040 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f e value [SQLITE_
29050 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e TRANSIENT], then
29060 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 .** SQLite makes
29070 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
29080 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 copy of the dat
29090 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 a immediately, b
290a0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c efore.** the sql
290b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
290c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a utine returns..*
290d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
290e0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
290f0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 ) routine binds
29100 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 a BLOB of length
29110 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 N that.** is fi
29120 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 lled with zeroes
29130 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 . ^A zeroblob u
29140 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 ses a fixed amou
29150 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 nt of memory.**
29160 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 (just an integer
29170 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a to hold its siz
29180 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
29190 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
291a0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
291b0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
291c0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 ve as placeholde
291d0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f rs for BLOBs who
291e0 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 se.** content is
291f0 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 later written u
29200 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
29210 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 _blob_open | inc
29220 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f remental BLOB I/
29230 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 O] routines..**
29240 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 ^A negative valu
29250 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c e for the zerobl
29260 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 ob results in a
29270 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
29280 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 ..**.** ^If any
29290 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 of the sqlite3_b
292a0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
292b0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 are called with
292c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
292d0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 ** for the [prep
292e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
292f0 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 or with a prepar
29300 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 ed statement for
29310 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 which.** [sqlit
29320 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 e3_step()] has b
29330 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 een called more
29340 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 recently than [s
29350 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
29360 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c .** then the cal
29370 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 l will return [S
29380 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
29390 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 If any sqlite3_b
293a0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ind_().** routin
293b0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 e is passed a [p
293c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
293d0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e t] that has been
293e0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a finalized, the.
293f0 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 ** result is und
29400 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
29410 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
29420 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 ** ^Bindings are
29430 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 not cleared by
29440 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 the [sqlite3_res
29450 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a et()] routine..*
29460 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d * ^Unbound param
29470 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 eters are interp
29480 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a reted as NULL..*
29490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
294a0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 3_bind_* routine
294b0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
294c0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
294d0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 or an.** [error
294e0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e code] if anythin
294f0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
29500 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d ^[SQLITE_RANGE]
29510 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
29520 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
29530 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
29540 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 range. ^[SQLIT
29550 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
29560 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
29570 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 fails..**.** Se
29580 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
29590 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
295a0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 count()],.** [sq
295b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
295c0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
295d0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
295e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
295f0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
29600 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
29610 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f nd_blob(sqlite3_
29620 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
29630 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 t void*, int n,
29640 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
29650 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
29670 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
29680 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
29690 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
296a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
296b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
296c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 int, int);.SQLIT
296d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
296e0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
296f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
29700 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
29710 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29720 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c sqlite3_bind_nul
29730 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c l(sqlite3_stmt*,
29740 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
29750 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
29760 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f nd_text(sqlite3_
29770 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
29780 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 t char*, int n,
29790 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
297a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
297b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
297c0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
297d0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
297e0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
297f0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
29800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
29810 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 3_bind_value(sql
29820 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
29830 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 const sqlite3_v
29840 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
29850 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
29860 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ind_zeroblob(sql
29870 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
29880 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
29890 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
298a0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
298b0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 rs.**.** ^This r
298c0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 outine can be us
298d0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
298e0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 umber of [SQL pa
298f0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 rameters].** in
29900 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
29910 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 ement]. SQL par
29920 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 ameters are toke
29930 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ns of the.** for
29940 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 m "?", "?NNN", "
29950 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f :AAA", "$AAA", o
29960 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 r "@AAA" that se
29970 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 rve as.** placeh
29980 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 olders for value
29990 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 s that are [sqli
299a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
299b0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 bound].** to the
299c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 parameters at a
299d0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a later time..**.
299e0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e ** ^(This routin
299f0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 e actually retur
29a00 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 ns the index of
29a10 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 the largest (rig
29a20 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d htmost).** param
29a30 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f eter. For all fo
29a40 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c rms except ?NNN,
29a50 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 this will corre
29a60 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 spond to the.**
29a70 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 number of unique
29a80 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 parameters. If
29a90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
29aa0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 he ?NNN form are
29ab0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 used,.** there
29ac0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 may be gaps in t
29ad0 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a he list.)^.**.**
29ae0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
29af0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
29b00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
29b10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
29b20 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
29b30 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
29b40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
29b50 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
29b60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
29b70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
29b80 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 eter_count(sqlit
29b90 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
29ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
29bb0 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d Of A Host Param
29bc0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eter.**.** ^The
29bd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
29be0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
29bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
29c00 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
29c10 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
29c20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
29c30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29c40 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
29c50 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
29c60 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
29c70 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
29c80 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
29c90 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
29ca0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
29cb0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
29cc0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
29cd0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
29ce0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
29cf0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
29d00 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
29d10 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
29d20 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
29d30 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
29d40 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
29d50 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
29d60 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
29d70 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
29d80 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
29d90 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
29da0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
29db0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
29dc0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
29dd0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
29de0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
29df0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
29e00 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
29e10 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
29e20 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
29e30 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
29e40 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
29e50 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
29e60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
29e70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
29e80 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
29e90 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
29ea0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
29eb0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
29ec0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
29ed0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
29ee0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
29ef0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
29f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
29f10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
29f20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
29f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
29f40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
29f50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
29f60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
29f70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
29f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
29f90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
29fa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
29fb0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
29fc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
29fd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
29fe0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
29ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
2a000 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
2a010 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
2a020 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e me.**.** ^Return
2a030 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
2a040 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 SQL parameter g
2a050 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 iven its name.
2a060 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 ^The.** index va
2a070 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
2a080 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 suitable for use
2a090 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
2a0a0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b * parameter to [
2a0b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2a0c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2a0d0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 ]. ^A zero.** i
2a0e0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
2a0f0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
2a100 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e ter is found. ^
2a110 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a The parameter.**
2a120 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 name must be gi
2a130 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 ven in UTF-8 eve
2a140 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 n if the origina
2a150 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 l statement.** w
2a160 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d as prepared from
2a170 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 UTF-16 text usi
2a180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
2a190 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
2a1a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2a1b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2a1c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2a1d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2a1e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2a1f0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
2a200 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2a210 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
2a220 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2a240 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 rameter_index(sq
2a250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e lite3_stmt*, con
2a260 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
2a270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a280 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 : Reset All Bind
2a290 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 ings On A Prepar
2a2a0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a ed Statement.**.
2a2b0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 ** ^Contrary to
2a2c0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 the intuition of
2a2d0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f many, [sqlite3_
2a2e0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f reset()] does no
2a2f0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b t reset.** the [
2a300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2a310 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e b | bindings] on
2a320 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2a330 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 tement]..** ^Use
2a340 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f this routine to
2a350 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 reset all host
2a360 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 parameters to NU
2a370 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 LL..*/.SQLITE_AP
2a380 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c I int sqlite3_cl
2a390 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c ear_bindings(sql
2a3a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2a3b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2a3c0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 mber Of Columns
2a3d0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2a3e0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
2a3f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
2a400 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
2a410 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
2a420 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
2a430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
2a440 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
2a450 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 urns 0 if pStmt
2a460 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 is an SQL.** sta
2a470 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 tement that does
2a480 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 not return data
2a490 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e (for example an
2a4a0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a [UPDATE])..**.*
2a4b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2a4c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2a4d0 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )].*/.SQLITE_API
2a4e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
2a4f0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
2a500 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2a510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2a520 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
2a530 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
2a540 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2a550 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e nes return the n
2a560 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 ame assigned to
2a570 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c a particular col
2a580 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 umn.** in the re
2a590 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
2a5a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2a5b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
2a5c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a column_name().**
2a5d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2a5e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2a5f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2a600 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a d UTF-8 string.*
2a610 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
2a620 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 lumn_name16() re
2a630 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2a640 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2a650 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 ated.** UTF-16 s
2a660 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 tring. ^The fir
2a670 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2a680 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2a690 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 atement].** that
2a6a0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
2a6b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2a6c0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 nt. ^The second
2a6d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2a6e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 .** column numbe
2a6f0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 r. ^The leftmos
2a700 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 t column is numb
2a710 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er 0..**.** ^The
2a720 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2a730 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 pointer is vali
2a740 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 d until either t
2a750 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2a760 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 tement].** is de
2a770 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
2a780 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2a790 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2a7a0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2a7b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2a7c0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2a7d0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2a7e0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2a7f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2a800 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2a810 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a next call to.**
2a820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a830 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 name() or sqlite
2a840 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
2a850 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f ) on the same co
2a860 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 lumn..**.** ^If
2a870 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2a880 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 fails during th
2a890 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 e processing of
2a8a0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a either routine.*
2a8b0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 * (for example d
2a8c0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 uring a conversi
2a8d0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f on from UTF-8 to
2a8e0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a UTF-16) then a.
2a8f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
2a900 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2a910 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
2a920 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 a result column
2a930 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
2a940 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 the "AS" clause
2a950 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 for.** that colu
2a960 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 mn, if there is
2a970 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 an AS clause. I
2a980 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 f there is no AS
2a990 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 clause.** then
2a9a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2a9b0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 column is unspec
2a9c0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 ified and may ch
2a9d0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 ange from.** one
2a9e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2a9f0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a te to the next..
2aa00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2aa10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2aa20 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
2aa30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2aa40 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 N);.SQLITE_API
2aa50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2aa60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
2aa70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2aa80 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int N);../*.**
2aa90 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 CAPI3REF: Source
2aaa0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 Of Data In A Qu
2aab0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a ery Result.**.**
2aac0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2aad0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 provide a means
2aae0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 to determine th
2aaf0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c e database, tabl
2ab00 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 e, and.** table
2ab10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 column that is t
2ab20 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 he origin of a p
2ab30 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 articular result
2ab40 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 column in.** [S
2ab50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2ab60 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f ..** ^The name o
2ab70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
2ab80 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
2ab90 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
2aba0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
2abb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
2abc0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f string. ^The _
2abd0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e database_ routin
2abe0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 es return.** the
2abf0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 database name,
2ac00 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 the _table_ rout
2ac10 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
2ac20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a table name, and.
2ac30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 ** the origin_ r
2ac40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2ac50 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a he column name..
2ac60 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
2ac70 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
2ac80 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
2ac90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2aca0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
2acb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
2acc0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2acd0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2ace0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2acf0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2ad00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2ad10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2ad20 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2ad30 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2ad40 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
2ad50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2ad60 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
2ad70 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
2ad80 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
2ad90 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 * ^The names ret
2ada0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
2adb0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
2adc0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
2add0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
2ade0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
2adf0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2ae00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 argument to thes
2ae10 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 e interfaces is
2ae20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2ae30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 ement]..** ^Thes
2ae40 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
2ae50 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
2ae60 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 bout the Nth res
2ae70 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 ult column retur
2ae80 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
2ae90 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
2aea0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
2aeb0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
2aec0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d ..** ^The left-m
2aed0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f ost column is co
2aee0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 lumn 0 for these
2aef0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
2af00 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
2af10 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
2af20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2af30 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
2af40 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e r.** subquery an
2af50 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
2af60 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
2af70 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
2af80 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e ions return.** N
2af90 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 ULL. ^These rou
2afa0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 tine might also
2afb0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 return NULL if a
2afc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
2afd0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 on error.** occu
2afe0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c rs. ^Otherwise,
2aff0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 they return the
2b000 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
2b010 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
2b020 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c table,.** or col
2b030 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 umn that query r
2b040 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 esult column was
2b050 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e extracted from.
2b060 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 .**.** ^As with
2b070 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 all other SQLite
2b080 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f APIs, those who
2b090 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 se names end wit
2b0a0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
2b0b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
2b0c0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 strings and the
2b0d0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 other functions
2b0e0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a return UTF-8..**
2b0f0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 .** ^These APIs
2b100 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
2b110 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
2b120 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
2b130 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
2b140 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
2b150 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
2b160 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
2b170 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
2b180 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
2b190 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 all one or more
2b1a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2b1b0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 s against the sa
2b1c0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 me.** prepared s
2b1d0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c tatement and col
2b1e0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 umn at the same
2b1f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2b200 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 sults are.** und
2b210 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 efined..**.** If
2b220 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
2b230 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
2b240 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 more.** [sqlite
2b250 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2b260 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 e_name | column
2b270 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 metadata interfa
2b280 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ces].** for the
2b290 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
2b2a0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 tatement] and re
2b2b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 sult column.** a
2b2c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
2b2d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
2b2e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
2b2f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2b300 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2b310 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2b320 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
2b330 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2b340 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2b350 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2b360 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 _database_name16
2b370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2b380 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2b390 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2b3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
2b3b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2b3c0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2b3d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2b3e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b3f0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c table_name16(sql
2b400 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2b410 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2b420 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2b430 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
2b440 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2b450 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2b460 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2b470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
2b480 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
2b490 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
2b4a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2b4b0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
2b4c0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
2b4d0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ult.**.** ^(The
2b4e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2b4f0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
2b500 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 tatement]..** If
2b510 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 this statement
2b520 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 is a [SELECT] st
2b530 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 atement and the
2b540 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
2b550 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 e.** returned re
2b560 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 sult set of that
2b570 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 [SELECT] is a t
2b580 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 able column (not
2b590 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
2b5a0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 n or subquery) t
2b5b0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 hen the declared
2b5c0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 type of the tab
2b5d0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 le.** column is
2b5e0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 returned.)^ ^If
2b5f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2b600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2b610 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
2b620 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
2b630 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
2b640 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
2b650 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 ed..** ^The retu
2b660 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
2b670 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
2b680 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
2b690 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 example, given
2b6a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
2b6b0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 ema:.**.** CREAT
2b6c0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 E TABLE t1(c1 VA
2b6d0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e RIANT);.**.** an
2b6e0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 d the following
2b6f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
2b700 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 compiled:.**.**
2b710 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 SELECT c1 + 1, c
2b720 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 1 FROM t1;.**.**
2b730 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f this routine wo
2b740 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 uld return the s
2b750 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 tring "VARIANT"
2b760 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 for the second r
2b770 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 esult.** column
2b780 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 (i==1), and a NU
2b790 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 LL pointer for t
2b7a0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 he first result
2b7b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e column (i==0).)^
2b7c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
2b7d0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
2b7e0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 time typing. ^S
2b7f0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 o just because a
2b800 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 column.** is de
2b810 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 clared to contai
2b820 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 n a particular t
2b830 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 ype does not mea
2b840 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 n that the.** da
2b850 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 ta stored in tha
2b860 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 t column is of t
2b870 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
2b880 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 . SQLite is.**
2b890 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 strongly typed,
2b8a0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 but the typing i
2b8b0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 s dynamic not st
2b8c0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 atic. ^Type.**
2b8d0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
2b8e0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
2b8f0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
2b900 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
2b910 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
2b920 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 ose values..*/.S
2b930 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2b940 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2b950 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
2b960 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2b970 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2b980 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2b990 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
2b9a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2b9b0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ,int);../*.** CA
2b9c0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 PI3REF: Evaluate
2b9d0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2b9e0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 t.**.** After a
2b9f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ba00 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 ent] has been pr
2ba10 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 epared using eit
2ba20 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
2ba30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2ba40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2ba50 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 e16_v2()] or one
2ba60 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a of the legacy.*
2ba70 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 * interfaces [sq
2ba80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
2ba90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2baa0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 pare16()], this
2bab0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 function.** must
2bac0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f be called one o
2bad0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
2bae0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 evaluate the sta
2baf0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 tement..**.** Th
2bb00 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
2bb10 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 behavior of the
2bb20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2bb30 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 interface depend
2bb40 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 .** on whether t
2bb50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
2bb60 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
2bb70 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 the newer "v2" i
2bb80 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c nterface.** [sql
2bb90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2bba0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2bbb0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
2bbc0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 or the older leg
2bbd0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
2bbe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2bbf0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2bc00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 3_prepare16()].
2bc10 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a The use of the.
2bc20 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 ** new "v2" inte
2bc30 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 rface is recomme
2bc40 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 nded for new app
2bc50 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 lications but th
2bc60 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
2bc70 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 rface will conti
2bc80 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 nue to be suppor
2bc90 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ted..**.** ^In t
2bca0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2bcb0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
2bcc0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
2bcd0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
2bce0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
2bcf0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
2bd00 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
2bd10 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
2bd20 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 ISUSE]..** ^With
2bd30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
2bd40 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 ace, any of the
2bd50 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f other [result co
2bd60 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 des] or.** [exte
2bd70 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
2bd80 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 s] might be retu
2bd90 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a rned as well..**
2bda0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 .** ^[SQLITE_BUS
2bdb0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
2bdc0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
2bdd0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
2bde0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
2bdf0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
2be00 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
2be10 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 job. ^If the s
2be20 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
2be30 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
2be40 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
2be50 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
2be60 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
2be70 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
2be80 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
2be90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2bea0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
2beb0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
2bec0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 in an.** explici
2bed0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
2bee0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
2bef0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
2bf00 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
2bf10 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
2bf20 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ** ^[SQLITE_DONE
2bf30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2bf40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
2bf50 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
2bf60 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
2bf70 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
2bf80 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
2bf90 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
2bfa0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
2bfb0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
2bfc0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
2bfd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2bfe0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
2bff0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
2c000 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
2c010 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
2c020 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 * ^If the SQL st
2c030 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
2c040 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
2c050 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
2c060 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
2c070 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
2c080 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
2c090 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
2c0a0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
2c0b0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
2c0c0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
2c0d0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
2c0e0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
2c0f0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
2c100 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
2c110 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
2c120 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
2c130 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
2c140 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ta..**.** ^[SQLI
2c150 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 TE_ERROR] means
2c160 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 that a run-time
2c170 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 error (such as a
2c180 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 constraint.** v
2c190 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 iolation) has oc
2c1a0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 curred. sqlite3
2c1b0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
2c1c0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
2c1d0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e in on.** the VM.
2c1e0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f More informatio
2c1f0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 n may be found b
2c200 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
2c210 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a e3_errmsg()]..**
2c220 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 ^With the legac
2c230 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d y interface, a m
2c240 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
2c250 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 or code (for exa
2c260 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 mple,.** [SQLITE
2c270 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 _INTERRUPT], [SQ
2c280 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 LITE_SCHEMA], [S
2c290 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 QLITE_CORRUPT],
2c2a0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a and so forth).**
2c2b0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
2c2c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
2c2d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e ite3_reset()] on
2c2e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2c2f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e d statement]. ^
2c300 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
2c310 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f rface,.** the mo
2c320 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2c330 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
2c340 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 ed directly by s
2c350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a qlite3_step()..*
2c360 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 *.** [SQLITE_MIS
2c370 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USE] means that
2c380 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 the this routine
2c390 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 was called inap
2c3a0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 propriately..**
2c3b0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 Perhaps it was c
2c3c0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 alled on a [prep
2c3d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2c3e0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 that has.** alre
2c3f0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 ady been [sqlite
2c400 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2c410 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e alized] or on on
2c420 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 e that had.** pr
2c430 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
2c440 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d d [SQLITE_ERROR]
2c450 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
2c460 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a ]. Or it could.
2c470 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 ** be the case t
2c480 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 hat the same dat
2c490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c4a0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 is being used b
2c4b0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 y two or.** more
2c4c0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
2c4d0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 same moment in t
2c4e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 ime..**.** For a
2c4f0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ll versions of S
2c500 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 QLite up to and
2c510 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 including 3.6.23
2c520 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a .1, a call to.**
2c530 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c540 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 )] was required
2c550 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 after sqlite3_st
2c560 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e ep() returned an
2c570 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 ything.** other
2c580 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
2c590 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 ] before any sub
2c5a0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
2c5b0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 on of.** sqlite3
2c5c0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 _step(). Failur
2c5d0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 e to reset the p
2c5e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c5f0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c t using .** [sql
2c600 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f ite3_reset()] wo
2c610 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e uld result in an
2c620 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2c630 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 return from.**
2c640 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
2c650 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 But after versi
2c660 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c on 3.6.23.1, sql
2c670 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 ite3_step() bega
2c680 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 n.** calling [sq
2c690 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
2c6a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 utomatically in
2c6b0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 this circumstanc
2c6c0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e e rather.** than
2c6d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
2c6e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 TE_MISUSE]. Thi
2c6f0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 s is not conside
2c700 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c red a compatibil
2c710 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 ity.** break bec
2c720 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 ause any applica
2c730 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 tion that ever r
2c740 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 eceives an SQLIT
2c750 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a E_MISUSE error.*
2c760 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 * is broken by d
2c770 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 efinition. The
2c780 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
2c790 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d ORESET] compile-
2c7a0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 time option.** c
2c7b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
2c7c0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 store the legacy
2c7d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
2c7e0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 <b>Goofy Interf
2c7f0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 ace Alert:</b> I
2c800 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
2c810 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 erface, the sqli
2c820 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 te3_step().** AP
2c830 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 I always returns
2c840 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 a generic error
2c850 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 code, [SQLITE_E
2c860 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 RROR], following
2c870 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 any.** error ot
2c880 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
2c890 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 _BUSY] and [SQLI
2c8a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 TE_MISUSE]. You
2c8b0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 must call.** [s
2c8c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c8d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
2c8e0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 lize()] in order
2c8f0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 to find one of
2c900 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
2c910 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 [error codes] th
2c920 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 at better descri
2c930 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a bes the error..*
2c940 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 * We admit that
2c950 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 this is a goofy
2c960 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f design. The pro
2c970 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 blem has been fi
2c980 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 xed.** with the
2c990 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 "v2" interface.
2c9a0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 If you prepare
2c9b0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 all of your SQL
2c9c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 statements.** us
2c9d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 ing either [sqli
2c9e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2c9f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
2ca00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e epare16_v2()] in
2ca10 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 stead.** of the
2ca20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f legacy [sqlite3_
2ca30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
2ca40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2ca50 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 6()] interfaces,
2ca60 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 .** then the mor
2ca70 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f e specific [erro
2ca80 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 r codes] are ret
2ca90 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a urned directly.*
2caa0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 * by sqlite3_ste
2cab0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 p(). The use of
2cac0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
2cad0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ace is recommend
2cae0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ed..*/.SQLITE_AP
2caf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 I int sqlite3_st
2cb00 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
2cb10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2cb20 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
2cb30 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
2cb40 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 t set.**.** ^The
2cb50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2cb60 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 unt(P) interface
2cb70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2cb80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2cb90 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
2cba0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2cbb0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
2cbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2cbd0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 ..** ^If prepare
2cbe0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f d statement P do
2cbf0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 es not have resu
2cc00 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 lts ready to ret
2cc10 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c urn.** (via call
2cc20 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
2cc30 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 3_column_int | s
2cc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 qlite3_column_*(
2cc50 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 )] of.** interfa
2cc60 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 ces) then sqlite
2cc70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2cc80 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 returns 0..** ^T
2cc90 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2cca0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
2ccb0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 also returns 0
2ccc0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 if P is a NULL p
2ccd0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 ointer..**.** Se
2cce0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2ccf0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
2cd00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2cd10 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f nt sqlite3_data_
2cd20 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2cd30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2cd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
2cd50 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 damental Datatyp
2cd60 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
2cd70 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
2cd80 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 * ^(Every value
2cd90 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
2cda0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
2cdb0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
2cdc0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2cdd0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
2cde0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
2cdf0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
2ce00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
2ce10 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
2ce20 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
2ce30 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
2ce40 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
2ce50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
2ce60 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 e codes for each
2ce70 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e of those types.
2ce80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
2ce90 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 the SQLITE_TEXT
2cea0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c constant was al
2ceb0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 so used in SQLit
2cec0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 e version 2.** f
2ced0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 or a completely
2cee0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e different meanin
2cef0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 g. Software tha
2cf00 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 t links against
2cf10 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 both.** SQLite v
2cf20 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c ersion 2 and SQL
2cf30 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 ite version 3 sh
2cf40 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 ould use SQLITE3
2cf50 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 _TEXT, not.** SQ
2cf60 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 LITE_TEXT..*/.#d
2cf70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
2cf80 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 EGER 1.#define
2cf90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 SQLITE_FLOAT
2cfa0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2cfb0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 _BLOB 4.#def
2cfc0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 ine SQLITE_NULL
2cfd0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 5.#ifdef SQL
2cfe0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 ITE_TEXT.# undef
2cff0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c SQLITE_TEXT.#el
2d000 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 se.# define SQLI
2d010 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 TE_TEXT 3.#e
2d020 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c ndif.#define SQL
2d030 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a ITE3_TEXT 3.
2d040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d050 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 Result Values F
2d060 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b rom A Query.** K
2d070 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e EYWORDS: {column
2d080 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
2d090 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s}.**.** These r
2d0a0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
2d0b0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e "result set" in
2d0c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
2d0d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2d0e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2d0f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
2d100 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
2d110 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
2d120 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
2d130 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
2d140 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
2d150 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
2d160 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
2d170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d180 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
2d190 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
2d1a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
2d1b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
2d1c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2d1d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2d1e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
2d1f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
2d200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2d210 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2d220 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
2d230 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
2d240 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
2d250 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
2d260 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
2d270 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
2d280 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
2d290 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
2d2a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2d2b0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
2d2c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
2d2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2d2e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
2d2f0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2d300 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
2d310 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
2d320 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
2d330 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
2d340 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
2d350 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
2d360 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
2d370 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
2d380 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
2d390 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
2d3a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2d3b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2d3c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
2d3d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2d3e0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
2d3f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
2d400 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
2d410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2d420 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
2d430 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
2d440 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
2d450 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
2d460 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
2d470 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
2d480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
2d490 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
2d4a0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
2d4b0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
2d4c0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
2d4d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2d4e0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
2d4f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2d500 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
2d510 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2d520 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2d530 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2d540 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
2d550 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
2d560 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
2d570 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
2d580 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
2d590 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
2d5a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2d5b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2d5c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2d5d0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
2d5e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
2d5f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
2d600 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
2d610 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
2d620 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
2d630 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
2d640 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
2d650 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
2d660 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
2d670 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
2d680 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
2d690 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
2d6a0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
2d6b0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
2d6c0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
2d6d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d6e0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
2d6f0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
2d700 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
2d710 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
2d720 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
2d730 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
2d740 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
2d750 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
2d760 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2d770 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2d780 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
2d790 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
2d7a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
2d7b0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
2d7c0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
2d7d0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
2d7e0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
2d7f0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
2d800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2d810 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
2d820 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
2d830 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
2d840 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
2d850 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2d860 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2d870 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
2d880 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
2d890 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2d8a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
2d8b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2d8c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
2d8d0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
2d8e0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
2d8f0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
2d900 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2d910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2d920 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2d930 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2d940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2d950 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
2d960 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
2d970 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
2d980 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
2d990 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2d9a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
2d9b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2d9c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
2d9d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2d9e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
2d9f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2da00 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
2da10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
2da20 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
2da30 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
2da40 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
2da50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2da60 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2da70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2da80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2da90 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2daa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2dab0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
2dac0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2dad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2dae0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
2daf0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
2db00 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
2db10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2db20 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
2db30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2db40 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
2db50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2db60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
2db70 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
2db80 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
2db90 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
2dba0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
2dbb0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
2dbc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2dbd0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
2dbe0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2dbf0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
2dc00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2dc10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2dc20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2dc30 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
2dc40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2dc50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2dc60 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
2dc70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2dc80 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
2dc90 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
2dca0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
2dcb0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
2dcc0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
2dcd0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
2dce0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
2dcf0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2dd00 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2dd20 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
2dd30 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
2dd40 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
2dd50 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
2dd60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
2dd70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
2dd80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2dd90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2dda0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
2ddb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
2ddc0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
2ddd0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
2dde0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 s zero terminate
2ddf0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
2de00 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
2de10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2de20 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
2de30 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
2de40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2de50 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 .** ^The object
2de60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2de70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2de80 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
2de90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2dea0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2deb0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
2dec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2ded0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
2dee0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
2def0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
2df00 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
2df10 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2df20 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
2df30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2df40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2df50 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
2df60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2df70 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
2df80 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
2df90 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
2dfa0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
2dfb0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
2dfc0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
2dfd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2dfe0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
2dff0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
2e000 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
2e010 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
2e020 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
2e030 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
2e040 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
2e050 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
2e060 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 propriate. ^For
2e070 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
2e080 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
2e090 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
2e0a0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
2e0b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
2e0c0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
2e0d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
2e0e0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
2e0f0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
2e100 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
2e110 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 omatically. ^(T
2e120 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 he following tab
2e130 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 le details the c
2e140 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 onversions.** th
2e150 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a at are applied:.
2e160 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
2e170 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
2e180 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
2e190 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 <th> Internal<br
2e1a0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 >Type <th> Reque
2e1b0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 sted<br>Type <th
2e1c0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a > Conversion.**
2e1d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
2e1e0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
2e1f0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
2e200 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
2e210 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
2e220 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
2e230 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
2e240 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2e250 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
2e260 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2e270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2e280 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2e290 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2e2a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2e2b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2e2c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
2e2d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
2e2e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
2e2f0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
2e300 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
2e310 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
2e320 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
2e330 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
2e340 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
2e350 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
2e360 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
2e370 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 <td> Same as INT
2e380 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 EGER->TEXT.** <t
2e390 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
2e3a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2e3b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
2e3c0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 float to intege
2e3d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 r.** <tr><td> F
2e3e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
2e3f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2e400 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2e410 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
2e420 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2e430 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2e440 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e Same as FLOAT->
2e450 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
2e460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 TEXT <td> I
2e470 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 NTEGER <td> Us
2e480 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
2e490 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2e4a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2e4b0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 > Use atof().**
2e4c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
2e4d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2e4e0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a <td> No change.
2e4f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2e500 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 B <td> INTEGE
2e510 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
2e520 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 to TEXT then us
2e530 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e e atoi().** <tr>
2e540 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
2e550 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2e560 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
2e570 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 T then use atof(
2e580 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
2e590 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 LOB <td> TE
2e5a0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 XT <td> Add a
2e5b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2e5c0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f if needed.** </
2e5d0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 table>.** </bloc
2e5e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
2e5f0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
2e600 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
2e610 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
2e620 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
2e630 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
2e640 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
2e650 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
2e660 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
2e670 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
2e680 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
2e690 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
2e6a0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
2e6b0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
2e6c0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
2e6d0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
2e6e0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
2e6f0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
2e700 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
2e710 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
2e720 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
2e730 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
2e740 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
2e750 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
2e760 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
2e770 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2e780 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
2e790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
2e7a0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
2e7b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2e7c0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
2e7d0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
2e7e0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
2e7f0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
2e800 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
2e810 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
2e820 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
2e830 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
2e840 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2e850 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
2e860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2e870 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
2e880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e890 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
2e8a0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
2e8b0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
2e8c0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
2e8d0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
2e8e0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
2e8f0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
2e900 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
2e910 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
2e920 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2e930 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
2e940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2e950 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
2e960 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
2e970 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
2e980 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
2e990 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
2e9a0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2e9b0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
2e9c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2e9d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
2e9e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2e9f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
2ea00 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
2ea10 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
2ea20 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
2ea30 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
2ea40 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f </ul>.**.** ^Co
2ea50 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
2ea60 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
2ea70 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
2ea80 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
2ea90 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
2eaa0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
2eab0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
2eac0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
2ead0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
2eae0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
2eaf0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
2eb00 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 references will
2eb10 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
2eb20 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
2eb30 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
2eb40 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
2eb50 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
2eb60 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
2eb70 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
2eb80 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
2eb90 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
2eba0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
2ebb0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
2ebc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 d..**.** The saf
2ebd0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 est and easiest
2ebe0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 to remember poli
2ebf0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 cy is to invoke
2ec00 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
2ec10 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 * in one of the
2ec20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a following ways:.
2ec30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c **.** <ul>.** <
2ec40 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
2ec50 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 n_text() followe
2ec60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2ec70 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
2ec80 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
2ec90 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
2eca0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2ecb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2ecc0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
2ecd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2ece0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 xt16() followed
2ecf0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2ed00 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e n_bytes16()</li>
2ed10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
2ed20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2ed30 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 you should call
2ed40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ed50 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 ext(),.** sqlite
2ed60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
2ed70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
2ed80 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 mn_text16() firs
2ed90 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 t to force the r
2eda0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 esult.** into th
2edb0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 e desired format
2edc0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 , then invoke sq
2edd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2ede0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 es() or.** sqlit
2edf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2ee00 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6() to find the
2ee10 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 size of the resu
2ee20 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 lt. Do not mix
2ee30 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 calls.** to sqli
2ee40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2ee50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2ee60 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 umn_blob() with
2ee70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
2ee80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2ee90 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 16(), and do not
2eea0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 mix calls to sq
2eeb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2eec0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 t16().** with ca
2eed0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
2eee0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a olumn_bytes()..*
2eef0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 *.** ^The pointe
2ef00 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 rs returned are
2ef10 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 valid until a ty
2ef20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 pe conversion oc
2ef30 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 curs as.** descr
2ef40 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 ibed above, or u
2ef50 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ntil [sqlite3_st
2ef60 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2ef70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
2ef80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2ef90 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e ze()] is called.
2efa0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 ^The memory sp
2efb0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 ace used to hold
2efc0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 strings.** and
2efd0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 BLOBs is freed a
2efe0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 utomatically. D
2eff0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 o <b>not</b> pas
2f000 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 s the pointers r
2f010 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 eturned.** [sqli
2f020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2f030 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c )], [sqlite3_col
2f040 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 umn_text()], etc
2f050 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 . into.** [sqlit
2f060 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
2f070 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 * ^(If a memory
2f080 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
2f090 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
2f0a0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
2f0b0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 any.** of these
2f0c0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 routines, a def
2f0d0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 ault value is re
2f0e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 turned. The def
2f0f0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 ault value.** is
2f100 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 either the inte
2f110 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 ger 0, the float
2f120 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
2f130 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 0.0, or a NULL.
2f140 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 ** pointer. Sub
2f150 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
2f160 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
2f170 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e e()] will return
2f180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
2f190 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f M].)^.*/.SQLITE_
2f1a0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2f1b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2f1c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2f1d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2f1e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2f1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2f200 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
2f210 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2f220 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2f230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2f240 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2f250 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2f260 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 TE_API double sq
2f270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
2f280 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
2f290 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2f2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2f2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 ite3_column_int(
2f2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2f2d0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
2f2e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
2f2f0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2f300 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2f310 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2f320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2f330 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
2f340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2f350 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
2f360 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2f370 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2f380 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2f390 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c olumn_text16(sql
2f3a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2f3b0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
2f3c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
2f3d0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 lumn_type(sqlite
2f3e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2f3f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 l);.SQLITE_API s
2f400 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
2f410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2f420 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2f430 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
2f440 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2f450 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
2f460 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
2f470 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2f480 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
2f490 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
2f4a0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
2f4b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f4c0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 nt]..** ^If the
2f4d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
2f4e0 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 uation of the st
2f4f0 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 atement encounte
2f500 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a red no errors.**
2f510 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 or if the state
2f520 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 ment is never be
2f530 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 en evaluated, th
2f540 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c en sqlite3_final
2f550 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a ize() returns.**
2f560 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 SQLITE_OK. ^If
2f570 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2f580 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 evaluation of s
2f590 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 tatement S faile
2f5a0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 d, then.** sqlit
2f5b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
2f5c0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f eturns the appro
2f5d0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
2f5e0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
2f5f0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e ded error code].
2f600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2f610 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
2f620 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 routine can be c
2f630 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 alled at any poi
2f640 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 nt during.** the
2f650 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b life cycle of [
2f660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f670 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 nt] S:.** before
2f680 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 statement S is
2f690 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 ever evaluated,
2f6a0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 after.** one or
2f6b0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 more calls to [s
2f6c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
2f6d0 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 or after any ca
2f6e0 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ll.** to [sqlite
2f6f0 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 3_step()] regard
2f700 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
2f710 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 or not the state
2f720 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 ment has.** comp
2f730 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e leted execution.
2f740 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 .**.** ^Invoking
2f750 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2f760 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f e() on a NULL po
2f770 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c inter is a harml
2f780 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a ess no-op..**.**
2f790 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
2f7a0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 must finalize e
2f7b0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 very [prepared s
2f7c0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 tatement] in ord
2f7d0 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 er to avoid.** r
2f7e0 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 esource leaks.
2f7f0 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 It is a grievous
2f800 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 error for the a
2f810 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 pplication to tr
2f820 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 y to use.** a pr
2f830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f840 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
2f850 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 en finalized. A
2f860 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 ny use of a prep
2f870 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
2f880 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
2f890 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 een finalized ca
2f8a0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 n result in unde
2f8b0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 fined and.** und
2f8c0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
2f8d0 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 r such as segfau
2f8e0 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 lts and heap cor
2f8f0 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 ruption..*/.SQLI
2f900 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2f910 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 e3_finalize(sqli
2f920 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2f930 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f940 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 F: Reset A Prepa
2f950 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
2f960 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ject.**.** The s
2f970 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 qlite3_reset() f
2f980 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
2f990 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 d to reset a [pr
2f9a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f9b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b ].** object back
2f9c0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2f9d0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 state, ready to
2f9e0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a be re-executed..
2f9f0 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 ** ^Any SQL stat
2fa00 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 ement variables
2fa10 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 that had values
2fa20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 bound to them us
2fa30 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ing.** the [sqli
2fa40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
2fa50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2fa60 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 API] retain the
2fa70 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 ir values..** Us
2fa80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 e [sqlite3_clear
2fa90 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 _bindings()] to
2faa0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e reset the bindin
2fab0 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b gs..**.** ^The [
2fac0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
2fad0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 ] interface rese
2fae0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 ts the [prepared
2faf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a statement] S.**
2fb00 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 back to the beg
2fb10 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 inning of its pr
2fb20 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 ogram..**.** ^If
2fb30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2fb40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2fb50 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
2fb60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
2fb70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 statement] S ret
2fb80 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
2fb90 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f W] or [SQLITE_DO
2fba0 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 NE],.** or if [s
2fbb0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2fbc0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 has never before
2fbd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
2fbe0 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 S,.** then [sqli
2fbf0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
2fc00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
2fc10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
2fc20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
2fc30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2fc40 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
2fc50 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2fc60 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 ement] S indicat
2fc70 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 ed an error, the
2fc80 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 n.** [sqlite3_re
2fc90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
2fca0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
2fcb0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
2fcc0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
2fcd0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
2fce0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 face does not ch
2fcf0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a ange the values.
2fd00 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 ** of any [sqlit
2fd10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e e3_bind_blob|bin
2fd20 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 dings] on the [p
2fd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fd40 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f t] S..*/.SQLITE_
2fd50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2fd60 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 reset(sqlite3_st
2fd70 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2fd80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 ** CAPI3REF: Cre
2fd90 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 ate Or Redefine
2fda0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a SQL Functions.**
2fdb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 KEYWORDS: {func
2fdc0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
2fdd0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f utines}.** KEYWO
2fde0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f RDS: {applicatio
2fdf0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2fe00 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f nction}.** KEYWO
2fe10 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f RDS: {applicatio
2fe20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2fe30 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e nctions}.**.** ^
2fe40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
2fe50 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e (collectively kn
2fe60 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e own as "function
2fe70 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
2fe80 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 es").** are used
2fe90 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 to add SQL func
2fea0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
2feb0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 tes or to redefi
2fec0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a ne the behavior.
2fed0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 ** of existing S
2fee0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
2fef0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 aggregates. The
2ff00 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 only difference
2ff10 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 s between.** the
2ff20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
2ff30 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e the text encodin
2ff40 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a g expected for.*
2ff50 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * the second par
2ff60 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 ameter (the name
2ff70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
2ff80 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a being created).
2ff90 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 ** and the prese
2ffa0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f nce or absence o
2ffb0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 f a destructor c
2ffc0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 allback for.** t
2ffd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
2ffe0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ata pointer..**.
2fff0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
30000 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
30010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
30020 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 ion] to which th
30030 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f e SQL.** functio
30040 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 n is to be added
30050 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 . ^If an applic
30060 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 ation uses more
30070 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 than one databas
30080 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
30090 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e then application
300a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
300b0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 ctions must be a
300c0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 dded.** to each
300d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
300e0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a ion separately..
300f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
30100 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
30110 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
30120 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
30130 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
30140 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 redefined. ^The
30150 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
30160 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
30170 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 o 255 bytes in a
30180 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 UTF-8.** repres
30190 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 entation, exclus
301a0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d ive of the zero-
301b0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f terminator. ^No
301c0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 te that the name
301d0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 .** length limit
301e0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 is in UTF-8 byt
301f0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 es, not characte
30200 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 rs nor UTF-16 by
30210 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 tes. .** ^Any a
30220 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
30230 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
30240 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
30250 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
30260 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
30270 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e being returned.
30280 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
30290 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 d parameter (nAr
302a0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d g).** is the num
302b0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
302c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 that the SQL fu
302d0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
302e0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 regate takes. ^I
302f0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 f this parameter
30300 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 is -1, then the
30310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
30320 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 .** aggregate ma
30330 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 y take any numbe
30340 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 r of arguments b
30350 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 etween 0 and the
30360 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 limit.** set by
30370 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d [sqlite3_limit]
30380 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 ([SQLITE_LIMIT_F
30390 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 UNCTION_ARG]).
303a0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 If the third.**
303b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 parameter is les
303c0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 s than -1 or gre
303d0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 ater than 127 th
303e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
303f0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e is.** undefined.
30400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 .**.** ^The four
30410 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 th parameter, eT
30420 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 extRep, specifie
30430 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 s what.** [SQLIT
30440 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e E_UTF8 | text en
30450 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c coding] this SQL
30460 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 function prefer
30470 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 s for.** its par
30480 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 ameters. Every
30490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
304a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 lementation must
304b0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b be able to work
304c0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 .** with UTF-8,
304d0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 UTF-16le, or UTF
304e0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 -16be. But some
304f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
30500 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 may be.** more
30510 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f efficient with o
30520 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e ne encoding than
30530 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 another. ^An a
30540 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a pplication may.*
30550 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
30560 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
30570 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
30580 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
30590 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 ) multiple.** ti
305a0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
305b0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 e function but w
305c0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 ith different va
305d0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 lues of eTextRep
305e0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 ..** ^When multi
305f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
30600 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
30610 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 function are ava
30620 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a ilable, SQLite.*
30630 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 * will pick the
30640 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 one that involve
30650 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
30660 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 nt of data conve
30670 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 rsion..** If the
30680 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e re is only a sin
30690 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 gle implementati
306a0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f on which does no
306b0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 t care what text
306c0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 .** encoding is
306d0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 used, then the f
306e0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 ourth argument s
306f0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 hould be [SQLITE
30700 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 _ANY]..**.** ^(T
30710 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
30720 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
30730 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
30740 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
30750 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
30760 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
30770 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
30780 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
30790 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 3_user_data()].)
307a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ^.**.** ^The six
307b0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 th, seventh and
307c0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 eighth parameter
307d0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
307e0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
307f0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
30800 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
30810 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
30820 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
30830 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
30840 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
30850 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
30860 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
30870 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
30880 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
30890 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
308a0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 ers must be pass
308b0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
308c0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
308d0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
308e0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
308f0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
30900 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
30910 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
30920 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
30930 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 pointer must be
30940 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
30950 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
30960 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
30970 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
30980 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
30990 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c pointers for al
309a0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
309b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a .** callbacks..*
309c0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 *.** ^(If the ni
309d0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f nth parameter to
309e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
309f0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 function_v2() is
30a00 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 not NULL,.** th
30a10 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 en it is destruc
30a20 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c tor for the appl
30a30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
30a40 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 nter. .** The de
30a50 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f structor is invo
30a60 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e ked when the fun
30a70 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 ction is deleted
30a80 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e , either by bein
30a90 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 g.** overloaded
30aa0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 or when the data
30ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
30ac0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 closes.)^.** ^Th
30ad0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
30ae0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 also invoked if
30af0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 the call to.** s
30b00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
30b10 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c nction_v2() fail
30b20 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 s..** ^When the
30b30 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
30b40 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 ack of the tenth
30b50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e parameter is in
30b60 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 voked, it.** is
30b70 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 passed a single
30b80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
30b90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
30ba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
30bb0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 .** pointer whi
30bc0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 ch was the fifth
30bd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
30be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30bf0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a ction_v2()..**.*
30c00 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 * ^It is permitt
30c10 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d ed to register m
30c20 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
30c30 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
30c40 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ame.** functions
30c50 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
30c60 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 ame but with eit
30c70 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 her differing nu
30c80 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 mbers of.** argu
30c90 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 ments or differi
30ca0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 ng preferred tex
30cb0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 t encodings. ^S
30cc0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
30cd0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
30ce0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 tion that most c
30cf0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 losely matches t
30d00 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
30d10 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 the.** SQL funct
30d20 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 ion is used. ^A
30d30 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
30d40 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 entation with a
30d50 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 non-negative.**
30d60 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 nArg parameter i
30d70 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 s a better match
30d80 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
30d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
30da0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 with.** a negati
30db0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e ve nArg. ^A fun
30dc0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
30dd0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
30de0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
30df0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
30e00 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
30e10 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
30e20 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
30e30 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
30e40 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
30e50 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 .** ^A function
30e60 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
30e70 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
30e80 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
30e90 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
30ea0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
30eb0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
30ec0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
30ed0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
30ee0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
30ef0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
30f00 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 .** ^Built-in fu
30f10 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
30f20 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
30f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
30f40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
30f50 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 **.** ^An applic
30f60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
30f70 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 nction is permit
30f80 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 ted to call othe
30f90 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
30fa0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 rfaces. However
30fb0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 , such calls mus
30fc0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 t not.** close t
30fd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
30fe0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c ection nor final
30ff0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 ize or reset the
31000 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
31010 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 tement in which
31020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
31030 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
31040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
31050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
31060 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
31070 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
31080 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
31090 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
310a0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
310b0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
310c0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
310d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
310e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
310f0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
31100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
31110 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
31120 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
31130 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
31140 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 _context*).);.SQ
31150 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
31160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
31170 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
31180 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
31190 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
311a0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
311b0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
311c0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
311d0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
311e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
311f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
31200 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
31210 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
31220 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
31230 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
31240 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
31250 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
31260 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
31270 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
31280 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 function_v2(. s
31290 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
312a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 nst char *zFunct
312b0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
312c0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
312d0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
312e0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
312f0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
31300 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
31310 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
31320 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
31330 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
31340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
31350 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
31360 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
31370 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 t*),. void(*xDe
31380 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
31390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
313a0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
313b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
313c0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 stant define int
313d0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 eger codes that
313e0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 represent the va
313f0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e rious.** text en
31400 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 codings supporte
31410 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a d by SQLite..*/.
31420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
31430 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a TF8 1.
31440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
31450 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a TF16LE 2.
31460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
31470 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a TF16BE 3.
31480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
31490 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 TF16 4
314a0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 /* Use native
314b0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 byte order */.#
314c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
314d0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 Y 5
314e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 /* sqlite3_cre
314f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c ate_function onl
31500 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
31510 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
31520 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 D 8 /* sqlit
31530 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
31540 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a ion only */../*.
31550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 ** CAPI3REF: Dep
31560 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e recated Function
31570 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a s.** DEPRECATED.
31580 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
31590 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 tions are [depre
315a0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 cated]. In orde
315b0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a r to maintain.**
315c0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
315d0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c tibility with ol
315e0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 der code, these
315f0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e functions contin
31600 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 ue .** to be sup
31610 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 ported. However
31620 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f , new applicatio
31630 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a ns should avoid.
31640 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 ** the use of th
31650 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
31660 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 To help encourag
31670 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 e people to avoi
31680 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 d.** using these
31690 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 functions, we a
316a0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 re not going to
316b0 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 tell you what th
316c0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ey do..*/.#ifnde
316d0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 f SQLITE_OMIT_DE
316e0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f PRECATED.SQLITE_
316f0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
31700 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
31710 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
31720 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
31730 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
31740 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
31750 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 D int sqlite3_ex
31760 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 pired(sqlite3_st
31770 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 mt*);.SQLITE_API
31780 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
31790 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 ED int sqlite3_t
317a0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 ransfer_bindings
317b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
317c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
317d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
317e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
317f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
31800 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
31810 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
31820 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
31830 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f sqlite3_thread_
31840 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 cleanup(void);.S
31850 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
31860 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
31870 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 sqlite3_memory_a
31880 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 larm(void(*)(voi
31890 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
318a0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 ,int),void*,sqli
318b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 te3_int64);.#end
318c0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
318d0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 EF: Obtaining SQ
318e0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d L Function Param
318f0 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a eter Values.**.*
31900 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 * The C-language
31910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
31920 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 of SQL functions
31930 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 and aggregates
31940 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 uses.** this set
31950 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f of interface ro
31960 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 utines to access
31970 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 the parameter v
31980 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 alues on.** the
31990 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
319a0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egate..**.** The
319b0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c xFunc (for scal
319c0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 ar functions) or
319d0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 xStep (for aggr
319e0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 egates) paramete
319f0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 rs.** to [sqlite
31a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
31a10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
31a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
31a30 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 n16()].** define
31a40 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 callbacks that
31a50 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 implement the SQ
31a60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
31a70 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 aggregates..** T
31a80 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
31a90 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 to these callba
31aa0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 cks is an array
31ab0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a of pointers to.*
31ac0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c * [protected sql
31ad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
31ae0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f cts. There is o
31af0 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ne [sqlite3_valu
31b00 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a e] object for.**
31b10 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 each parameter
31b20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 to the SQL funct
31b30 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 ion. These rout
31b40 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f ines are used to
31b50 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 .** extract valu
31b60 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c es from the [sql
31b70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
31b80 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 cts..**.** These
31b90 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f routines work o
31ba0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 nly with [protec
31bb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
31bc0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 e] objects..** A
31bd0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ny attempt to us
31be0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
31bf0 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 on an [unprotec
31c00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
31c10 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 e].** object res
31c20 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
31c30 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a d behavior..**.*
31c40 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
31c50 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 s work just like
31c60 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
31c70 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 ng [column acces
31c80 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 s functions].**
31c90 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 except that the
31ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 se routines take
31cb0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 a single [prote
31cc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
31cd0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f ue] object.** po
31ce0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 inter instead of
31cf0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 a [sqlite3_stmt
31d00 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 *] pointer and a
31d10 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e n integer column
31d20 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e number..**.** ^
31d30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
31d40 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 e_text16() inter
31d50 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 face extracts a
31d60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a UTF-16 string.**
31d70 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 in the native b
31d80 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 yte-order of the
31d90 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 host machine.
31da0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^The.** sqlite3_
31db0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
31dc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
31dd0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
31de0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
31df0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e act UTF-16 strin
31e00 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e gs as big-endian
31e10 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 and little-endi
31e20 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e an respectively.
31e30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
31e40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
31e50 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 ic_type() interf
31e60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
31e70 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 apply.** numeric
31e80 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 affinity to the
31e90 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 value. This me
31ea0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 ans that an atte
31eb0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 mpt is.** made t
31ec0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
31ed0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 lue to an intege
31ee0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f r or floating po
31ef0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 int. If.** such
31f00 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 a conversion is
31f10 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 possible withou
31f20 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d t loss of inform
31f30 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a ation (in other.
31f40 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 ** words, if the
31f50 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 value is a stri
31f60 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 ng that looks li
31f70 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 ke a number).**
31f80 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 then the convers
31f90 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 ion is performed
31fa0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
31fb0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
31fc0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 s..** The [SQLIT
31fd0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
31fe0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 type] after conv
31ff0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e ersion is return
32000 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 ed.)^.**.** Plea
32010 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
32020 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
32030 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
32040 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 pointer returne
32050 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
32060 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d e3_value_blob()]
32070 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
32080 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 _text()], or.**
32090 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
320a0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 ext16()] can be
320b0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 invalidated by a
320c0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
320d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
320e0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
320f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
32100 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 ytes16()], [sqli
32110 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
32120 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
32130 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
32140 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ]..**.** These r
32150 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
32160 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
32170 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a same thread as.*
32180 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
32190 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 on that supplied
321a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
321b0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 lue*] parameters
321c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
321d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
321e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 te3_value_blob(s
321f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
32200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
32210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
32220 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 es(sqlite3_value
32230 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
32240 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
32250 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
32260 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
32270 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 _API double sqli
32280 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
32290 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
322a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
322b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
322c0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt(sqlite3_value
322d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 *);.SQLITE_API s
322e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
322f0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
32300 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
32310 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
32320 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
32330 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
32340 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c text(sqlite3_val
32350 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
32360 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
32370 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
32380 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
32390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
323a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
323b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
323c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
323d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
323e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
323f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
32400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
32410 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
32420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
32430 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32440 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
32450 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
32460 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
32470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
32480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32490 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 Obtain Aggregate
324a0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
324b0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e t.**.** Implemen
324c0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 tations of aggre
324d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
324e0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 ns use this.** r
324f0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
32500 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 te memory for st
32510 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
32520 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 e..**.** ^The fi
32530 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c rst time the sql
32540 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
32550 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 ontext(C,N) rout
32560 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a ine is called .*
32570 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c * for a particul
32580 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e ar aggregate fun
32590 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a ction, SQLite.**
325a0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 allocates N of
325b0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f memory, zeroes o
325c0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 ut that memory,
325d0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
325e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
325f0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 new memory. ^On
32600 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
32610 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a quent calls to.*
32620 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
32630 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f ate_context() fo
32640 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 r the same aggre
32650 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
32660 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 stance,.** the s
32670 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 ame buffer is re
32680 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 turned. Sqlite3
32690 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
326a0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 xt() is normally
326b0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 .** called once
326c0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 for each invocat
326d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 ion of the xStep
326e0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 callback and th
326f0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 en one.** last t
32700 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 ime when the xFi
32710 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 nal callback is
32720 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e invoked. ^(When
32730 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a no rows match.*
32740 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 * an aggregate q
32750 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 uery, the xStep(
32760 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 ) callback of th
32770 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
32780 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e tion.** implemen
32790 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 tation is never
327a0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 called and xFina
327b0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 l() is called ex
327c0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 actly once..** I
327d0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 n those cases, s
327e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
327f0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 _context() might
32800 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 be called for t
32810 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 he.** first time
32820 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 from within xFi
32830 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e nal().)^.**.** ^
32840 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 The sqlite3_aggr
32850 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
32860 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 N) routine retur
32870 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
32880 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 r if N is.** les
32890 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 s than or equal
328a0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 to zero or if a
328b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 memory allocate
328c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a error occurs..**
328d0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 .** ^(The amount
328e0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 of space alloca
328f0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 ted by sqlite3_a
32900 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32910 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 (C,N) is.** dete
32920 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 rmined by the N
32930 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 parameter on fir
32940 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 st successful ca
32950 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 ll. Changing th
32960 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 e.** value of N
32970 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
32980 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ll to sqlite3_ag
32990 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
329a0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 ) within.** the
329b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
329c0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
329d0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 will not resize
329e0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
329f0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a llocation.)^.**.
32a00 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
32a10 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
32a20 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
32a30 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
32a40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
32a50 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
32a60 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
32a70 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
32a80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
32a90 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
32aa0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
32ab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
32ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
32ad0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
32ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
32af0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
32b00 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
32b10 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
32b20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
32b30 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
32b40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
32b50 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
32b60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
32b70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
32b80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
32b90 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
32ba0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
32bb0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
32bc0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 void *sqlite3_a
32bd0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32be0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32bf0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
32c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32c10 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
32c20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
32c30 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 The sqlite3_user
32c40 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 _data() interfac
32c50 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
32c60 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
32c70 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
32c80 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 pUserData parame
32c90 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 ter (the 5th par
32ca0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
32cb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
32cc0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
32cd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
32ce0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
32cf0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
32d00 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
32d10 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
32d20 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
32d30 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
32d40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
32d50 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
32d60 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
32d70 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
32d80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
32d90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
32da0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
32db0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
32dc0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
32dd0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
32de0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
32df0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
32e00 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
32e10 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 nctions.**.** ^T
32e20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 he sqlite3_conte
32e30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 xt_db_handle() i
32e40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
32e50 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
32e60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
32e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
32e80 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 ction] (the 1st
32e90 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
32ea0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
32eb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
32ec0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
32ed0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32ee0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
32ef0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
32f00 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
32f10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
32f20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
32f30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
32f40 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
32f50 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
32f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
32f80 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
32f90 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a iliary Data.**.*
32fa0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
32fb0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
32fc0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
32fd0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
32fe0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
32ff0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
33000 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
33010 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
33020 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
33030 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
33040 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
33050 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
33060 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
33070 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
33080 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
33090 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
330a0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
330b0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
330c0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
330d0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
330e0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
330f0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
33100 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
33110 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
33120 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
33130 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
33140 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
33150 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
33160 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
33170 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
33180 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
33190 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
331a0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
331b0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
331c0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
331d0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
331e0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
331f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
33200 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
33210 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
33220 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
33230 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
33240 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
33250 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
33260 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
33270 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
33280 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
33290 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
332a0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
332b0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
332c0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
332d0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
332e0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
332f0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
33300 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
33310 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33320 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e function. ^If n
33330 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 o metadata has b
33340 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e een ever.** been
33350 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 set for the Nth
33360 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
33370 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 function, or if
33380 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
33390 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 ng.** function p
333a0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 arameter has cha
333b0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d nged since the m
333c0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 eta-data was set
333d0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 ,.** then sqlite
333e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
333f0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
33400 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
33410 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
33420 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
33430 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 ce saves the met
33440 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 adata.** pointed
33450 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
33460 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
33470 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
33480 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
33490 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
334a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
334b0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 ction. Subseque
334c0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
334d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
334e0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 ta() might retur
334f0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 n this data, if
33500 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 it has.** not be
33510 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a en destroyed..**
33520 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e ^If it is not N
33530 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c ULL, SQLite will
33540 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
33550 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ructor.** functi
33560 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 on given by the
33570 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
33580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
33590 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 data() on.** the
335a0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 metadata when t
335b0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
335c0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
335d0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f ter changes.** o
335e0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 r when the SQL s
335f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 tatement complet
33600 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f es, whichever co
33610 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a mes first..**.**
33620 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 SQLite is free
33630 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 to call the dest
33640 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 ructor and drop
33650 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a metadata on any.
33660 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 ** parameter of
33670 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 any function at
33680 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 any time. ^The
33690 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 only guarantee i
336a0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 s that.** the de
336b0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 structor will be
336c0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 called before t
336d0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 he metadata is d
336e0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ropped..**.** ^(
336f0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
33700 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 adata is preserv
33710 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 ed between funct
33720 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a ion calls for.**
33730 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 expressions tha
33740 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 t are constant a
33750 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 t compile time.
33760 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 This includes li
33770 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 teral.** values
33780 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d and [parameters]
33790 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 .)^.**.** These
337a0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
337b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
337c0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
337d0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
337e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
337f0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
33800 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
33810 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_get_auxdata(sq
33820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
33830 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
33840 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
33850 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
33860 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
33870 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
33880 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
33890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
338a0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
338b0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
338c0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a uctor Behavior.*
338d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
338e0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
338f0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
33900 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
33910 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
33920 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
33930 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
33940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
33950 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 b()]. ^If the d
33960 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
33970 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
33980 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
33990 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
339a0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
339b0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
339c0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
339d0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
339e0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
339f0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 d. ^The.** SQLI
33a00 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
33a10 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
33a20 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
33a30 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
33a40 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
33a50 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
33a60 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
33a70 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
33a80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
33a90 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
33aa0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
33ab0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
33ac0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
33ad0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
33ae0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
33af0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 compilers. See
33b00 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a ticket #2191..*
33b10 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 /.typedef void (
33b20 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 *sqlite3_destruc
33b30 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 tor_type)(void*)
33b40 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
33b50 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 _STATIC ((s
33b60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
33b70 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e r_type)0).#defin
33b80 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 e SQLITE_TRANSIE
33b90 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 NT ((sqlite3_d
33ba0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d estructor_type)-
33bb0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 1)../*.** CAPI3R
33bc0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 EF: Setting The
33bd0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c Result Of An SQL
33be0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Function.**.**
33bf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
33c00 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
33c10 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
33c20 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
33c30 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
33c40 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
33c50 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
33c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
33c80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33c90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
33ca0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
33cb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
33cc0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
33cd0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
33ce0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
33cf0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
33d00 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
33d10 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
33d20 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
33d30 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
33d40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
33d50 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
33d60 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
33d70 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
33d80 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
33d90 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
33da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
33db0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
33dc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
33dd0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
33de0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
33df0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
33e00 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
33e10 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
33e20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
33e30 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
33e40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
33e50 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
33e60 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
33e70 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
33e80 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
33e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33ea0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 zeroblob() inter
33eb0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 faces set the re
33ec0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
33ed0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33ee0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
33ef0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e e a BLOB contain
33f00 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 ing all zero.**
33f10 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 bytes and N byte
33f20 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 s in size, where
33f30 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 N is the value
33f40 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d of the 2nd param
33f50 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
33f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33f70 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
33f80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
33f90 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
33fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
33fb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
33fc0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
33fd0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
33fe0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
33ff0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
34000 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
34010 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
34020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
34030 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f rror16() functio
34040 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 ns.** cause the
34050 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 implemented SQL
34060 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f function to thro
34070 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a w an exception..
34080 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
34090 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
340a0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
340b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
340c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
340d0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
340e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
340f0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
34100 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
34110 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 essage. ^SQLite
34120 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
34130 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
34140 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
34150 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34160 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 r() as UTF-8. ^S
34170 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 QLite.** interpr
34180 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 ets the string f
34190 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
341a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 lt_error16() as
341b0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
341c0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 .** byte order.
341d0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
341e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
341f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34200 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
34210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
34220 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
34230 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
34240 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
34250 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
34260 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
34270 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
34280 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
34290 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
342a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
342b0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a lt_error() or.**
342c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
342d0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e error16() is non
342e0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 -negative then S
342f0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 QLite takes that
34300 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 many.** bytes (
34310 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
34320 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
34330 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 ameter as the er
34340 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 ror message..**
34350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
34360 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
34370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
34380 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 rror16().** rout
34390 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 ines make a priv
343a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
343b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
343c0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 xt before.** the
343d0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 y return. Hence
343e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 , the calling fu
343f0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c nction can deall
34400 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 ocate or.** modi
34410 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 fy the text afte
34420 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 r they return wi
34430 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e thout harm..** ^
34440 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34450 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 lt_error_code()
34460 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 function changes
34470 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a the error code.
34480 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 ** returned by S
34490 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c QLite as a resul
344a0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e t of an error in
344b0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 a function. ^B
344c0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
344d0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
344e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e SQLITE_ERROR. ^
344f0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
34500 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 l to sqlite3_res
34510 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
34520 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
34530 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 _error16() reset
34540 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
34550 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 to SQLITE_ERROR
34560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
34570 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 ite3_result_toob
34580 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 ig() interface c
34590 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 auses SQLite to
345a0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a throw an error.*
345b0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 * indicating tha
345c0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c t a string or BL
345d0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 OB is too long t
345e0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a o represent..**.
345f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34600 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 result_nomem() i
34610 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
34620 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
34630 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
34640 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
34650 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
34660 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 failed..**.** ^T
34670 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34680 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
34690 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
346a0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
346b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
346c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
346d0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
346e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
346f0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
34700 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
34710 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 t..** ^The sqlit
34720 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
34730 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
34740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
34750 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
34760 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34770 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
34780 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
34790 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
347a0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
347b0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
347c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
347d0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
347e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
347f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
34800 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
34810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
34820 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
34830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34840 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
34850 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ), sqlite3_resul
34860 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 t_text16(),.** s
34870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
34880 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 xt16le(), and sq
34890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
348a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 t16be() interfac
348b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 es.** set the re
348c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
348d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
348e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
348f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 o be.** a text s
34900 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 tring which is r
34910 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 epresented as UT
34920 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 F-8, UTF-16 nati
34930 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a ve byte order,.*
34940 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 * UTF-16 little
34950 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 endian, or UTF-1
34960 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 6 big endian, re
34970 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
34980 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
34990 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
349a0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
349b0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
349c0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
349d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
349e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
349f0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 es..** ^If the 3
34a00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
34a10 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
34a20 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
34a30 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 ces.** is negati
34a40 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ve, then SQLite
34a50 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 takes result tex
34a60 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 t from the 2nd p
34a70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f arameter.** thro
34a80 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
34a90 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
34aa0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 ^If the 3rd par
34ab0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
34ac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34ad0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
34ae0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
34af0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 , then as many b
34b00 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
34b10 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 ters) of the tex
34b20 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 t.** pointed to
34b30 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
34b40 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 eter are taken a
34b50 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f s the applicatio
34b60 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e n-defined.** fun
34b70 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a ction result..**
34b80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
34b90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
34ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34bb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
34bc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
34bd0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
34be0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
34bf0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
34c00 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
34c10 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
34c20 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
34c30 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
34c40 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
34c50 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
34c60 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
34c70 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
34c80 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
34c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
34ca0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
34cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
34cc0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
34cd0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
34ce0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
34cf0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
34d00 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
34d10 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
34d20 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
34d30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
34d40 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
34d50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
34d60 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
34d70 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
34d80 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
34d90 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
34da0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
34db0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
34dc0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
34dd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
34de0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
34df0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
34e00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
34e10 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
34e20 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
34e30 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
34e40 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
34e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
34e60 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
34e70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
34e80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
34e90 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
34ea0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
34eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34ec0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
34ed0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
34ee0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
34ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
34f00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
34f10 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
34f20 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
34f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34f40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
34f50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
34f60 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
34f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
34f80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
34f90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
34fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
34fb0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
34fc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
34fd0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
34fe0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
34ff0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
35000 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
35010 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
35020 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
35030 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
35040 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
35050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
35060 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
35070 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
35080 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
35090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
350a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
350b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
350c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
350d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
350e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
350f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
35100 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
35110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
35120 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
35130 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
35140 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
35150 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
35160 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
35170 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
35180 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
35190 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
351a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
351b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
351c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
351d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
351e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
351f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 t_blob(sqlite3_c
35200 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
35210 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
35220 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
35230 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
35240 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
35250 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
35260 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c t*, double);.SQL
35270 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
35280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35290 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
352a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
352b0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
352c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
352d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
352e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
352f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
35300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
35310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35320 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
35330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
35340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
35350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
35360 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
35370 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
35380 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
35390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
353a0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
353b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
353c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
353d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
353e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e _int(sqlite3_con
353f0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c text*, int);.SQL
35400 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
35410 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
35420 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
35430 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t*, sqlite3_int6
35440 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
35450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35460 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f lt_null(sqlite3_
35470 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
35480 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
35490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
354a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
354b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
354c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
354d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
354e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
354f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
35500 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
35510 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
35520 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
35530 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
35540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35550 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
35560 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
35570 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
35580 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
35590 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
355a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
355b0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
355c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
355d0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
355e0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
355f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
35600 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 esult_value(sqli
35610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
35620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
35630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
35640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
35650 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
35660 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
35670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35680 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
35690 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
356a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
356b0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
356c0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
356d0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
356e0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
356f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
35700 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
35710 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
35720 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
35730 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
35740 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
35750 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
35760 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
35770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
35780 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
35790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
357a0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
357b0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
357c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
357d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
357e0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
357f0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
35800 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
35810 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
35820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
35830 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
35840 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
35850 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
35860 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
35870 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
35880 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
35890 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
358a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
358b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
358c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
358d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
358e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
358f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
35900 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
35910 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
35920 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
35930 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
35940 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
35950 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
35960 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
35970 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
35980 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
35990 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
359a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
359b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
359c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
359d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
359e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
359f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
35a00 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
35a10 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
35a20 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
35a30 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
35a40 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
35a50 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
35a60 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
35a70 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
35a80 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
35a90 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
35aa0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
35ab0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
35ac0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
35ad0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
35ae0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
35af0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
35b00 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
35b10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
35b20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
35b30 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
35b40 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
35b50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
35b60 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
35b70 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
35b80 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
35b90 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
35ba0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
35bb0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
35bc0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
35bd0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
35be0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
35bf0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
35c00 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
35c10 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
35c20 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
35c30 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
35c40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
35c50 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
35c60 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
35c70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
35c80 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
35c90 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
35ca0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
35cb0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
35cc0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
35cd0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
35ce0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
35cf0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
35d00 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
35d10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
35d20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
35d30 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
35d40 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
35d50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
35d60 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
35d70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
35d80 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
35d90 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
35da0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
35db0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
35dc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
35dd0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
35de0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
35df0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
35e00 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
35e10 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
35e20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
35e30 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
35e40 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
35e50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
35e60 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
35e70 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
35e80 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
35e90 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
35ea0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
35eb0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
35ec0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
35ed0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
35ee0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
35ef0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
35f00 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
35f10 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
35f20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
35f30 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
35f40 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
35f50 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
35f60 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
35f70 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
35f80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
35f90 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
35fa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
35fb0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
35fc0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
35fd0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
35fe0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
35ff0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
36000 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
36010 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
36020 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
36030 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
36040 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
36050 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
36060 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
36070 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
36080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
36090 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
360a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
360b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
360c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
360d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
360e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
360f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
36100 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
36110 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
36120 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
36130 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
36140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
36150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36160 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
36170 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
36180 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
36190 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
361a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
361b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
361c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
361d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
361e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
361f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
36200 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
36210 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
36220 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
36230 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
36240 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
36250 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
36260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
36270 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
36280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
36290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
362a0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
362b0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
362c0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
362d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
362e0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
362f0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
36300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
36310 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
36320 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
36330 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
36340 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
36350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
36360 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
36370 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
36380 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
36390 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
363a0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
363b0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
363c0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
363d0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
363e0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
363f0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
36400 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
36410 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
36420 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
36430 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
36440 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
36450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
36460 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
36470 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
36480 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
36490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
364a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
364b0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
364c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
364d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
364e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
364f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36500 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
36510 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
36520 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
36530 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
36540 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e void *pArg,. in
36550 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
36560 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
36570 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
36580 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 d*).);.SQLITE_AP
36590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
365a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
365b0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
365c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
365d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
365e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
365f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
36600 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
36610 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
36620 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 const void*),.
36630 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
36640 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 void*).);.SQLITE
36650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36670 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
36680 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a . const void *
36690 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 zName,. int eTe
366a0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
366b0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
366c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
366d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
366e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
366f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36700 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 : Collation Need
36710 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ed Callbacks.**.
36720 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 ** ^To avoid hav
36730 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
36740 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
36750 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
36760 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
36770 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
36780 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
36790 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
367a0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
367b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
367c0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 nection] to be i
367d0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
367e0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c an undefined col
367f0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
36800 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a ce is required..
36810 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 **.** ^If the fu
36820 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
36830 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
36840 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36850 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
36860 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
36870 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
36880 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
36890 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
368a0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
368b0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e oded in UTF-8. ^
368c0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 If sqlite3_colla
368d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 tion_needed16()
368e0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 is used,.** the
368f0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 names are passed
36900 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 as UTF-16 in ma
36910 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 chine native byt
36920 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 e order..** ^A c
36930 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
36940 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
36950 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c the existing col
36960 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 lation-needed ca
36970 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 llback..**.** ^(
36980 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
36990 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 k is invoked, th
369a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
369b0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 passed is a cop
369c0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f y.** of the seco
369d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
369e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
369f0 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 _needed() or.**
36a00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
36a10 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 n_needed16(). T
36a20 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
36a30 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
36a40 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
36a50 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
36a60 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
36a70 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
36a80 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
36a90 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
36aa0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 TF16LE], indicat
36ab0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 ing the most des
36ac0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 irable form of t
36ad0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 he collation.**
36ae0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f sequence functio
36af0 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 n required. The
36b00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
36b10 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
36b20 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 the.** required
36b30 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
36b40 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 nce.)^.**.** The
36b50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
36b60 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 on should regist
36b70 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 er the desired c
36b80 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a ollation using.*
36b90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
36ba0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 e_collation()],
36bb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36bc0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 collation16()],
36bd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
36be0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
36bf0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
36c00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36c10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
36c20 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a d(. sqlite3*, .
36c30 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 void*, . void
36c40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
36c50 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
36c60 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a const char*).);.
36c70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
36c80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36c90 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c _needed16(. sql
36ca0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
36cb0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
36cc0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
36cd0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 extRep,const voi
36ce0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 d*).);..#ifdef S
36cf0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a QLITE_HAS_CODEC.
36d00 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
36d10 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 e key for an enc
36d20 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e rypted database.
36d30 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 This routine s
36d40 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c hould be.** call
36d50 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 ed right after s
36d60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a qlite3_open()..*
36d70 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f *.** The code to
36d80 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 implement this
36d90 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c API is not avail
36da0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c able in the publ
36db0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 ic release.** of
36dc0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
36dd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
36de0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
36df0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
36e00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
36e10 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
36e20 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
36e30 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
36e40 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
36e50 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
36e60 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
36e70 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
36e80 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
36e90 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
36ea0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
36eb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
36ec0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
36ed0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
36ee0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
36ef0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
36f00 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
36f10 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
36f20 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
36f30 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
36f40 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
36f50 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
36f60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
36f70 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a sqlite3_rekey(.
36f80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
36f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36fa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
36fb0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
36fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
36fd0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
36fe0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f * The new key */
36ff0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 .);../*.** Speci
37000 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f fy the activatio
37010 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 n key for a SEE
37020 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 database. Unles
37030 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c s .** activated,
37040 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 none of the SEE
37050 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 routines will w
37060 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ork..*/.SQLITE_A
37070 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
37080 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 activate_see(.
37090 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 const char *zPas
370a0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f sPhrase /
370b0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 * Activation phr
370c0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 ase */.);.#endif
370d0 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f ..#ifdef SQLITE_
370e0 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a ENABLE_CEROD./*.
370f0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 ** Specify the a
37100 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f ctivation key fo
37110 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 r a CEROD databa
37120 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 se. Unless .**
37130 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 activated, none
37140 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 of the CEROD rou
37150 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e tines will work.
37160 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
37170 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 oid sqlite3_acti
37180 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f vate_cerod(. co
37190 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 nst char *zPassP
371a0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 hrase /*
371b0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 Activation phras
371c0 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a e */.);.#endif..
371d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
371e0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f Suspend Executio
371f0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 n For A Short Ti
37200 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c me.**.** The sql
37210 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e ite3_sleep() fun
37220 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 ction causes the
37230 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 current thread
37240 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 to suspend execu
37250 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c tion.** for at l
37260 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 east a number of
37270 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 milliseconds sp
37280 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 ecified in its p
37290 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
372a0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 If the operating
372b0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 system does not
372c0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 support sleep r
372d0 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 equests with.**
372e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 millisecond time
372f0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 resolution, the
37300 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 n the time will
37310 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f be rounded up to
37320 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 .** the nearest
37330 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 second. The numb
37340 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
37350 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
37360 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 ally.** requeste
37370 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 d from the opera
37380 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 ting system is r
37390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
373a0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
373b0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 s this interface
373c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 by calling the
373d0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 xSleep().** meth
373e0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
373f0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
37400 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 object. If the
37410 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a xSleep() method.
37420 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c ** of the defaul
37430 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 t VFS is not imp
37440 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 lemented correct
37450 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 ly, or not imple
37460 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c mented at.** all
37470 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
37480 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ior of sqlite3_s
37490 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 leep() may devia
374a0 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 te from the desc
374b0 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 ription.** in th
374c0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 e previous parag
374d0 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 raphs..*/.SQLITE
374e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
374f0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a _sleep(int);../*
37500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
37510 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 me Of The Folder
37520 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 Holding Tempora
37530 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e ry Files.**.** ^
37540 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 (If this global
37550 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 variable is made
37560 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 to point to a s
37570 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a tring which is.*
37580 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 * the name of a
37590 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 folder (a.k.a. d
375a0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 irectory), then
375b0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 all temporary fi
375c0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 les.** created b
375d0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 y SQLite when us
375e0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b ing a built-in [
375f0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 sqlite3_vfs | VF
37600 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c S].** will be pl
37610 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 aced in that dir
37620 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 ectory.)^ ^If t
37630 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
37640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
37650 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 r, then SQLite p
37660 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 erforms a search
37670 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 for an appropri
37680 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 ate.** temporary
37690 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e file directory.
376a0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 .**.** It is not
376b0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 safe to read or
376c0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
376d0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 iable in more th
376e0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 an one.** thread
376f0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 at a time. It
37700 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 is not safe to r
37710 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 ead or modify th
37720 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 is variable.** i
37730 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f f a [database co
37740 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 nnection] is bei
37750 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 ng used at the s
37760 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 ame time in a se
37770 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 parate.** thread
37780 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e ..** It is inten
37790 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 ded that this va
377a0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e riable be set on
377b0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 ce.** as part of
377c0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
377d0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f ization and befo
377e0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e re any SQLite in
377f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 terface.** routi
37800 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 nes have been ca
37810 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 lled and that th
37820 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 is variable rema
37830 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 in unchanged.**
37840 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a thereafter..**.*
37850 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f * ^The [temp_sto
37860 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
37870 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 gma] may modify
37880 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e this variable an
37890 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f d cause.** it to
378a0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 point to memory
378b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
378c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e sqlite3_malloc].
378d0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a ^Furthermore,.
378e0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f ** the [temp_sto
378f0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
37900 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 gma] always assu
37910 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 mes that any str
37920 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 ing.** that this
37930 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 variable points
37940 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d to is held in m
37950 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
37960 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rom .** [sqlite3
37970 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 _malloc] and the
37980 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 pragma may atte
37990 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 mpt to free that
379a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 memory.** using
379b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e [sqlite3_free].
379c0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 .** Hence, if th
379d0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d is variable is m
379e0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 odified directly
379f0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 , either it shou
37a00 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 ld be.** made NU
37a10 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f LL or made to po
37a20 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 int to memory ob
37a30 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
37a40 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 ite3_malloc].**
37a50 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 or else the use
37a60 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f of the [temp_sto
37a70 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
37a80 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 gma] should be a
37a90 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 voided..*/.SQLIT
37aa0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
37ab0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
37ac0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ry;../*.** CAPI3
37ad0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 REF: Test For Au
37ae0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a to-Commit Mode.*
37af0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
37b00 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a ocommit mode}.**
37b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37b20 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 _get_autocommit(
37b30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
37b40 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a rns non-zero or.
37b50 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 ** zero if the g
37b60 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f iven database co
37b70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 nnection is or i
37b80 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d s not in autocom
37b90 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 mit mode,.** res
37ba0 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 pectively. ^Aut
37bb0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
37bc0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a on by default..*
37bd0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f * ^Autocommit mo
37be0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 de is disabled b
37bf0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 y a [BEGIN] stat
37c00 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 ement..** ^Autoc
37c10 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 ommit mode is re
37c20 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 -enabled by a [C
37c30 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 OMMIT] or [ROLLB
37c40 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 ACK]..**.** If c
37c50 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 ertain kinds of
37c60 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 errors occur on
37c70 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 a statement with
37c80 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 in a multi-state
37c90 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 ment.** transact
37ca0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c ion (errors incl
37cb0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 uding [SQLITE_FU
37cc0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 LL], [SQLITE_IOE
37cd0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f RR],.** [SQLITE_
37ce0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f NOMEM], [SQLITE_
37cf0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 BUSY], and [SQLI
37d00 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 TE_INTERRUPT]) t
37d10 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 hen the.** trans
37d20 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 action might be
37d30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
37d40 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 matically. The
37d50 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 only way to.** f
37d60 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 ind out whether
37d70 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
37d80 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
37d90 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
37da0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 after.** an err
37db0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 or is to use thi
37dc0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a s function..**.*
37dd0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 * If another thr
37de0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 ead changes the
37df0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 autocommit statu
37e00 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 s of the databas
37e10 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
37e20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 while this routi
37e30 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 ne is running, t
37e40 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
37e50 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 alue.** is undef
37e60 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ined..*/.SQLITE_
37e70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
37e80 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 get_autocommit(s
37e90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
37ea0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
37eb0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e The Database Han
37ec0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 dle Of A Prepare
37ed0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
37ee0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
37ef0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 b_handle interfa
37f00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
37f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37f20 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 ion] handle.** t
37f30 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 o which a [prepa
37f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 red statement] b
37f50 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 elongs. ^The [d
37f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37f70 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 on].** returned
37f80 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 by sqlite3_db_ha
37f90 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 ndle is the same
37fa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
37fb0 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 ction].** that w
37fc0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
37fd0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 ument.** to the
37fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
37ff0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 _v2()] call (or
38000 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 its variants) th
38010 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a at was used to.*
38020 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 * create the sta
38030 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 tement in the fi
38040 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 rst place..*/.SQ
38050 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
38060 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e *sqlite3_db_han
38070 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dle(sqlite3_stmt
38080 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
38090 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 REF: Find the ne
380a0 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 xt prepared stat
380b0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ement.**.** ^Thi
380c0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
380d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
380e0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 the next [prepa
380f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
38100 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 fter.** pStmt as
38110 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
38120 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38130 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 ection] pDb. ^I
38140 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a f pStmt is NULL.
38150 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 ** then this int
38160 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
38170 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
38180 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 first prepared s
38190 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f tatement.** asso
381a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
381b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
381c0 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f ion pDb. ^If no
381d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
381e0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 ent.** satisfies
381f0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 the conditions
38200 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
38210 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c it returns NULL
38220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 ..**.** The [dat
38230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
38240 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 ] pointer D in a
38250 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
38260 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 ite3_next_stmt(D
38270 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 ,S)] must refer
38280 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 to an open datab
38290 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
382a0 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 n and in particu
382b0 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 lar must not be
382c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
382d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
382e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 lite3_stmt *sqli
382f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 te3_next_stmt(sq
38300 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 lite3 *pDb, sqli
38310 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
38320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38330 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f F: Commit And Ro
38340 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 llback Notificat
38350 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
38360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
38370 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 _commit_hook() i
38380 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
38390 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a rs a callback.**
383a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
383b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
383c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
383d0 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d s [COMMIT | comm
383e0 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 itted]..** ^Any
383f0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
38400 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
38410 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 to sqlite3_commi
38420 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 t_hook().** for
38430 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
38440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
38450 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e overridden..** ^
38460 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c The sqlite3_roll
38470 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 back_hook() inte
38480 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
38490 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
384a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
384b0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
384c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b transaction is [
384d0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 ROLLBACK | rolle
384e0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 d back]..** ^Any
384f0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
38500 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
38510 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c to sqlite3_roll
38520 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 back_hook().** f
38530 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
38540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
38550 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
38560 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 * ^The pArg argu
38570 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 ment is passed t
38580 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 hrough to the ca
38590 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 llback..** ^If t
385a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 he callback on a
385b0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e commit hook fun
385c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f ction returns no
385d0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 n-zero,.** then
385e0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f the commit is co
385f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 nverted into a r
38600 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e ollback..**.** ^
38610 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d The sqlite3_comm
38620 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 it_hook(D,C,P) a
38630 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 nd sqlite3_rollb
38640 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 ack_hook(D,C,P)
38650 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 functions.** ret
38660 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 urn the P argume
38670 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 nt from the prev
38680 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 ious call of the
38690 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a same function.*
386a0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 * on the same [d
386b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
386c0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 on] D, or NULL f
386d0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 or.** the first
386e0 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 call for each fu
386f0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a nction on D..**.
38700 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
38710 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
38720 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
38730 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
38740 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
38750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
38760 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
38770 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 callback. Any
38780 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f actions.** to mo
38790 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 dify the databas
387a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 e connection mus
387b0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e t be deferred un
387c0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a til after the.**
387d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 completion of t
387e0 68 65