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 38 2e 37 2e 20 20 42 ersion 3.8.7. 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 54 68 65 t LFS..**.** The
0b00: 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 previous paragr
0b10: 61 70 68 20 77 61 73 20 77 72 69 74 74 65 6e 20 aph was written
0b20: 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 73 20 in 2005. (This
0b30: 70 61 72 61 67 72 61 70 68 20 69 73 20 77 72 69 paragraph is wri
0b40: 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d tten.** on 2008-
0b50: 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 64 61 11-28.) These da
0b60: 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65 ys, all Linux ke
0b70: 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 6c 61 rnels support la
0b80: 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a rge files, so.**
0b90: 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f 62 you should prob
0ba0: 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 20 65 ably leave LFS e
0bb0: 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d nabled. But som
0bc0: 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 74 66 e embedded platf
0bd0: 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61 orms might.** la
0be0: 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 68 20 ck LFS in which
0bf0: 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f case the SQLITE_
0c00: 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72 DISABLE_LFS macr
0c10: 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 62 65 o might still be
0c20: 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 useful..**.** S
0c30: 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 imilar is true f
0c40: 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 or Mac OS X. LF
0c50: 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 S is only suppor
0c60: 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 ted on Mac OS X
0c70: 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 9 and later..*/.
0c80: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 #ifndef SQLITE_D
0c90: 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 ISABLE_LFS.# def
0ca0: 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 ine _LARGE_FILE
0cb0: 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 1.# ifndef
0cc0: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 _FILE_OFFSET_BI
0cd0: 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 TS.# define _F
0ce0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 ILE_OFFSET_BITS
0cf0: 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 64.# endif.# def
0d00: 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 ine _LARGEFILE_S
0d10: 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a OURCE 1.#endif..
0d20: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 /* Needed for va
0d30: 72 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e rious definition
0d40: 73 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66 69 s... */.#if defi
0d50: 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 ned(__GNUC__) &&
0d60: 20 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f 53 !defined(_GNU_S
0d70: 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 OURCE).# define
0d80: 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e 64 _GNU_SOURCE.#end
0d90: 69 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28 if..#if defined(
0da0: 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26 20 __OpenBSD__) &&
0db0: 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53 4f !defined(_BSD_SO
0dc0: 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f URCE).# define _
0dd0: 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 BSD_SOURCE.#endi
0de0: 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e f../*.** For Min
0df0: 47 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 GW, check to see
0e00: 20 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 if we can inclu
0e10: 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 de the header fi
0e20: 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 le containing it
0e30: 73 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 s.** version inf
0e40: 6f 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 ormation, among
0e50: 6f 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e other things. N
0e60: 6f 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e ormally, this in
0e70: 74 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 ternal MinGW.**
0e80: 68 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c header file woul
0e90: 64 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c d [only] be incl
0ea0: 75 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c uded automatical
0eb0: 6c 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 ly by other MinG
0ec0: 57 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 W header.** file
0ed0: 73 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20 s; however, the
0ee0: 63 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f contained versio
0ef0: 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 n information is
0f00: 20 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79 now required by
0f10: 20 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 this.** header
0f20: 66 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f file to work aro
0f30: 75 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 und binary compa
0f40: 74 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20 tibility issues
0f50: 28 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a (see below) and.
0f60: 2a 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f ** this is the o
0f70: 6e 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f nly known way to
0f80: 20 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e reliably obtain
0f90: 20 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72 it. This entir
0fa0: 65 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 e #if block.** w
0fb0: 6f 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 ould be complete
0fc0: 6c 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69 ly unnecessary i
0fd0: 66 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20 f there was any
0fe0: 6f 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74 other way of det
0ff0: 65 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 ecting.** MinGW
1000: 76 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f via their prepro
1010: 63 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 cessor (e.g. if
1020: 74 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 they customized
1030: 74 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66 their GCC to def
1040: 69 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 ine.** some MinG
1050: 57 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f W-specific macro
1060: 73 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c s). When compil
1070: 69 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 ing for MinGW, e
1080: 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 ither the.** _HA
1090: 56 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 VE_MINGW_H or _H
10a0: 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f AVE__MINGW_H (no
10b0: 74 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64 te the extra und
10c0: 65 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d erscore) macro m
10d0: 75 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 ust be.** define
10e0: 64 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65 d; otherwise, de
10f0: 74 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 tection of condi
1100: 74 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74 tions specific t
1110: 6f 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a o MinGW will be.
1120: 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a ** disabled..*/.
1130: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 #if defined(_HAV
1140: 45 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 E_MINGW_H).# inc
1150: 6c 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 lude "mingw.h".#
1160: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 elif defined(_HA
1170: 56 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 VE__MINGW_H).# i
1180: 6e 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 nclude "_mingw.h
1190: 22 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ".#endif../*.**
11a0: 46 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f For MinGW versio
11b0: 6e 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65 n 4.x (and highe
11c0: 72 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 r), check to see
11d0: 20 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42 if the _USE_32B
11e0: 49 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 IT_TIME_T.** def
11f0: 69 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20 ine is required
1200: 74 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 to maintain bina
1210: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ry compatibility
1220: 20 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72 with the MSVC r
1230: 75 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 untime.** librar
1240: 79 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 y in use (e.g. f
1250: 6f 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a or Windows XP)..
1260: 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 */.#if !defined(
1270: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f _USE_32BIT_TIME_
1280: 54 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f T) && !defined(_
1290: 55 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 USE_64BIT_TIME_T
12a0: 29 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e ) && \. defin
12b0: 65 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64 ed(_WIN32) && !d
12c0: 65 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 efined(_WIN64) &
12d0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 & \. defined(
12e0: 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 __MINGW_MAJOR_VE
12f0: 52 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 RSION) && __MING
1300: 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 W_MAJOR_VERSION
1310: 3e 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65 >= 4 && \. de
1320: 66 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f fined(__MSVCRT__
1330: 29 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f ).# define _USE_
1340: 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 32BIT_TIME_T.#en
1350: 64 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c dif../* The publ
1360: 69 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ic SQLite interf
1370: 61 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f ace. The _FILE_
1380: 4f 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72 OFFSET_BITS macr
1390: 6f 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a o must appear.**
13a0: 20 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 first in QNX.
13b0: 41 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 Also, the _USE_3
13c0: 32 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 2BIT_TIME_T macr
13d0: 6f 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69 o must appear fi
13e0: 72 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 rst for.** MinGW
13f0: 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
1400: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c **** Include sql
1410: 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 ite3.h in the mi
1420: 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e ddle of sqliteIn
1430: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a t.h ************
1440: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***/./**********
1450: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 **** Begin file
1460: 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a sqlite3.h ******
1470: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1480: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1490: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 ***/./*.** 2001
14a0: 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a September 15.**.
14b0: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 ** The author di
14c0: 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 sclaims copyrigh
14d0: 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 t to this source
14e0: 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 code. In place
14f0: 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e of.** a legal n
1500: 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 otice, here is a
1510: 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a blessing:.**.**
1520: 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 May you do g
1530: 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c ood and not evil
1540: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 ..** May you
1550: 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 find forgiveness
1560: 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e for yourself an
1570: 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 d forgive others
1580: 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 ..** May you
1590: 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 share freely, ne
15a0: 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 ver taking more
15b0: 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a than you give..*
15c0: 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a *.**************
15d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 ***********.** T
1610: 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 his header file
1620: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
1630: 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 rface that the S
1640: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a QLite library.**
1650: 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 presents to cli
1660: 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 ent programs. I
1670: 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 f a C-function,
1680: 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 structure, datat
1690: 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 ype,.** or const
16a0: 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 ant definition d
16b0: 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 oes not appear i
16c0: 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 n this file, the
16d0: 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 n it is.** not a
16e0: 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f published API o
16f0: 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 f SQLite, is sub
1700: 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
1710: 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 ithout.** notice
1720: 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 , and should not
1730: 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 be referenced b
1740: 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 y programs that
1750: 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a use SQLite..**.*
1760: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 * Some of the de
1770: 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 finitions that a
1780: 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 re in this file
1790: 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a are marked as.**
17a0: 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e "experimental".
17b0: 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 Experimental i
17c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f nterfaces are no
17d0: 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 rmally new.** fe
17e0: 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 atures recently
17f0: 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e added to SQLite.
1800: 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 We do not anti
1810: 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a cipate changes.*
1820: 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 * to experimenta
1830: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 l interfaces but
1840: 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 reserve the rig
1850: 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 ht to make minor
1860: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 changes.** if e
1870: 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 xperience from u
1880: 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 se "in the wild"
1890: 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 suggest such ch
18a0: 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e anges are pruden
18b0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 t..**.** The off
18c0: 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 icial C-language
18d0: 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 API documentati
18e0: 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 on for SQLite is
18f0: 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d derived.** from
1900: 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 comments in thi
1910: 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 s file. This fi
1920: 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 le is the author
1930: 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a itative source.*
1940: 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 * on how SQLite
1950: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 interfaces are s
1960: 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 uppose to operat
1970: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d e..**.** The nam
1980: 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 e of this file u
1990: 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 nder configurati
19a0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 on management is
19b0: 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a "sqlite.h.in"..
19c0: 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 ** The makefile
19d0: 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 makes some minor
19e0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 changes to this
19f0: 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 file (such as i
1a00: 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 nserting.** the
1a10: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 version number)
1a20: 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 and changes its
1a30: 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 name to "sqlite3
1a40: 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f .h" as.** part o
1a50: 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 f the build proc
1a60: 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ess..*/.#ifndef
1a70: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 _SQLITE3_H_.#def
1a80: 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a ine _SQLITE3_H_.
1a90: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 #include <stdarg
1aa0: 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 .h> /* Neede
1ab0: 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 d for the defini
1ac0: 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 tion of va_list
1ad0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 */../*.** Make s
1ae0: 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 ure we can call
1af0: 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 this stuff from
1b00: 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 C++..*/.#if 0.ex
1b10: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 tern "C" {.#endi
1b20: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 f.../*.** Add th
1b30: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 e ability to ove
1b40: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a rride 'extern'.*
1b50: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
1b60: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 _EXTERN.# define
1b70: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 SQLITE_EXTERN e
1b80: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 xtern.#endif..#i
1b90: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
1ba0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
1bb0: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a _API.#endif.../*
1bc0: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 .** These no-op
1bd0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 macros are used
1be0: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 in front of inte
1bf0: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 rfaces to mark t
1c00: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hose.** interfac
1c10: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 es as either dep
1c20: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 recated or exper
1c30: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 imental. New ap
1c40: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
1c50: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 ould not use dep
1c60: 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 recated interfac
1c70: 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 es - they are su
1c80: 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 pport for backwa
1c90: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
1ca0: 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c lity only. Appl
1cb0: 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 ication writers
1cc0: 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 should be aware
1cd0: 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 that.** experime
1ce0: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 ntal interfaces
1cf0: 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 are subject to c
1d00: 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 hange in point r
1d10: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 eleases..**.** T
1d20: 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 hese macros used
1d30: 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 to resolve to v
1d40: 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 arious kinds of
1d50: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 compiler magic t
1d60: 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e hat.** would gen
1d70: 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 erate warning me
1d80: 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 ssages when they
1d90: 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 were used. But
1da0: 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 that.** compile
1db0: 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 r magic ended up
1dc0: 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 generating such
1dd0: 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 a flurry of bug
1de0: 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 reports.** that
1df0: 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 we have taken i
1e00: 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f t all out and go
1e10: 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 ne back to using
1e20: 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 simple.** noop
1e30: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 macros..*/.#defi
1e40: 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 ne SQLITE_DEPREC
1e50: 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c ATED.#define SQL
1e60: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
1e70: 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 ../*.** Ensure t
1e80: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 hese symbols wer
1e90: 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 e not defined by
1ea0: 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 some previous h
1eb0: 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 eader file..*/.#
1ec0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 ifdef SQLITE_VER
1ed0: 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c SION.# undef SQL
1ee0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 ITE_VERSION.#end
1ef0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
1f00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a _VERSION_NUMBER.
1f10: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 # undef SQLITE_V
1f20: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 ERSION_NUMBER.#e
1f30: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1f40: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
1f50: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
1f60: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a on Numbers.**.**
1f70: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
1f80: 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f ERSION] C prepro
1f90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 cessor macro in
1fa0: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 the sqlite3.h he
1fb0: 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 ader.** evaluate
1fc0: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 s to a string li
1fd0: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 teral that is th
1fe0: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e e SQLite version
1ff0: 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 in the.** forma
2000: 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 t "X.Y.Z" where
2010: 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 X is the major v
2020: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 ersion number (a
2030: 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 lways 3 for.** S
2040: 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 QLite3) and Y is
2050: 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 the minor versi
2060: 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 on number and Z
2070: 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e is the release n
2080: 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 umber.)^.** ^(Th
2090: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f e [SQLITE_VERSIO
20a0: 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 N_NUMBER] C prep
20b0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 rocessor macro r
20c0: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e esolves to an in
20d0: 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 teger.** with th
20e0: 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 e value (X*10000
20f0: 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 00 + Y*1000 + Z)
2100: 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 where X, Y, and
2110: 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a Z are the same.
2120: 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 ** numbers used
2130: 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 in [SQLITE_VERSI
2140: 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 ON].)^.** The SQ
2150: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
2160: 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 BER for any give
2170: 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c n release of SQL
2180: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a ite will also.**
2190: 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 be larger than
21a0: 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d the release from
21b0: 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 which it is der
21c0: 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 ived. Either Y
21d0: 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 will.** be held
21e0: 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 constant and Z w
21f0: 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 ill be increment
2200: 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c ed or else Y wil
2210: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 l be incremented
2220: 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 .** and Z will b
2230: 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e e reset to zero.
2240: 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 .**.** Since ver
2250: 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c sion 3.6.18, SQL
2260: 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 ite source code
2270: 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 has been stored
2280: 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 in the.** <a hre
2290: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f f="http://www.fo
22a0: 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 ssil-scm.org/">F
22b0: 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 ossil configurat
22c0: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a ion management.*
22d0: 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e * system</a>. ^
22e0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 The SQLITE_SOURC
22f0: 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 E_ID macro evalu
2300: 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 ates to.** a str
2310: 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 ing which identi
2320: 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 fies a particula
2330: 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 r check-in of SQ
2340: 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 Lite.** within i
2350: 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ts configuration
2360: 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 management syst
2370: 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 em. ^The SQLITE
2380: 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 _SOURCE_ID.** st
2390: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 ring contains th
23a0: 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 e date and time
23b0: 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 of the check-in
23c0: 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 (UTC) and an SHA
23d0: 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 1.** hash of the
23e0: 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 entire source t
23f0: 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ree..**.** See a
2400: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 lso: [sqlite3_li
2410: 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 bversion()],.**
2420: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 [sqlite3_libvers
2430: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b ion_number()], [
2440: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
2450: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f ()],.** [sqlite_
2460: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b version()] and [
2470: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 sqlite_source_id
2480: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ()]..*/.#define
2490: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 SQLITE_VERSION
24a0: 20 20 20 20 20 20 22 33 2e 38 2e 37 22 0a 23 64 "3.8.7".#d
24b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
24c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 SION_NUMBER 3008
24d0: 30 30 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 007.#define SQLI
24e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 TE_SOURCE_ID
24f0: 20 20 22 32 30 31 34 2d 31 30 2d 30 38 20 31 35 "2014-10-08 15
2500: 3a 35 33 3a 32 31 20 36 34 38 33 64 34 32 36 63 :53:21 6483d426c
2510: 34 63 35 63 37 37 32 63 64 34 39 34 31 32 65 61 4c5c772cd49412ea
2520: 33 37 65 30 66 61 37 61 30 33 37 38 39 30 34 22 37e0fa7a0378904"
2530: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2540: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
2550: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
2560: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
2570: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c sqlite3_version,
2580: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
2590: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
25a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 terfaces provide
25b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
25c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
25d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a LITE_VERSION],.*
25e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
25f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b N_NUMBER], and [
2600: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
2610: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
2620: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 macros.** but a
2630: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 re associated wi
2640: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 th the library i
2650: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 nstead of the he
2660: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 ader file. ^(Ca
2670: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 utious.** progra
2680: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c mmers might incl
2690: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ude assert() sta
26a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 tements in their
26b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a application to.
26c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 ** verify that v
26d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
26e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 y these interfac
26f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 es match the mac
2700: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 ros in.** the he
2710: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69 ader, and thus i
2720: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
2730: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a pplication is.**
2740: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
2750: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 atching library
2760: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 and header files
2770: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 ..**.** <blockqu
2780: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 ote><pre>.** ass
2790: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 ert( sqlite3_lib
27a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
27b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ==SQLITE_VERSION
27c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 _NUMBER );.** as
27d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
27e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
27f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
2800: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 )==0 );.** asser
2810: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
2820: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 3_libversion(),S
2830: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d QLITE_VERSION)==
2840: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 0 );.** </pre></
2850: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
2860: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2870: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e _version[] strin
2880: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
2890: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
28a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
28b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 .** macro. ^The
28c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
28d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
28e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
28f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 to the.** to th
2900: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
2910: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
2920: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ant. The sqlite
2930: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 3_libversion().*
2940: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 * function is pr
2950: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 ovided for use i
2960: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c n DLLs since DLL
2970: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 users usually d
2980: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 o not have.** di
2990: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 rect access to s
29a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 tring constants
29b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 within the DLL.
29c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
29d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
29e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 er() function re
29f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 turns an integer
2a00: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 equal to.** [SQ
2a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
2a20: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 BER]. ^The sqli
2a30: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 te3_sourceid() f
2a40: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
2a50: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
2a60: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 a string consta
2a70: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 nt whose value i
2a80: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 s the same as th
2a90: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f e .** [SQLITE_SO
2aa0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 URCE_ID] C prepr
2ab0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a ocessor macro..*
2ac0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2ad0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
2ae0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
2af0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 urce_id()]..*/.S
2b00: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2b10: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
2b20: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f sion[] = SQLITE_
2b30: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f VERSION;.SQLITE_
2b40: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2b50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
2b60: 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 on(void);.SQLITE
2b70: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2b80: 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 *sqlite3_sourcei
2b90: 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f d(void);.SQLITE_
2ba0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2bb0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
2bc0: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 r(void);../*.**
2bd0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
2be0: 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 me Library Compi
2bf0: 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 lation Options D
2c00: 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a iagnostics.**.**
2c10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
2c20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
2c30: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
2c40: 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 rns 0 or 1 .** i
2c50: 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 ndicating whethe
2c60: 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 r the specified
2c70: 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e option was defin
2c80: 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c ed at .** compil
2c90: 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 e time. ^The SQ
2ca0: 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 LITE_ prefix may
2cb0: 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d be omitted from
2cc0: 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 the .** option
2cd0: 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 name passed to s
2ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
2cf0: 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a tion_used(). .*
2d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2d10: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
2d20: 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 get() function a
2d30: 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a llows iterating.
2d40: 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 ** over the list
2d50: 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 of options that
2d60: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 were defined at
2d70: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 compile time by
2d80: 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 .** returning th
2d90: 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 e N-th compile t
2da0: 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e ime option strin
2db0: 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 g. ^If N is out
2dc0: 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 of range,.** sq
2dd0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
2de0: 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e ion_get() return
2df0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2e00: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 . ^The SQLITE_
2e10: 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d .** prefix is om
2e20: 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 itted from any s
2e30: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2e40: 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by .** sqlite3_c
2e50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
2e60: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f ()..**.** ^Suppo
2e70: 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e rt for the diagn
2e80: 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 ostic functions
2e90: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
2ea0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 ption_used().**
2eb0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 and sqlite3_comp
2ec0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 ileoption_get()
2ed0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 may be omitted b
2ee0: 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 y specifying the
2ef0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 .** [SQLITE_OMI
2f00: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f T_COMPILEOPTION_
2f10: 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 DIAGS] option at
2f20: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a compile time..*
2f30: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 *.** See also: S
2f40: 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 QL functions [sq
2f50: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 lite_compileopti
2f60: 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a on_used()] and.*
2f70: 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c * [sqlite_compil
2f80: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 eoption_get()] a
2f90: 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f nd the [compile_
2fa0: 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e options pragma].
2fb0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
2fc0: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f TE_OMIT_COMPILEO
2fd0: 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 PTION_DIAGS.SQLI
2fe0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2ff0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3000: 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 _used(const char
3010: 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c *zOptName);.SQL
3020: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
3030: 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 ar *sqlite3_comp
3040: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e ileoption_get(in
3050: 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a t N);.#endif../*
3060: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
3070: 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 st To See If The
3080: 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 Library Is Thre
3090: 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 adsafe.**.** ^Th
30a0: 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 e sqlite3_thread
30b0: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 safe() function
30c0: 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 returns zero if
30d0: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 and only if.** S
30e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c QLite was compil
30f0: 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 ed with mutexing
3100: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 code omitted du
3110: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c e to the.** [SQL
3120: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
3130: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
3140: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f ion being set to
3150: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 0..**.** SQLite
3160: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 can be compiled
3170: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 with or without
3180: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a mutexes. When.
3190: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 HREADSAFE] C pre
31b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
31c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 is 1 or 2, mutex
31d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
31e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 d and SQLite is
31f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 threadsafe. Whe
3200: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 n the.** [SQLITE
3210: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 _THREADSAFE] mac
3220: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 ro is 0, .** the
3230: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 mutexes are omi
3240: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 tted. Without t
3250: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 he mutexes, it i
3260: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f s not safe.** to
3270: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 use SQLite conc
3280: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f urrently from mo
3290: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 re than one thre
32a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 ad..**.** Enabli
32b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 ng mutexes incur
32c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 s a measurable p
32d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c erformance penal
32e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 ty..** So if spe
32f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 ed is of utmost
3300: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d importance, it m
3310: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 akes sense to di
3320: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 sable.** the mut
3330: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d exes. But for m
3340: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d aximum safety, m
3350: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 utexes should be
3360: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 enabled..** ^Th
3370: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
3380: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
3390: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
33a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
33b0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
33c0: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 d by an applicat
33d0: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ion to make sure
33e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 that the.** ver
33f0: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 sion of SQLite t
3400: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e hat it is linkin
3410: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f g against was co
3420: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
3430: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 he desired setti
3440: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ng of the [SQLIT
3450: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
3460: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 cro..**.** This
3470: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 interface only r
3480: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f eports on the co
3490: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 mpile-time mutex
34a0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 setting.** of t
34b0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
34c0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 DSAFE] flag. If
34d0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
34e0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 led with.** SQLI
34f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 TE_THREADSAFE=1
3500: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 or =2 then mutex
3510: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 es are enabled b
3520: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a y default but.**
3530: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 can be fully or
3540: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 partially disab
3550: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c led using a call
3560: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
3570: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 fig()].** with t
3580: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 he verbs [SQLITE
3590: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
35a0: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 READ], [SQLITE_C
35b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
35c0: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 D],.** or [SQLIT
35d0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e E_CONFIG_MUTEX].
35e0: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 ^(The return v
35f0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 alue of the.** s
3600: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
3610: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f e() function sho
3620: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 ws only the comp
3630: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 ile-time setting
3640: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 of.** thread sa
3650: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 fety, not any ru
3660: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 n-time changes t
3670: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d o that setting m
3680: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 ade by.** sqlite
3690: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 3_config(). In o
36a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
36b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
36c0: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 m sqlite3_thread
36d0: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 safe().** is unc
36e0: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 hanged by calls
36f0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
3700: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 g().)^.**.** See
3710: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
3720: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 mode] documentat
3730: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
3740: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
3750: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
3760: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 t sqlite3_thread
3770: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a safe(void);../*.
3780: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
3790: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
37a0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f Handle.** KEYWO
37b0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 RDS: {database c
37c0: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 onnection} {data
37d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
37e0: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 }.**.** Each ope
37f0: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
3800: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 e is represented
3810: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f by a pointer to
3820: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a an instance of.
3830: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 ** the opaque st
3840: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 ructure named "s
3850: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 qlite3". It is
3860: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 useful to think
3870: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a of an sqlite3.**
3880: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f pointer as an o
3890: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c bject. The [sql
38a0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
38b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
38c0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
38d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
38e0: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 erfaces are its
38f0: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e constructors, an
3900: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
3910: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
3920: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 te3_close_v2()]
3930: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 are its destruct
3940: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 ors. There are
3950: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e many other.** in
3960: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
3970: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
3980: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
3990: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
39a0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
39b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
39c0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
39d0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
39e0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
39f0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
3a00: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
3a10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
3a20: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
3a30: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
3a40: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a t Integer Types.
3a50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
3a60: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
3a70: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
3a80: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
3a90: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
3aa0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
3ab0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
3ac0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
3ad0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
3ae0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
3af0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
3b00: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
3b10: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
3b20: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
3b30: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
3b40: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
3b50: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
3b60: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
3b70: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
3b80: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
3b90: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
3ba0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
3bb0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y only..**.** ^T
3bc0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 he sqlite3_int64
3bd0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 and sqlite_int6
3be0: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
3bf0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
3c00: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 .** between -922
3c10: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 3372036854775808
3c20: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 and +9223372036
3c30: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 854775807 inclus
3c40: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 ive. ^The.** sq
3c50: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 lite3_uint64 and
3c60: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
3c70: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 ypes can store i
3c80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a nteger values .*
3c90: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
3ca0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 +184467440737095
3cb0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 51615 inclusive.
3cc0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
3cd0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 E_INT64_TYPE. t
3ce0: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e ypedef SQLITE_IN
3cf0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
3d00: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
3d10: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 unsigned SQLITE
3d20: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
3d30: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 te_uint64;.#elif
3d40: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
3d50: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f R) || defined(__
3d60: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 BORLANDC__). ty
3d70: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 pedef __int64 sq
3d80: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
3d90: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f pedef unsigned _
3da0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
3db0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 nt64;.#else. ty
3dc0: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 pedef long long
3dd0: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 int sqlite_int64
3de0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
3df0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 gned long long i
3e00: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nt sqlite_uint64
3e10: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 ;.#endif.typedef
3e20: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
3e30: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 lite3_int64;.typ
3e40: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 edef sqlite_uint
3e50: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64 sqlite3_uint6
3e60: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 4;../*.** If com
3e70: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f piling for a pro
3e80: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b cessor that lack
3e90: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 s floating point
3ea0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 support,.** sub
3eb0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 stitute integer
3ec0: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 for floating-poi
3ed0: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 nt..*/.#ifdef SQ
3ee0: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 LITE_OMIT_FLOATI
3ef0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e NG_POINT.# defin
3f00: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 e double sqlite3
3f10: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f _int64.#endif../
3f20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
3f30: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 losing A Databas
3f40: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a e Connection.**.
3f50: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
3f60: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 close() and sqli
3f70: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 te3_close_v2() r
3f80: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 outines are dest
3f90: 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 ructors.** for t
3fa0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
3fb0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ect..** ^Calls t
3fc0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 o sqlite3_close(
3fd0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
3fe0: 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 ose_v2() return
3ff0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a [SQLITE_OK] if.*
4000: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 * the [sqlite3]
4010: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 object is succes
4020: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 sfully destroyed
4030: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 and all associa
4040: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ted.** resources
4050: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 are deallocated
4060: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
4070: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4080: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 ion is associate
4090: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
40a0: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 ed prepared.** s
40b0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 tatements or unf
40c0: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
40d0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 backup objects t
40e0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 hen sqlite3_clos
40f0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 e().** will leav
4100: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
4110: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 onnection open a
4120: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
4130: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 E_BUSY]..** ^If
4140: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
4150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
4160: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 h unfinalized pr
4170: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
4180: 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 s.** and/or unfi
4190: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
41a0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 ackups, then the
41b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
41c0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 tion becomes.**
41d0: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d an unusable "zom
41e0: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 bie" which will
41f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 automatically be
4200: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 deallocated whe
4210: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 n the.** last pr
4220: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
4230: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 is finalized or
4240: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
4250: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 3_backup is.** f
4260: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 inished. The sq
4270: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
4280: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
4290: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 tended for use w
42a0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 ith.** host lang
42b0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 uages that are g
42c0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 arbage collected
42d0: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 , and where the
42e0: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a order in which.*
42f0: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 * destructors ar
4300: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 e called is arbi
4310: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 trary..**.** App
4320: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
4330: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
4340: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 ze | finalize] a
4350: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
4360: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 tements],.** [sq
4370: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
4380: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 | close] all [B
4390: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e LOB handles], an
43a0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 d .** [sqlite3_b
43b0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 ackup_finish | f
43c0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 inish] all [sqli
43d0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
43e0: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a cts associated.*
43f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 * with the [sqli
4400: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f te3] object prio
4410: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 r to attempting
4420: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a to close the obj
4430: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c ect. ^If.** sql
4440: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
4450: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b is called on a [
4460: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4470: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 ion] that still
4480: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 has.** outstandi
4490: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ng [prepared sta
44a0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
44b0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 handles], and/or
44c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
44d0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 kup] objects the
44e0: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 n it returns [SQ
44f0: 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 LITE_OK] and the
4500: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a deallocation.**
4510: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 of resources is
4520: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
4530: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 all [prepared st
4540: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 atements], [BLOB
4550: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e handles],.** an
4560: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 d [sqlite3_backu
4570: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 p] objects are a
4580: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a lso destroyed..*
4590: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c *.** ^If an [sql
45a0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
45b0: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 destroyed while
45c0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
45d0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 open,.** the tr
45e0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
45f0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
4600: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
4610: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f e C parameter to
4620: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
4630: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 C)] and [sqlite3
4640: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a _close_v2(C)].**
4650: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
4660: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
4670: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 r or an [sqlite3
4680: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 ] object pointer
4690: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
46a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
46b0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
46c0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
46d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
46e0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 ], and not previ
46f0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a ously closed..**
4700: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
4710: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 3_close() or sql
4720: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
4730: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
4740: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ter.** argument
4750: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
4760: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 -op..*/.SQLITE_A
4770: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
4780: 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a lose(sqlite3*);.
4790: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
47a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
47b0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
47c0: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 * The type for a
47d0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
47e0: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c on..** This is l
47f0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 egacy and deprec
4800: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 ated. It is inc
4810: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 luded for histor
4820: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ical.** compatib
4830: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 ility and is not
4840: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a documented..*/.
4850: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 typedef int (*sq
4860: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 lite3_callback)(
4870: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
4880: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a , char**);../*.*
4890: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d * CAPI3REF: One-
48a0: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 Step Query Execu
48b0: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a tion Interface.*
48c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
48d0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 _exec() interfac
48e0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e e is a convenien
48f0: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e ce wrapper aroun
4900: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 d.** [sqlite3_pr
4910: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
4920: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 lite3_step()], a
4930: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 nd [sqlite3_fina
4940: 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 lize()],.** that
4950: 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 allows an appli
4960: 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 cation to run mu
4970: 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 ltiple statement
4980: 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 s of SQL.** with
4990: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 out having to us
49a0: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 e a lot of C cod
49b0: 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 e. .**.** ^The s
49c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e qlite3_exec() in
49d0: 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 terface runs zer
49e0: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 o or more UTF-8
49f0: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 encoded,.** semi
4a00: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 colon-separate S
4a10: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 QL statements pa
4a20: 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e ssed into its 2n
4a30: 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 d argument,.** i
4a40: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 n the context of
4a50: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
4a60: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 onnection] passe
4a70: 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a d in as its 1st.
4a80: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 ** argument. ^I
4a90: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 f the callback f
4aa0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 unction of the 3
4ab0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a rd argument to.*
4ac0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
4ad0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
4ae0: 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 en it is invoked
4af0: 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 for each result
4b00: 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f row.** coming o
4b10: 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 ut of the evalua
4b20: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
4b30: 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 ts. ^The 4th ar
4b40: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
4b50: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
4b60: 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 elayed through t
4b70: 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 o the 1st argume
4b80: 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 nt of each.** ca
4b90: 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f llback invocatio
4ba0: 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c n. ^If the call
4bb0: 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 back pointer to
4bc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
4bd0: 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 * is NULL, then
4be0: 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 no callback is e
4bf0: 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 ver invoked and
4c00: 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a result rows are.
4c10: 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a ** ignored..**.*
4c20: 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f * ^If an error o
4c30: 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c ccurs while eval
4c40: 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 uating the SQL s
4c50: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 tatements passed
4c60: 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
4c70: 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 _exec(), then ex
4c80: 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 ecution of the c
4c90: 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 urrent statement
4ca0: 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 stops and.** su
4cb0: 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 bsequent stateme
4cc0: 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e nts are skipped.
4cd0: 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 ^If the 5th pa
4ce0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
4cf0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
4d00: 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e not NULL then an
4d10: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 y error message
4d20: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
4d30: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a memory obtained.
4d40: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
4d50: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 _malloc()] and p
4d60: 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 assed back throu
4d70: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
4d80: 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 eter..** To avoi
4d90: 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 d memory leaks,
4da0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
4db0: 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 should invoke [s
4dc0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a qlite3_free()].*
4dd0: 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 * on error messa
4de0: 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 ge strings retur
4df0: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 ned through the
4e00: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 5th parameter of
4e10: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 .** of sqlite3_e
4e20: 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 xec() after the
4e30: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
4e40: 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 ring is no longe
4e50: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 r needed..** ^If
4e60: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
4e70: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
4e80: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ec() is not NULL
4e90: 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a and no errors.*
4ea0: 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 * occur, then sq
4eb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 lite3_exec() set
4ec0: 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e s the pointer in
4ed0: 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 its 5th paramet
4ee0: 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 er to.** NULL be
4ef0: 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a fore returning..
4f00: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c **.** ^If an sql
4f10: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c ite3_exec() call
4f20: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
4f30: 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 -zero, the sqlit
4f40: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 e3_exec().** rou
4f50: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c tine returns SQL
4f60: 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 ITE_ABORT withou
4f70: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 t invoking the c
4f80: 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e allback again an
4f90: 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e d.** without run
4fa0: 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 ning any subsequ
4fb0: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ent SQL statemen
4fc0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 ts..**.** ^The 2
4fd0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 nd argument to t
4fe0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
4ff0: 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 ) callback funct
5000: 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 ion is the.** nu
5010: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
5020: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 in the result.
5030: 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e ^The 3rd argumen
5040: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
5050: 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 _exec().** callb
5060: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 ack is an array
5070: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
5080: 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 trings obtained
5090: 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 as if from.** [s
50a0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
50b0: 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 xt()], one for e
50c0: 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 ach column. ^If
50d0: 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 an element of a
50e0: 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 .** result row i
50f0: 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 s NULL then the
5100: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 corresponding st
5110: 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 ring pointer for
5120: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
5130: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
5140: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
5150: 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 r. ^The 4th arg
5160: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 ument to the.**
5170: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
5180: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
5190: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
51a0: 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 to strings where
51b0: 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 each.** entry r
51c0: 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 epresents the na
51d0: 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 me of correspond
51e0: 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ing result colum
51f0: 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a n as obtained.**
5200: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
5210: 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a olumn_name()]..*
5220: 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 *.** ^If the 2nd
5230: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
5240: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
5250: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
5260: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
5270: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
5280: 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 or a pointer th
5290: 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 at contains only
52a0: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f whitespace and/
52b0: 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 or .** SQL comme
52c0: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c nts, then no SQL
52d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
52e0: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 evaluated and th
52f0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 e database.** is
5300: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a not changed..**
5310: 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 .** Restrictions
5320: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
5330: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 <li> The applica
5340: 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 tion must insure
5350: 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 that the 1st pa
5360: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
5370: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 e3_exec().**
5380: 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 is a valid and
5390: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
53a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
53b0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 <li> The applica
53c0: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c tion must not cl
53d0: 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 ose the [databas
53e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
53f0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 ecified by.**
5400: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d the 1st param
5410: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
5420: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c exec() while sql
5430: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 ite3_exec() is r
5440: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 unning..** <li>
5450: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
5460: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 must not modify
5470: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
5480: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e t text passed in
5490: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 to.** the 2
54a0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
54b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 sqlite3_exec() w
54c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 hile sqlite3_exe
54d0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a c() is running..
54e0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 ** </ul>.*/.SQLI
54f0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
5500: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 e3_exec(. sqlit
5510: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 e3*,
5520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5530: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
5540: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
5550: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 onst char *sql,
5560: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5570: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
5580: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
5590: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c */. int (*call
55a0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c back)(void*,int,
55b0: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 char**,char**),
55c0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e /* Callback fun
55d0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
55e0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5600: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 /* 1st arg
5610: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 ument to callbac
5620: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 k */. char **er
5630: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 rmsg
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5650: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
5660: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
5670: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
5680: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a F: Result Codes.
5690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 ** KEYWORDS: {re
56a0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
56b0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e tions}.**.** Man
56c0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f y SQLite functio
56d0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 ns return an int
56e0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 eger result code
56f0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 from the set sh
5700: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f own.** here in o
5710: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 rder to indicate
5720: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
5730: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
5740: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
5750: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
5760: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
5770: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
5780: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 also: [extended
5790: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 result code defi
57a0: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 nitions].*/.#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
57c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
57d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
57e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
57f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
5800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5810: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
5820: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
5830: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
5840: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
5850: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
5860: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
5870: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
5880: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
5890: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
58a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
58b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
58c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
58e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
58f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
5900: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
5910: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
5920: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
5930: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
5940: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
5950: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
5960: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
5970: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
5980: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
5990: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
59a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
59b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
59c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
59d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
59f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
5a00: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
5a10: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
5a20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5a30: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
5a40: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
5a50: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
5a60: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
5a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5a80: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
5a90: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
5aa0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
5ab0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
5ad0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
5ae0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
5af0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
5b00: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
5b10: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
5b20: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 12 /* Unkn
5b30: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 own opcode in sq
5b40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
5b50: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ol() */.#define
5b60: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 SQLITE_FULL
5b70: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 13 /* Inser
5b80: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 tion failed beca
5b90: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 use database is
5ba0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 full */.#define
5bb0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
5bc0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 14 /* Unabl
5bd0: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
5be0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
5bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
5c00: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f OTOCOL 15 /
5c10: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 * Database lock
5c20: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a protocol error *
5c30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5c40: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 _EMPTY 16
5c50: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 /* Database is
5c60: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e empty */.#defin
5c70: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 e SQLITE_SCHEMA
5c80: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 17 /* The
5c90: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
5ca0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 changed */.#def
5cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 ine SQLITE_TOOBI
5cc0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 G 18 /* S
5cd0: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 tring or BLOB ex
5ce0: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 ceeds size limit
5cf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5d00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 TE_CONSTRAINT 1
5d10: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 9 /* Abort due
5d20: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 to constraint v
5d30: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 iolation */.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 ine SQLITE_MISMA
5d50: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 TCH 20 /* D
5d60: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 ata type mismatc
5d70: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c h */.#define SQL
5d80: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 ITE_MISUSE
5d90: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 21 /* Library
5da0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 used incorrectly
5db0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
5dc0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 TE_NOLFS 2
5dd0: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 2 /* Uses OS f
5de0: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 eatures not supp
5df0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f orted on host */
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5e10: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 AUTH 23
5e20: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f /* Authorizatio
5e30: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 ine SQLITE_FORMA
5e50: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 T 24 /* A
5e60: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 uxiliary databas
5e70: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a e format error *
5e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5e90: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 _RANGE 25
5ea0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 /* 2nd paramet
5eb0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
5ec0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 nd out of range
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ee0: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 E_NOTADB 26
5ef0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 /* File opene
5f00: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 d that is not a
5f10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f database file */
5f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5f30: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 NOTICE 27
5f40: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e /* Notification
5f50: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c s from sqlite3_l
5f60: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 og() */.#define
5f70: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 SQLITE_WARNING
5f80: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 28 /* Warni
5f90: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ngs from sqlite3
5fa0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e _log() */.#defin
5fb0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
5fc0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
5fd0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
5fe0: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
5ff0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6000: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
6010: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
6020: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
6030: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
6040: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
6050: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
6060: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
6070: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
6080: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
6090: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
60a0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d ode definitions}
60b0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 .**.** In its de
60c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
60d0: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 ion, SQLite API
60e0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
60f0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 one of 30 intege
6100: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 r.** [result cod
6110: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 es]. However, e
6120: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 xperience has sh
6130: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 own that many of
6140: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 .** these result
6150: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 codes are too c
6160: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 oarse-grained.
6170: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 They do not prov
6180: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 ide as.** much i
6190: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
61a0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f problems as pro
61b0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c grammers might l
61c0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f ike. In an effo
61d0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 rt to.** address
61e0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 this, newer ver
61f0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
6200: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 (version 3.3.8 a
6210: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
6220: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
6230: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
6240: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
6250: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
6260: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
6270: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
6280: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 These [extended
6290: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 result codes] a
62a0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 re enabled or di
62b0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 sabled.** on a p
62c0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e er database conn
62d0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 ection basis usi
62e0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
62f0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
6300: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e lt_codes()] API.
6310: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 Or, the extend
6320: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 ed code for.** t
6330: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
6340: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 rror can be obta
6350: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
6360: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
6370: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 errcode()]..*/.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6390: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 ERR_READ
63a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
63b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<8)).#d
63c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
63d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
63e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
63f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RR | (2<<8)).#de
6400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
6410: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 R_WRITE
6420: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
6430: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 R | (3<<8)).#def
6440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
6450: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 _FSYNC
6460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
6470: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
6480: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
6490: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 DIR_FSYNC
64a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
64b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
64c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
64d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 RUNCATE
64e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
64f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (6<<8)).#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
6510: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 TAT
6520: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
6530: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
6540: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c SQLITE_IOERR_UNL
6550: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
6560: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
6570: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
6580: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f QLITE_IOERR_RDLO
6590: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 CK (S
65a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
65b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
65c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
65d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 E (SQ
65e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 LITE_IOERR | (10
65f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6600: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
6610: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ED (SQ
6620: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 LITE_IOERR | (11
6630: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6640: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d LITE_IOERR_NOMEM
6650: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6660: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 LITE_IOERR | (12
6670: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6680: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
6690: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 S (SQ
66a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 LITE_IOERR | (13
66b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
66c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b LITE_IOERR_CHECK
66d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 RESERVEDLOCK (SQ
66e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 LITE_IOERR | (14
66f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6700: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 LITE_IOERR_LOCK
6710: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 LITE_IOERR | (15
6730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6740: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 LITE_IOERR_CLOSE
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 LITE_IOERR | (16
6770: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6780: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 LITE_IOERR_DIR_C
6790: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 LOSE (SQ
67a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 LITE_IOERR | (17
67b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
67c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 LITE_IOERR_SHMOP
67d0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 EN (SQ
67e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 LITE_IOERR | (18
67f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6800: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 LITE_IOERR_SHMSI
6810: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ZE (SQ
6820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 LITE_IOERR | (19
6830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6840: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f LITE_IOERR_SHMLO
6850: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 CK (SQ
6860: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 LITE_IOERR | (20
6870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6880: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 LITE_IOERR_SHMMA
6890: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 P (SQ
68a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 LITE_IOERR | (21
68b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
68c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 LITE_IOERR_SEEK
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
68e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 LITE_IOERR | (22
68f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6900: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
6910: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 E_NOENT (SQ
6920: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 LITE_IOERR | (23
6930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6940: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 LITE_IOERR_MMAP
6950: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
6960: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 LITE_IOERR | (24
6970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6980: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 LITE_IOERR_GETTE
6990: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 MPPATH (SQ
69a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 LITE_IOERR | (25
69b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
69c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 LITE_IOERR_CONVP
69d0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 ATH (SQ
69e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 LITE_IOERR | (26
69f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6a00: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 LITE_LOCKED_SHAR
6a10: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 EDCACHE (SQ
6a20: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 LITE_LOCKED | (
6a30: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
6a40: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 QLITE_BUSY_RECOV
6a50: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 ERY (S
6a60: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 QLITE_BUSY |
6a70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
6a80: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 SQLITE_BUSY_SNAP
6a90: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 SHOT (
6aa0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 SQLITE_BUSY |
6ab0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
6ac0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
6ad0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 _NOTEMPDIR
6ae0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
6af0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
6b10: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 EN_ISDIR
6b20: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
6b30: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 EN | (2<<8)).#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
6b50: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 OPEN_FULLPATH
6b60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
6b70: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OPEN | (3<<8)).#
6b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
6b90: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 NTOPEN_CONVPATH
6ba0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
6bb0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 NTOPEN | (4<<8))
6bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6bd0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
6be0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
6bf0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
6c00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
6c10: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
6c20: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
6c30: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
6c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
6c50: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
6c60: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
6c70: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
6c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
6c90: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f LITE_READONLY_RO
6ca0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 LLBACK (SQ
6cb0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
6cc0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
6cd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
6ce0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 DBMOVED (
6cf0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
6d00: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
6d10: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 e SQLITE_ABORT_R
6d20: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 OLLBACK
6d30: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c (SQLITE_ABORT |
6d40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
6d50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6d60: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 NT_CHECK
6d70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6d80: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NT | (1<<8)).#de
6d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
6da0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f TRAINT_COMMITHOO
6db0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 K (SQLITE_CONS
6dc0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 TRAINT | (2<<8))
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6de0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 CONSTRAINT_FOREI
6df0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f GNKEY (SQLITE_
6e00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c CONSTRAINT | (3<
6e10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
6e20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
6e30: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c UNCTION (SQL
6e40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
6e50: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
6e60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6e70: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 NT_NOTNULL
6e80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6e90: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 NT | (5<<8)).#de
6ea0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
6eb0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 TRAINT_PRIMARYKE
6ec0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
6ed0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 TRAINT | (6<<8))
6ee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6ef0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 CONSTRAINT_TRIGG
6f00: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f ER (SQLITE_
6f10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c CONSTRAINT | (7<
6f20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
6f30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 ITE_CONSTRAINT_U
6f40: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c NIQUE (SQL
6f50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
6f60: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
6f70: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
6f80: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 NT_VTAB
6f90: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
6fa0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 NT | (9<<8)).#de
6fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
6fc0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 TRAINT_ROWID
6fd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
6fe0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 TRAINT |(10<<8))
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7000: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 NOTICE_RECOVER_W
7010: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f AL (SQLITE_
7020: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 NOTICE | (1<<8))
7030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7040: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 NOTICE_RECOVER_R
7050: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f OLLBACK (SQLITE_
7060: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 NOTICE | (2<<8))
7070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7080: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 WARNING_AUTOINDE
7090: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f X (SQLITE_
70a0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 WARNING | (1<<8)
70b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
70c0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 _AUTH_USER
70d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
70e0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a _AUTH | (1<<8)).
70f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7100: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 Flags For File
7110: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a Open Operations.
7120: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 **.** These bit
7130: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e values are inten
7140: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 ded for use in t
7150: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 he.** 3rd parame
7160: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
7170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
7180: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 nterface and.**
7190: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d in the 4th param
71a0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c eter to the [sql
71b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
71c0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 method..*/.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
71e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
71f0: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 0x00000001 /* O
7200: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7210: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7220: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
7230: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
7240: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 0x00000002 /* O
7250: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7260: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
7280: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
7290: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 0x00000004 /* O
72a0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
72b0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
72c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
72d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
72e0: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 0x00000008 /* V
72f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7300: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
7310: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
7320: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 0x00000010 /* V
7330: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7340: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 ne SQLITE_OPEN_A
7350: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 UTOPROXY
7360: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 0x00000020 /* V
7370: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7380: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 ne SQLITE_OPEN_U
7390: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RI
73a0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 0x00000040 /* O
73b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
73c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
73d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
73e0: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 EMORY
73f0: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 0x00000080 /* O
7400: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7410: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7420: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
7430: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
7440: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 0x00000100 /* V
7450: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7460: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
7470: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
7480: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 0x00000200 /* V
7490: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
74a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
74b0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
74c0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 0x00000400 /* V
74d0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
74e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
74f0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
7500: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 0x00000800 /* V
7510: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7520: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
7530: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
7540: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 0x00001000 /* V
7550: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
7560: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
7570: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
7580: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 0x00002000 /* V
7590: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
75a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
75b0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
75c0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 0x00004000 /* V
75d0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
75e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
75f0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
7600: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 0x00008000 /* O
7610: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7620: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7630: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
7640: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
7650: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 0x00010000 /* O
7660: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7670: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7680: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
7690: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
76a0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 0x00020000 /* O
76b0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
76c0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
76d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 ne SQLITE_OPEN_P
76e0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 RIVATECACHE
76f0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 0x00040000 /* O
7700: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
7710: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
7720: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 ne SQLITE_OPEN_W
7730: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AL
7740: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 0x00080000 /* V
7750: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 FS only */../* R
7760: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 eserved:
7770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
7780: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 0x00F00000 */..
7790: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
77a0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 Device Character
77b0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 istics.**.** The
77c0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
77d0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f ristics method o
77e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
77f0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 o_methods].** ob
7800: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ject returns an
7810: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
7820: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 a vector of the
7830: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 se.** bit values
7840: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 expressing I/O
7850: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 characteristics
7860: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 of the mass stor
7870: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 age.** device th
7880: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c at holds the fil
7890: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 e that the [sqli
78a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
78b0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a ** refers to..**
78c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
78d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
78e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
78f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
7900: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
7910: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
7920: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
7930: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
7940: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
7950: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
7960: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
7970: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
7980: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
7990: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
79a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
79b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
79c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
79d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
79e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
79f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
7a00: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
7a10: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
7a20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
7a30: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
7a40: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
7a50: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
7a60: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
7a70: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
7a80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
7a90: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
7aa0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
7ab0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
7ac0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
7ad0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
7ae0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
7af0: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 xWrite(). The
7b00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
7b10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
7b20: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
7b30: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 that.** after re
7b40: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 boot following a
7b50: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 crash or power
7b60: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 loss, the only b
7b70: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c ytes in a.** fil
7b80: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 e that were writ
7b90: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 ten at the appli
7ba0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 cation level mig
7bb0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a ht have changed.
7bc0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 ** and that adja
7bd0: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e cent bytes, even
7be0: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 bytes within th
7bf0: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 e same sector ar
7c00: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 e.** guaranteed
7c10: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e to be unchanged.
7c20: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
7c30: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
7c40: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 HEN_OPEN.** flag
7c50: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 indicate that a
7c60: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
7c70: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 deleted when ope
7c80: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 n. The.** SQLIT
7c90: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
7ca0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 E flag indicates
7cb0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 that the file i
7cc0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c s on.** read-onl
7cd0: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e y media and cann
7ce0: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 ot be changed ev
7cf0: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 en by processes
7d00: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 with.** elevated
7d10: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a privileges..*/.
7d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7d30: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
7d40: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
7d50: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
7d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7d70: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
7d80: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
7d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
7db0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7dc0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
7dd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
7de0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
7df0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
7e00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
7e10: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
7e20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
7e30: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
7e40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
7e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
7e60: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
7e70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
7e80: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
7e90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
7ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7eb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
7ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
7ed0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
7ee0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7ef0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
7f00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
7f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7f20: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
7f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
7f40: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
7f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
7f60: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
7f70: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
7f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
7f90: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
7fa0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
7fb0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
7fc0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
7fd0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
7fe0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 0x00001000.#defi
7ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8000: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 IMMUTABLE
8010: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
8020: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
8030: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 F: File Locking
8040: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c Levels.**.** SQL
8050: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 ite uses one of
8060: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
8070: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
8080: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 nd.** argument t
8090: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 o calls it makes
80a0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 to the xLock()
80b0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 and xUnlock() me
80c0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b thods.** of an [
80d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
80e0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 ds] object..*/.#
80f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
8100: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 CK_NONE
8110: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
8120: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 E_LOCK_SHARED
8130: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
8140: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8150: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 VED 2.#defi
8160: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 ne SQLITE_LOCK_P
8170: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 ENDING 3.#
8180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
8190: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 CK_EXCLUSIVE
81a0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 4../*.** CAPI3R
81b0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 EF: Synchronizat
81c0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a ion Type Flags.*
81d0: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 *.** When SQLite
81e0: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 invokes the xSy
81f0: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 nc() method of a
8200: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
8210: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
8220: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 it uses a combi
8230: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 nation of.** the
8240: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 se integer value
8250: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 s as the second
8260: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
8270: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f When the SQLITE_
8280: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c SYNC_DATAONLY fl
8290: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d ag is used, it m
82a0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a eans that the.**
82b0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 sync operation
82c0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c only needs to fl
82d0: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 ush data to mass
82e0: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 storage. Inode
82f0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8300: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 need not be flus
8310: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 hed. If the lowe
8320: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 r four bits of t
8330: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c he flag.** equal
8340: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
8350: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 MAL, that means
8360: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 to use normal fs
8370: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e ync() semantics.
8380: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 .** If the lower
8390: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c four bits equal
83a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
83b0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a L, that means.**
83c0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 to use Mac OS X
83d0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 style fullsync
83e0: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 instead of fsync
83f0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 ()..**.** Do not
8400: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c confuse the SQL
8410: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
8420: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f and SQLITE_SYNC_
8430: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 FULL flags.** wi
8440: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 th the [PRAGMA s
8450: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d ynchronous]=NORM
8460: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 AL and [PRAGMA s
8470: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c ynchronous]=FULL
8480: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 .** settings. T
8490: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 he [synchronous
84a0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e pragma] determin
84b0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f es when calls to
84c0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 the.** xSync VF
84d0: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 S method occur a
84e0: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f nd applies unifo
84f0: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 rmly across all
8500: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 platforms..** Th
8510: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
8520: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
8530: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 SYNC_FULL flags
8540: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a determine how.**
8550: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 energetic or ri
8560: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 gorous or forcef
8570: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 ul the sync oper
8580: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a ations are and.*
8590: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 * only make a di
85a0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 fference on Mac
85b0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 OSX for the defa
85c0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e ult SQLite code.
85d0: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 .** (Third-party
85e0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
85f0: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 ions might also
8600: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
8610: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 tion.** between
8620: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
8630: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
8640: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f NC_FULL, but amo
8650: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 ng the.** operat
8660: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 ing systems nati
8670: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 vely supported b
8680: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d y SQLite, only M
8690: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 ac OSX.** cares
86a0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 about the differ
86b0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e ence.).*/.#defin
86c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
86d0: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 RMAL 0x00
86e0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
86f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 TE_SYNC_FULL
8700: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 0x00003.#d
8710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
8720: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 C_DATAONLY
8730: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x00010../*.** C
8740: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
8750: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 rface Open File
8760: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 Handle.**.** An
8770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
8780: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
8790: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
87a0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
87b0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 3_vfs | OS inter
87c0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e face layer]. In
87d0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 dividual OS inte
87e0: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 rface.** impleme
87f0: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
8800: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
8810: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
8820: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
8830: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
8840: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
8850: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
8860: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
8870: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
8880: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8890: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
88a0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
88b0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
88c0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
88d0: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
88e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
88f0: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
8910: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
8920: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
8930: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
8940: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
8950: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
8960: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
8970: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
8980: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
8990: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
89a0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a ethods Object.**
89b0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f .** Every file o
89c0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 pened by the [sq
89d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
89e0: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 method populate
89f0: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s an.** [sqlite3
8a00: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f _file] object (o
8a10: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 r, more commonly
8a20: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 , a subclass of
8a30: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
8a40: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 file] object) wi
8a50: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 th a pointer to
8a60: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
8a70: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 his object..** T
8a80: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
8a90: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 es the methods u
8aa0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 sed to perform v
8ab0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e arious operation
8ac0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 s.** against the
8ad0: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 open file repre
8ae0: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 sented by the [s
8af0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
8b00: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ect..**.** If th
8b10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
8b20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 Open] method set
8b30: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 s the sqlite3_fi
8b40: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
8b50: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e ent .** to a non
8b60: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
8b70: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
8b80: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 io_methods.xClos
8b90: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 e method.** may
8ba0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 be invoked even
8bb0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f if the [sqlite3_
8bc0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 vfs.xOpen] repor
8bd0: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c ted that it fail
8be0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 ed. The.** only
8bf0: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 way to prevent
8c00: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 a call to xClose
8c10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
8c20: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 led [sqlite3_vfs
8c30: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f .xOpen].** is fo
8c40: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 r the [sqlite3_v
8c50: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 fs.xOpen] to set
8c60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
8c70: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 e.pMethods eleme
8c80: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a nt.** to NULL..*
8c90: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
8ca0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 rgument to xSync
8cb0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b may be one of [
8cc0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
8cd0: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 AL] or.** [SQLIT
8ce0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 E_SYNC_FULL]. T
8cf0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 he first choice
8d00: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 is the normal fs
8d10: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ync()..** The se
8d20: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 cond choice is a
8d30: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
8d40: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b fullsync. The [
8d50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
8d60: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 ONLY].** flag ma
8d70: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 y be ORed in to
8d80: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e indicate that on
8d90: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 ly the data of t
8da0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e he file.** and n
8db0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 ot its inode nee
8dc0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e ds to be synced.
8dd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 .**.** The integ
8de0: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f er values to xLo
8df0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
8e00: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a () are one of.**
8e10: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
8e20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
8e30: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
8e40: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
8e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8e60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a LOCK_RESERVED],.
8e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8e80: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
8e90: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
8ea0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
8eb0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 ]..** </ul>.** x
8ec0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 Lock() increases
8ed0: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f the lock. xUnlo
8ee0: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 ck() decreases t
8ef0: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 he lock..** The
8f00: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
8f10: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 ck() method chec
8f20: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 ks whether any d
8f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
8f40: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e on,.** either in
8f50: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 this process or
8f60: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 in some other p
8f70: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 rocess, is holdi
8f80: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a ng a RESERVED,.*
8f90: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 * PENDING, or EX
8fa0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 CLUSIVE lock on
8fb0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 the file. It re
8fc0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 turns true.** if
8fd0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 such a lock exi
8fe0: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 sts and false ot
8ff0: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 herwise..**.** T
9000: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 he xFileControl(
9010: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 ) method is a ge
9020: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 neric interface
9030: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 that allows cust
9040: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d om.** VFS implem
9050: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 entations to dir
9060: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e ectly control an
9070: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 open file using
9080: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
9090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
90a0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 interface. The
90b0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 second "op" arg
90c0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 ument is an.** i
90d0: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 nteger opcode.
90e0: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
90f0: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 nt is a generic
9100: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 pointer intended
9110: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 to.** point to
9120: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 a structure that
9130: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 may contain arg
9140: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 uments or space
9150: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 in which to.** w
9160: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 rite return valu
9170: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 es. Potential u
9180: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e ses for xFileCon
9190: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a trol() might be.
91a0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 ** functions to
91b0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 enable blocking
91c0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f locks with timeo
91d0: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 uts, to change t
91e0: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 he.** locking st
91f0: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d rategy (for exam
9200: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 ple to use dot-f
9210: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 ile locks), to i
9220: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 nquire.** about
9230: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 the status of a
9240: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 lock, or to brea
9250: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 k stale locks.
9260: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f The SQLite.** co
9270: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 re reserves all
9280: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 opcodes less tha
9290: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 n 100 for its ow
92a0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c n use..** A [fil
92b0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
92c0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f s | list of opco
92d0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 des] less than 1
92e0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 00 is available.
92f0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
9300: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 that define a c
9310: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 ustom xFileContr
9320: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 ol method should
9330: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 use opcodes.**
9340: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 greater than 100
9350: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 to avoid confli
9360: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d cts. VFS implem
9370: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
9380: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
9390: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 TE_NOTFOUND] for
93a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 file control op
93b0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 codes that they
93c0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e do not.** recogn
93d0: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ize..**.** The x
93e0: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 SectorSize() met
93f0: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 hod returns the
9400: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 sector size of t
9410: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 he.** device tha
9420: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 t underlies the
9430: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f file. The secto
9440: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a r size is the.**
9450: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 minimum write t
9460: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f hat can be perfo
9470: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 rmed without dis
9480: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 turbing.** other
9490: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
94a0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 le. The xDevice
94b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 Characteristics(
94c0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
94d0: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 rns a bit vector
94e0: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 describing beha
94f0: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 viors of the.**
9500: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 underlying devic
9510: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
9520: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
9530: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c CAP_ATOMIC].** <
9540: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
9550: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 P_ATOMIC512].**
9560: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
9570: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 AP_ATOMIC1K].**
9580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
9590: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 AP_ATOMIC2K].**
95a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
95b0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 AP_ATOMIC4K].**
95c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
95d0: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 AP_ATOMIC8K].**
95e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
95f0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a AP_ATOMIC16K].**
9600: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
9610: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a CAP_ATOMIC32K].*
9620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
9630: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a OCAP_ATOMIC64K].
9640: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9650: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
9660: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 D].** <li> [SQLI
9670: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
9680: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IAL].** </ul>.**
9690: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
96a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
96b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
96c0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
96d0: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
96e0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
96f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
9700: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
9710: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
9720: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
9730: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
9740: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
9750: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
9760: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
9770: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
9780: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
9790: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
97a0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
97b0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
97c0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
97d0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
97e0: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
97f0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
9800: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
9810: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
9820: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
9830: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
9840: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
9850: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
9860: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
9870: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
9880: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
9890: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
98a0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
98b0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
98c0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a xWrite()..**.**
98d0: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 If xRead() retu
98e0: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 rns SQLITE_IOERR
98f0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d _SHORT_READ it m
9900: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a ust also fill.**
9910: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 in the unread p
9920: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ortions of the b
9930: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 uffer with zeros
9940: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a . A VFS that.**
9950: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 fails to zero-f
9960: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
9970: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f might seem to wo
9980: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a rk. However,.**
9990: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f failure to zero
99a0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
99b0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
99c0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 y lead to.** dat
99d0: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e abase corruption
99e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
99f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
9a00: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 ethods sqlite3_i
9a10: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 o_methods;.struc
9a20: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
9a30: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 hods {. int iVe
9a40: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
9a50: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 Close)(sqlite3_f
9a60: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
9a70: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 Read)(sqlite3_fi
9a80: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 le*, void*, int
9a90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
9aa0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
9ab0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
9ac0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
9ad0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
9ae0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
9af0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
9b00: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
9b10: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
9b20: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 3_int64 size);.
9b30: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
9b40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
9b50: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 flags);. int (
9b60: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 *xFileSize)(sqli
9b70: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
9b80: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 e3_int64 *pSize)
9b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 ;. int (*xLock)
9ba0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
9bb0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 int);. int (*xU
9bc0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 nlock)(sqlite3_f
9bd0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
9be0: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 t (*xCheckReserv
9bf0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f edLock)(sqlite3_
9c00: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 file*, int *pRes
9c10: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
9c20: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 ileControl)(sqli
9c30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f te3_file*, int o
9c40: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a p, void *pArg);.
9c50: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 int (*xSectorS
9c60: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
9c70: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 e*);. int (*xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
9c90: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ics)(sqlite3_fil
9ca0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 e*);. /* Method
9cb0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
9cc0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 d for version 1
9cd0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d */. int (*xShmM
9ce0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
9cf0: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 *, int iPg, int
9d00: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 pgsz, int, void
9d10: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 volatile**);. i
9d20: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 nt (*xShmLock)(s
9d30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
9d40: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c t offset, int n,
9d50: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 int flags);. v
9d60: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 oid (*xShmBarrie
9d70: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a r)(sqlite3_file*
9d80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 );. int (*xShmU
9d90: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 nmap)(sqlite3_fi
9da0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 le*, int deleteF
9db0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f lag);. /* Metho
9dc0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
9dd0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 id for version 2
9de0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 */. int (*xFet
9df0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
9e00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
9e10: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 iOfst, int iAmt
9e20: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 , void **pp);.
9e30: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 int (*xUnfetch)(
9e40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
9e50: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
9e60: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 st, void *p);.
9e70: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
9e80: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
9e90: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a ersion 3 */. /*
9ea0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 Additional meth
9eb0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ods may be added
9ec0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
9ed0: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ses */.};../*.**
9ee0: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 CAPI3REF: Stand
9ef0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c ard File Control
9f00: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 Opcodes.** KEYW
9f10: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 ORDS: {file cont
9f20: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 rol opcodes} {fi
9f30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 le control opcod
9f40: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 e}.**.** These i
9f50: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
9f60: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 are opcodes for
9f70: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
9f80: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 l method.** of t
9f90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
9fa0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
9fb0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 nd for the [sqli
9fc0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9fd0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
9fe0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
9ff0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
a000: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
a010: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
a020: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
a030: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
a040: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
a050: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
a060: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
a070: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
a080: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
a090: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
a0a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
a0b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
a0c0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
a0d0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
a0e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
a0f0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
a100: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
a110: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
a120: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
a130: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
a140: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
a150: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f ng testing and o
a160: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
a170: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
a180: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 QLITE_TEST.** is
a190: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c defined..** <ul
a1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 >.** <li>[[SQLIT
a1b0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
a1c0: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 T]].** The [SQLI
a1d0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
a1e0: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 NT] opcode is us
a1f0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 ed by SQLite to
a200: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 give the VFS.**
a210: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 layer a hint of
a220: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 how large the da
a230: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
a240: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 grow to be duri
a250: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e ng the.** curren
a260: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 t transaction.
a270: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 This hint is not
a280: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
a290: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 e accurate but i
a2a0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c t.** is often cl
a2b0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c ose. The underl
a2c0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 ying VFS might c
a2d0: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f hoose to preallo
a2e0: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a cate database.**
a2f0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 file space base
a300: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 d on this hint i
a310: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 n order to help
a320: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 writes to the da
a330: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 tabase.** file r
a340: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a un faster..**.**
a350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a360: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d NTL_CHUNK_SIZE]]
a370: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
a380: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
a390: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
a3a0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 to request that
a3b0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 the VFS.** exte
a3c0: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 nds and truncate
a3d0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
a3e0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 ile in chunks of
a3f0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 a size specifie
a400: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 d.** by the user
a410: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 . The fourth arg
a420: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
a430: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
a440: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 ] should .** poi
a450: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 nt to an integer
a460: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 (type int) cont
a470: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 aining the new c
a480: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 hunk-size to use
a490: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 .** for the nomi
a4a0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 nated database.
a4b0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 Allocating datab
a4c0: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 ase file space i
a4d0: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b n large.** chunk
a4e0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 s (say 1MB at a
a4f0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 time), may reduc
a500: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 e file-system fr
a510: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a agmentation and.
a520: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f ** improve perfo
a530: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 rmance on some s
a540: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ystems..**.** <l
a550: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a560: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a _FILE_POINTER]].
a570: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
a580: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
a590: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 R] opcode is use
a5a0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f d to obtain a po
a5b0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
a5c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
a5d0: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
a5e0: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
a5f0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ar database.** c
a600: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 onnection. See
a610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
a620: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 e_control()] doc
a630: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a umentation for.*
a640: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * additional inf
a650: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
a660: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
a670: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d TL_SYNC_OMITTED]
a680: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 ].** No longer i
a690: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 n use..**.** <li
a6a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a6b0: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SYNC]].** The [S
a6c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
a6d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 ] opcode is gene
a6e0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 rated internally
a6f0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a by SQLite and.*
a700: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 * sent to the VF
a710: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 S immediately be
a720: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d fore the xSync m
a730: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
a740: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 on a.** databas
a750: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f e file descripto
a760: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 r. Or, if the xS
a770: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f ync method is no
a780: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 t invoked .** be
a790: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 cause the user h
a7a0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 as configured SQ
a7b0: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 Lite with .** [P
a7c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
a7d0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 s | PRAGMA synch
a7e0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 ronous=OFF] it i
a7f0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 s invoked in pla
a800: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 ce .** of the xS
a810: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d ync method. In m
a820: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 ost cases, the p
a830: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 ointer argument
a840: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 passed with.** t
a850: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a860: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 is NULL. Howeve
a870: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 r, if the databa
a880: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 se file is being
a890: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 synced.** as pa
a8a0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 rt of a multi-da
a8b0: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 tabase commit, t
a8c0: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e he argument poin
a8d0: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d ts to a nul-term
a8e0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
a8f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
a900: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 transactions mas
a910: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 ter-journal file
a920: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 name. VFSes tha
a930: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 t .** do not nee
a940: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 d this signal sh
a950: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
a960: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
a970: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a . Applications .
a980: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 ** should not ca
a990: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ll [sqlite3_file
a9a0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
a9b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
a9c0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a doing so may .**
a9d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 disrupt the ope
a9e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
a9f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
aa00: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
aa10: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
aa20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
aa30: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d OMMIT_PHASETWO]]
aa40: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
aa50: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
aa60: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 SETWO] opcode is
aa70: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
aa80: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a nally by SQLite.
aa90: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 ** and sent to t
aaa0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 he VFS after a t
aab0: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 ransaction has b
aac0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d een committed im
aad0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 mediately.** but
aae0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 before the data
aaf0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 base is unlocked
ab00: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 . VFSes that do
ab10: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
ab20: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 gnal.** should s
ab30: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 ilently ignore t
ab40: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c his opcode. Appl
ab50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
ab60: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c not call.** [sql
ab70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
ab80: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
ab90: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
aba0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 o may disrupt th
abb0: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 e .** operation
abc0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
abd0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
abe0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
abf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ac00: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
ac10: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 _RETRY]].** ^The
ac20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
ac30: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f IN32_AV_RETRY] o
ac40: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
ac50: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d configure autom
ac60: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f atic.** retry co
ac70: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 unts and interva
ac80: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 ls for certain d
ac90: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f isk I/O operatio
aca0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 ns for the.** wi
acb0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f ndows [VFS] in o
acc0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
acd0: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 robustness in th
ace0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a e presence of.**
acf0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 anti-virus prog
ad00: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c rams. By defaul
ad10: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 t, the windows V
ad20: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 FS will retry fi
ad30: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 le read,.** file
ad40: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 write, and file
ad50: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f delete operatio
ad60: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 ns up to 10 time
ad70: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a s, with a delay.
ad80: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 ** of 25 millise
ad90: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 conds before the
ada0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 first retry and
adb0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 with the delay
adc0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 increasing.** by
add0: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 an additional 2
ade0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 5 milliseconds w
adf0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 ith each subsequ
ae00: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 ent retry. This
ae10: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 .** opcode allow
ae20: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 s these two valu
ae30: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 es (10 retries a
ae40: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e nd 25 millisecon
ae50: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 ds of delay).**
ae60: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 to be adjusted.
ae70: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 The values are
ae80: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 changed for all
ae90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
aea0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 ions.** within t
aeb0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e he same process.
aec0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 The argument i
aed0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
aee0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a n array of two.*
aef0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 * integers where
af00: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 the first integ
af10: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 er i the new ret
af20: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 ry count and the
af30: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 second.** integ
af40: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e er is the delay.
af50: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 If either inte
af60: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c ger is negative,
af70: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e then the settin
af80: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e g.** is not chan
af90: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 ged but instead
afa0: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
afb0: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 of that setting
afc0: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e is written.** in
afd0: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 to the array ent
afe0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 ry, allowing the
aff0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 current retry s
b000: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a ettings to be.**
b010: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
b020: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 The zDbName para
b030: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 meter is ignored
b040: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b050: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 LITE_FCNTL_PERSI
b060: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 ST_WAL]].** ^The
b070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
b080: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f ERSIST_WAL] opco
b090: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
b0a0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
b0b0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 * persistent [WA
b0c0: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 L | Write Ahead
b0d0: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 Log] setting. B
b0e0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 y default, the a
b0f0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 uxiliary.** writ
b100: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 e ahead log and
b110: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
b120: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 les used for tra
b130: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
b140: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 .** are automati
b150: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 cally deleted wh
b160: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f en the latest co
b170: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 nnection to the
b180: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 database.** clos
b190: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 es. Setting per
b1a0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
b1b0: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 causes those fi
b1c0: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 les to persist a
b1d0: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 fter.** close.
b1e0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 Persisting the f
b1f0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 iles is useful w
b200: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 hen other proces
b210: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a ses that do not.
b220: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 ** have write pe
b230: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 rmission on the
b240: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 directory contai
b250: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
b260: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 e file want.** t
b270: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 o read the datab
b280: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 ase file, as the
b290: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 WAL and shared
b2a0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 memory files mus
b2b0: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 t exist.** in or
b2c0: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 der for the data
b2d0: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 base to be reada
b2e0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 ble. The fourth
b2f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
b300: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
b310: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 ontrol()] for th
b320: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 is opcode should
b330: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
b340: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 an integer..**
b350: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 That integer is
b360: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 0 to disable per
b370: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
b380: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
b390: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 persistent.** WA
b3a0: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 L mode. If the
b3b0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
b3c0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
b3d0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
b3e0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 urrent.** WAL pe
b3f0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e rsistence settin
b400: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
b410: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
b420: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
b430: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
b440: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 E_FCNTL_POWERSAF
b450: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 E_OVERWRITE] opc
b460: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
b470: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
b480: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 ** persistent "p
b490: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 owersafe-overwri
b4a0: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 te" or "PSOW" se
b4b0: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 tting. The PSOW
b4c0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 setting.** dete
b4d0: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 rmines the [SQLI
b4e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
b4f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 FE_OVERWRITE] bi
b500: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 t of the.** xDev
b510: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
b520: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 cs methods. The
b530: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
b540: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
b550: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
b560: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
b570: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
b580: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
b590: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
b5a0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
b5b0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d le zero-damage m
b5c0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
b5d0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a le zero-damage.*
b5e0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 * mode. If the
b5f0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
b600: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
b610: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
b620: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 urrent.** zero-d
b630: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 amage mode setti
b640: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
b650: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
b660: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
b670: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f [SQLITE_FCNTL_O
b680: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
b690: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 is invoked by S
b6a0: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e QLite after open
b6b0: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 ing.** a write t
b6c0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e ransaction to in
b6d0: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c dicate that, unl
b6e0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 ess it is rolled
b6f0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a back for some.*
b700: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e * reason, the en
b710: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 tire database fi
b720: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 le will be overw
b730: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 ritten by the cu
b740: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 rrent .** transa
b750: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 ction. This is u
b760: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 sed by VACUUM op
b770: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
b780: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b790: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 TL_VFSNAME]].**
b7a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
b7b0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f TL_VFSNAME] opco
b7c0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 de can be used t
b7d0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d o obtain the nam
b7e0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 es of.** all [VF
b7f0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 Ses] in the VFS
b800: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 stack. The name
b810: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 s are of all VFS
b820: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a shims and the.*
b830: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c * final bottom-l
b840: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 evel VFS are wri
b850: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
b860: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
b870: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
b880: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 oc()] and the re
b890: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 sult is stored i
b8a0: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 n the char* vari
b8b0: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 able.** that the
b8c0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
b8d0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 r of [sqlite3_fi
b8e0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f le_control()] po
b8f0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 ints to..** The
b900: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e caller is respon
b910: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e sible for freein
b920: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 g the memory whe
b930: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 n done. As with
b940: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e .** all file-con
b950: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 trol actions, th
b960: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e ere is no guaran
b970: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 tee that this wi
b980: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 ll actually.** d
b990: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c o anything. Cal
b9a0: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 lers should init
b9b0: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a ialize the char*
b9c0: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e variable to a N
b9d0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ULL.** pointer i
b9e0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 n case this file
b9f0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 -control is not
ba00: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 implemented. Th
ba10: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a is file-control.
ba20: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 ** is intended f
ba30: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 or diagnostic us
ba40: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c e only..**.** <l
ba50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
ba60: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 _PRAGMA]].** ^Wh
ba70: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 enever a [PRAGMA
ba80: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 ] statement is p
ba90: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 arsed, an [SQLIT
baa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
bab0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
bac0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 is sent to the
bad0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 open [sqlite3_fi
bae0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 le] object corre
baf0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 sponding.** to t
bb00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
bb10: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 to which the pr
bb20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 agma statement r
bb30: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 efers. ^The argu
bb40: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
bb50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
bb60: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
bb70: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 l is an array of
bb80: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
bb90: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 strings (char**)
bba0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 in which the se
bbb0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 cond element of
bbc0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 the array.** is
bbd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
bbe0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 pragma and the t
bbf0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 hird element is
bc00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 the argument to
bc10: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 the.** pragma or
bc20: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 NULL if the pra
bc30: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d gma has no argum
bc40: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ent. ^The handl
bc50: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 er for an.** [SQ
bc60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
bc70: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
bc80: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d can optionally m
bc90: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c ake the first el
bca0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 ement.** of the
bcb0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 char** argument
bcc0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
bcd0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
bce0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
bcf0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 ()].** or the eq
bd00: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 uivalent and tha
bd10: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 t string will be
bd20: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 come the result
bd30: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 of the pragma or
bd40: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 .** the error me
bd50: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 ssage if the pra
bd60: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 gma fails. ^If t
bd70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
bd80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
bd90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
bda0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
bdb0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 D], then normal
bdc0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f .** [PRAGMA] pro
bdd0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 cessing continue
bde0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c s. ^If the [SQL
bdf0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
be00: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
be10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
be20: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 E_OK], then the
be30: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 parser assumes t
be40: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 hat the.** VFS h
be50: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 as handled the P
be60: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 RAGMA itself and
be70: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 the parser gene
be80: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a rates a no-op.**
be90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
bea0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 ent. ^If the [S
beb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
bec0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
bed0: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
bee0: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 result code othe
bef0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
bf00: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f K] or [SQLITE_NO
bf10: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 TFOUND], that me
bf20: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ans.** that the
bf30: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 VFS encountered
bf40: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 an error while h
bf50: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 andling the [PRA
bf60: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 GMA] and the.**
bf70: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 compilation of t
bf80: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 he PRAGMA fails
bf90: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
bfa0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
bfb0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 TL_PRAGMA].** fi
bfc0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 le control occur
bfd0: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 s at the beginni
bfe0: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 ng of pragma sta
bff0: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 tement analysis
c000: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 and so.** it is
c010: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 able to override
c020: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d built-in [PRAGM
c030: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a A] statements..*
c040: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c050: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
c060: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 LER]].** ^The [S
c070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 QLITE_FCNTL_BUSY
c080: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 HANDLER].** file
c090: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 -control may be
c0a0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 invoked by SQLit
c0b0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 e on the databas
c0c0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a e file handle.**
c0d0: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 shortly after i
c0e0: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f t is opened in o
c0f0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
c100: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 a custom VFS wit
c110: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 h access.** to t
c120: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 he connections b
c130: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy-handler call
c140: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 back. The argume
c150: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 nt is of type (v
c160: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 oid **).** - an
c170: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f array of two (vo
c180: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 id *) values. Th
c190: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 e first (void *)
c1a0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 actually points
c1b0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f .** to a functio
c1c0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 n of type (int (
c1d0: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 *)(void *)). In
c1e0: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 order to invoke
c1f0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a the connections.
c200: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c ** busy-handler,
c210: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 this function s
c220: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 hould be invoked
c230: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 with the second
c240: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 (void *) in.**
c250: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 the array as the
c260: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 only argument.
c270: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f If it returns no
c280: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 n-zero, then the
c290: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 operation.** sh
c2a0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e ould be retried.
c2b0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a If it returns z
c2c0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 ero, the custom
c2d0: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 VFS should aband
c2e0: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e on the.** curren
c2f0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a t operation..**.
c300: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
c310: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
c320: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 ME]].** ^Applica
c330: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 tion can invoke
c340: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
c350: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 L_TEMPFILENAME]
c360: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
c370: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 to have SQLite g
c380: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d enerate a.** tem
c390: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 porary filename
c3a0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 using the same a
c3b0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 lgorithm that is
c3c0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e followed to gen
c3d0: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 erate.** tempora
c3e0: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 ry filenames for
c3f0: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 TEMP tables and
c400: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 other internal
c410: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 uses. The.** ar
c420: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
c430: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 a char** which
c440: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 will be filled w
c450: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ith the filename
c460: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f .** written into
c470: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
c480: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
c490: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 alloc()]. The c
c4a0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 aller should.**
c4b0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
c4c0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 free()] on the r
c4d0: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 esult to avoid a
c4e0: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a memory leak..**
c4f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c500: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
c510: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
c520: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
c530: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 E] file control
c540: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 is used to query
c550: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d or set the.** m
c560: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
c570: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c bytes that will
c580: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d be used for mem
c590: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a ory-mapped I/O..
c5a0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
c5b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
c5c0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 a value of type
c5d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 sqlite3_int64 th
c5e0: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 at.** is an advi
c5f0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d sory maximum num
c600: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
c610: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f the file to memo
c620: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 ry map. The.**
c630: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 pointer is overw
c640: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
c650: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 old value. The
c660: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 limit is not cha
c670: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 nged if.** the v
c680: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 alue originally
c690: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 pointed to is ne
c6a0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 gative, and so t
c6b0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 he current limit
c6c0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 .** can be quer
c6d0: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 ied by passing i
c6e0: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 n a pointer to a
c6f0: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
c700: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d . This.** file-
c710: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
c720: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d internally to im
c730: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 plement [PRAGMA
c740: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a mmap_size]..**.*
c750: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
c760: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 CNTL_TRACE]].**
c770: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c780: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f L_TRACE] file co
c790: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 ntrol provides a
c7a0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 dvisory informat
c7b0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 ion.** to the VF
c7c0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 S about what the
c7d0: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f higher layers o
c7e0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 f the SQLite sta
c7f0: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a ck are doing..**
c800: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 This file contr
c810: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f ol is used by so
c820: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 me VFS activity
c830: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e tracing [shims].
c840: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
c850: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 is a zero-termi
c860: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 nated string. H
c870: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 igher layers in
c880: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 the.** SQLite st
c890: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 ack may generate
c8a0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 instances of th
c8b0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
c8c0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 if.** the [SQLIT
c8d0: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 E_USE_FCNTL_TRAC
c8e0: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 E] compile-time
c8f0: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 option is enable
c900: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
c910: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
c920: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b MOVED]].** The [
c930: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
c940: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e _MOVED] file con
c950: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 trol interprets
c960: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 its argument as
c970: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
c980: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 an integer and i
c990: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 t writes a boole
c9a0: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 an into that int
c9b0: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a eger depending.*
c9c0: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 * on whether or
c9d0: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 not the file has
c9e0: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d been renamed, m
c9f0: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 oved, or deleted
ca00: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 since it.** was
ca10: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a first opened..*
ca20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ca30: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 E_FCNTL_WIN32_SE
ca40: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 T_HANDLE]].** Th
ca50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
ca60: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
ca70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
ca80: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
ca90: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
caa0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
cab0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
cac0: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 o swap the file
cad0: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 handle with the
cae0: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 one.** pointed t
caf0: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 o by the pArg ar
cb00: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 gument. This ca
cb10: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 pability is used
cb20: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a during testing.
cb30: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 ** and only need
cb40: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 s to be supporte
cb50: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 d when SQLITE_TE
cb60: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a ST is defined..*
cb70: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 *.** </ul>.*/.#d
cb80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
cb90: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 TL_LOCKSTATE
cba0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
cbb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f fine SQLITE_GET_
cbc0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
cbd0: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
cbe0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
cbf0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
cc00: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
cc10: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
cc20: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
cc30: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
cc40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
cc50: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 IZE_HINT
cc60: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
cc70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 SQLITE_FCNTL_CH
cc80: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 UNK_SIZE
cc90: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
cca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
ccb0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 E_POINTER
ccc0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
ccd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
cce0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 _OMITTED
ccf0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
cd00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
cd10: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 _AV_RETRY
cd20: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 9.#define SQL
cd30: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
cd40: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 T_WAL
cd50: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
cd60: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 TE_FCNTL_OVERWRI
cd70: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
cd80: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 11.#define SQLIT
cd90: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 E_FCNTL_VFSNAME
cda0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
cdb0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
cdc0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
cdd0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 _OVERWRITE 13
cde0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
cdf0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 FCNTL_PRAGMA
ce00: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 14.
ce10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
ce20: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
ce30: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 15.#
ce40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
ce50: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 NTL_TEMPFILENAME
ce60: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 16.#d
ce70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ce80: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 TL_MMAP_SIZE
ce90: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 18.#de
cea0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ceb0: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 L_TRACE
cec0: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 19.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
cee0: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 _HAS_MOVED
cef0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 20.#defi
cf00: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
cf10: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 SYNC
cf20: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 21.#defin
cf30: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 e SQLITE_FCNTL_C
cf40: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 OMMIT_PHASETWO
cf50: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 22.#define
cf60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
cf70: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 N32_SET_HANDLE
cf80: 20 20 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 23../*.** C
cf90: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
cfa0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
cfb0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
cfc0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
cfd0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
cfe0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
cff0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
d000: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
d010: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
d020: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
d030: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
d040: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
d050: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
d060: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
d070: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
d080: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
d090: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
d0a0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
d0b0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
d0c0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
d0d0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
d0e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
d0f0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
d100: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
d110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
d120: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
d130: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
d140: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
d150: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
d160: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
d170: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
d180: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
d190: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
d1a0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
d1b0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
d1c0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
d1d0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
d1e0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
d1f0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 file system".
d200: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 See.** the [VFS
d210: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 | VFS documentat
d220: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 ion] for further
d230: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
d240: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
d250: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
d260: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
d270: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
d280: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
d290: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
d2a0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
d2b0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
d2c0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
d2d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
d2e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
d2f0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
d300: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
d310: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
d320: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
d330: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
d340: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
d350: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
d360: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
d370: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
d380: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
d390: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
d3a0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
d3b0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
d3c0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
d3d0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
d3e0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
d3f0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
d400: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
d410: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
d420: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
d430: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
d440: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
d450: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
d460: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
d470: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
d480: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
d490: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
d4a0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
d4b0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
d4c0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
d4d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
d4e0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
d4f0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
d500: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
d510: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
d520: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
d530: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
d540: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
d550: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
d560: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
d570: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
d580: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
d590: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
d5a0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
d5b0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
d5c0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
d5d0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
d5e0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
d5f0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
d600: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
d610: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
d620: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
d630: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
d640: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
d650: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
d660: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
d670: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
d680: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
d690: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
d6a0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
d6b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
d6c0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
d6d0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
d6e0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
d6f0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
d700: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
d710: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
d720: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
d730: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
d740: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
d750: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
d760: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
d770: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 Open]].** ^SQLit
d780: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
d790: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 t the zFilename
d7a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
d7b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 en.** is either
d7c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
d7d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 r string obtaine
d7e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 d.** from xFullP
d7f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 athname() with a
d800: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 n optional suffi
d810: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 x added..** ^If
d820: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 a suffix is adde
d830: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 d to the zFilena
d840: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 me parameter, it
d850: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 will.** consist
d860: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 of a single "-"
d870: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f character follo
d880: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 wed by no more t
d890: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e han.** 11 alphan
d8a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d umeric and/or "-
d8b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a " characters..**
d8c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 ^SQLite further
d8d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
d8e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
d8f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
d900: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
d910: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
d920: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
d930: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
d940: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
d950: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
d960: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
d970: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
d980: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
d990: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
d9a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
d9b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
d9c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
d9d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
d9e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 r to xOpen is a
d9f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
da00: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
da10: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
da20: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
da30: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 r the file. ^Wh
da40: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 enever the .** x
da50: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
da60: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 er is NULL it wi
da70: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 ll also be the c
da80: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ase that the.**
da90: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
daa0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 will include [SQ
dab0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
dac0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 ONCLOSE]..**.**
dad0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
dae0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e nt to xOpen() in
daf0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 cludes all bits
db00: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c set in.** the fl
db10: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
db20: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
db30: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c ()]. Or if [sql
db40: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
db50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
db60: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 16()] is used, t
db70: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 hen flags includ
db80: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b es at least.** [
db90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
dba0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
dbb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a _OPEN_CREATE]. .
dbc0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 ** If xOpen() op
dbd0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d ens a file read-
dbe0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 only then it set
dbf0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a s *pOutFlags to.
dc00: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ** include [SQLI
dc10: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
dc20: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 ]. Other bits i
dc30: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
dc40: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e be set..**.** ^
dc50: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 (SQLite will als
dc60: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
dc70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
dc80: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
dc90: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
dca0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
dcb0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
dcc0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
dcd0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
dce0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
dcf0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
dd00: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
dd10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
dd20: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
dd30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
dd40: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
dd50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
dd60: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
dd70: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
dd80: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
dd90: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
dda0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
ddb0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
ddc0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
ddd0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 N_WAL].** </ul>)
dde0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 ^.**.** The file
ddf0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
de00: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
de10: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
de20: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
de30: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
de40: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
de50: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
de60: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
de70: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
de80: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
de90: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
dea0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
deb0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
dec0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
ded0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
dee0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
def0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
df00: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
df10: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
df20: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
df30: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
df40: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
df50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
df60: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
df70: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
df80: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
df90: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
dfa0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
dfb0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
dfc0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
dfd0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
dfe0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
dff0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
e000: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
e010: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
e020: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
e030: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
e040: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
e050: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
e060: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
e070: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
e080: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
e090: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
e0a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
e0b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
e0c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
e0d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
e0e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
e0f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 is closed. ^Th
e100: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
e110: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
e120: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 will be set for
e130: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 TEMP databases
e140: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 and their journa
e150: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a ls, transient.**
e160: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
e170: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
e180: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
e190: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
e1a0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
e1b0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
e1c0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
e1d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
e1e0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
e1f0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
e200: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
e210: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
e220: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
e230: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
e240: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
e250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
e260: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
e270: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
e280: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
e290: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
e2a0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
e2b0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
e2c0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
e2d0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
e2e0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
e2f0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
e300: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
e310: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
e320: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
e330: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
e340: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
e350: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
e360: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 ^At least szOsF
e370: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
e380: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
e390: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
e3a0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
e3b0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
e3c0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
e3d0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
e3e0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
e3f0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
e400: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
e410: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
e420: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
e430: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
e440: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
e450: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
e460: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
e470: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
e480: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
e490: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
e4a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
e4b0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
e4c0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
e4d0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
e4e0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
e4f0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
e500: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
e510: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
e520: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
e530: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
e540: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
e550: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
e560: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
e570: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
e580: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
e590: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
e5a0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 .xAccess]].** ^T
e5b0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
e5c0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
e5d0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
e5e0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
e5f0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
e600: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
e610: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
e620: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
e630: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
e640: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
e650: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
e660: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
e670: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
e680: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
e690: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
e6a0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
e6b0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
e6c0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
e6d0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 **.** ^SQLite wi
e6e0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
e6f0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
e700: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
e710: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
e720: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
e730: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
e740: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
e750: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
e760: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
e770: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
e780: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
e790: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
e7a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
e7b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
e7c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
e7d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
e7e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
e7f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
e800: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
e810: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
e820: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
e830: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
e840: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
e850: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
e860: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
e870: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
e880: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
e890: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
e8a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 ep(), xCurrentTi
e8b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 me(), and xCurre
e8c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a ntTimeInt64().**
e8d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
e8e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
e8f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
e900: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
e910: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
e920: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
e930: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
e940: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
e950: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
e960: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
e970: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
e980: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
e990: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
e9a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
e9b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
e9c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
e9d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
e9e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
e9f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
ea00: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
ea10: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
ea20: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
ea30: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
ea40: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
ea50: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
ea60: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 ven. ^The xCurr
ea70: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
ea80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
ea90: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
eaa0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
eab0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 date and time as
eac0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 .** a floating p
ead0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e oint value..** ^
eae0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
eaf0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 Int64() method r
eb00: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e eturns, as an in
eb10: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 teger, the Julia
eb20: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 n.** Day Number
eb30: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 multiplied by 86
eb40: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 400000 (the numb
eb50: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
eb60: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 ds in .** a 24-h
eb70: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e our day). .** ^
eb80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
eb90: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 the xCurrentTime
eba0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 Int64() method t
ebb0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e o get the curren
ebc0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 t.** date and ti
ebd0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f me if that metho
ebe0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 d is available (
ebf0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 if iVersion is 2
ec00: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 or .** greater
ec10: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e and the function
ec20: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
ec30: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 NULL) and will f
ec40: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 all back.** to x
ec50: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 CurrentTime() if
ec60: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
ec70: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 64() is unavaila
ec80: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ble..**.** ^The
ec90: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xSetSystemCall()
eca0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c , xGetSystemCall
ecb0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 (), and xNestSys
ecc0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 temCall() interf
ecd0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
ece0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 used by the SQLi
ecf0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 te core. These
ed00: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 optional interfa
ed10: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
ed20: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 .** by some VFSe
ed30: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 s to facilitate
ed40: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 testing of the V
ed50: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 FS code. By over
ed60: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 riding .** syste
ed70: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e m calls with fun
ed80: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 ctions under its
ed90: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 control, a test
eda0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 program can.**
edb0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 simulate faults
edc0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 and error condit
edd0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 ions that would
ede0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 otherwise be dif
edf0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 ficult.** or imp
ee00: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 ossible to induc
ee10: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 e. The set of s
ee20: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 ystem calls that
ee30: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
ee40: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f en.** varies fro
ee50: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f m one VFS to ano
ee60: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f ther, and from o
ee70: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ne version of th
ee80: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 e same VFS to th
ee90: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
eea0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
eeb0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 e these interfac
eec0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 es must be prepa
eed0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f red for any.** o
eee0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 r all of these i
eef0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 nterfaces to be
ef00: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 NULL or for thei
ef10: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 r behavior to ch
ef20: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 ange.** from one
ef30: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
ef40: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
ef50: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 ons must not att
ef60: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a empt to access.*
ef70: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d * any of these m
ef80: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 ethods if the iV
ef90: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 ersion of the VF
efa0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 S is less than 3
efb0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
efc0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
efd0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 sqlite3_vfs;.typ
efe0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
eff0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
f000: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 (void);.struct s
f010: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
f020: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
f030: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
f040: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
f050: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 ber (currently 3
f060: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 ) */. int szOsF
f070: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
f080: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
f090: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
f0a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
f0b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
f0c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
f0d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
f0e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
f0f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
f100: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
f110: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
f120: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
f130: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
f140: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
f150: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
f160: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
f170: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
f180: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
f190: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
f1a0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
f1b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
f1c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
f1d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
f1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
f1f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
f200: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
f210: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
f220: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
f230: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
f240: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
f250: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
f260: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
f270: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
f280: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
f290: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
f2a0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
f2b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
f2c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
f2d0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
f2e0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
f2f0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
f300: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
f310: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
f320: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
f330: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
f340: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
f350: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
f360: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
f370: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
f380: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
f390: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
f3a0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
f3b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
f3c0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
f3d0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
f3e0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
f3f0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
f400: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
f410: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
f420: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
f430: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
f440: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
f450: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
f460: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
f470: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
f480: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
f490: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 *);. /*. ** T
f4a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
f4b0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 are in version
f4c0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 1 of the sqlite_
f4d0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 vfs object. **
f4e0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f definition. Tho
f4f0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 se that follow a
f500: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 re added in vers
f510: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 ion 2 or later.
f520: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 */. int (*xCur
f530: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 rentTimeInt64)(s
f540: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c qlite3_vfs*, sql
f550: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 ite3_int64*);.
f560: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
f570: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
f580: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 versions 1 and
f590: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 2 of the sqlite_
f5a0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
f5b0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 Those below are
f5c0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 for version 3 a
f5d0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f nd greater.. */
f5e0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 . int (*xSetSys
f5f0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
f600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
f610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
f620: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 3_syscall_ptr);.
f630: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c sqlite3_syscal
f640: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 l_ptr (*xGetSyst
f650: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
f660: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
f670: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 *zName);. cons
f680: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 t char *(*xNextS
f690: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
f6a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
f6b0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f har *zName);. /
f6c0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
f6d0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
f6e0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 versions 1 throu
f6f0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 gh 3 of the sqli
f700: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
f710: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d ** New fields m
f720: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
f730: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e n figure version
f740: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
f750: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
f760: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
f770: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
f780: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a . . */.};../*.*
f790: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
f7a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
f7b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a s VFS method.**.
f7c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
f7d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
f7e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
f7f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
f800: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
f810: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
f820: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
f830: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 t. They determi
f840: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 ne.** what kind
f850: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
f860: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
f870: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 d is looking for
f880: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
f890: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
f8a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
f8b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
f8c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
f8d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
f8e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
f8f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 SS_READWRITE, th
f900: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
f910: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
f920: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 er the named dir
f930: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 ectory is both r
f940: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
f950: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 able.** (in othe
f960: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 r words, if file
f970: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 s can be added,
f980: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e removed, and ren
f990: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 amed within.** t
f9a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a he directory)..*
f9b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 * The SQLITE_ACC
f9c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f ESS_READWRITE co
f9d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e nstant is curren
f9e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 tly used only by
f9f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 the.** [temp_st
fa00: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
fa10: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 agma], though th
fa20: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 is could change
fa30: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
fa40: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
fa50: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
fa60: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
fa70: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
fa80: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
fa90: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
faa0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 eadable. The SQ
fab0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
fac0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 constant is.**
fad0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 currently unused
fae0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 , though it migh
faf0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 t be used in a f
fb00: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
fb10: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 .** SQLite..*/.#
fb20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
fb30: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
fb40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
fb50: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
fb60: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 1 /* Used by
fb70: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 PRAGMA temp_stor
fb80: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 e_directory */.#
fb90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
fba0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
fbb0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a /* Unused */.
fbc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
fbd0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
fbe0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 ShmLock VFS meth
fbf0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
fc00: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
fc10: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 define the vari
fc20: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 ous locking oper
fc30: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 ations.** allowe
fc40: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 d by the xShmLoc
fc50: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c k method of [sql
fc60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
fc70: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 . The.** follow
fc80: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 ing are the only
fc90: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 legal combinati
fca0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 ons of flags to
fcb0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 the.** xShmLock
fcc0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
fcd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
fce0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
fcf0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
fd00: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
fd10: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
fd20: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
fd30: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
fd40: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
fd50: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
fd60: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
fd70: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
fd80: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
fd90: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
fda0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 When unlocking,
fdb0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 the same SHARED
fdc0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 or EXCLUSIVE fla
fdd0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 g must be suppli
fde0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 ed as.** was giv
fdf0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 en no the corres
fe00: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a ponding lock. .
fe10: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
fe20: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 ck method can tr
fe30: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
fe40: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 unlocked and SH
fe50: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 ARED or.** betwe
fe60: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
fe70: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 EXCLUSIVE. It c
fe80: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e annot transition
fe90: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a between SHARED.
fea0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ** and EXCLUSIVE
feb0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
fec0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 ITE_SHM_UNLOCK
fed0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
fee0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 QLITE_SHM_LOCK
fef0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
ff00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
ff10: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 ED 4.#defi
ff20: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 ne SQLITE_SHM_EX
ff30: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a CLUSIVE 8../*
ff40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
ff50: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 ximum xShmLock i
ff60: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ndex.**.** The x
ff70: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
ff80: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
ff90: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 thods] may use v
ffa0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
ffb0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 0 and this uppe
ffc0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 r bound as its "
ffd0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 offset" argument
ffe0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
fff0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 core will never
10000 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 attempt to acqui
10010 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a re or release a.
10020 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 ** lock outside
10030 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f of this range.*/
10040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
10050 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 SHM_NLOCK
10060 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8.../*.** CAPI3
10070 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
10080 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
10090 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
100b0 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
100c0 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
100d0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
100e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
100f0 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
10100 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
10110 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
10120 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
10130 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
10140 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
10150 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
10160 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
10170 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
10180 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
10190 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
101a0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
101b0 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
101c0 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
101d0 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
101e0 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
101f0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
10200 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
10210 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
10220 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
10230 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
10240 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
10250 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
10260 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
10270 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
10280 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
10290 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
102a0 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
102b0 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
102c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
102d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
102e0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
102f0 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
10300 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10310 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
10320 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
10330 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
10340 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
10350 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
10360 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
10370 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
10380 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
10390 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
103a0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
103b0 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
103c0 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
103d0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
103e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
103f0 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
10400 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
10410 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
10420 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
10430 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
10440 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
10450 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
10460 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
10470 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
10480 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
10490 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
104a0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
104b0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
104c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
104d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
104e0 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
104f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
10500 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
10510 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
10520 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
10530 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
10540 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
10550 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
10560 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
10570 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
10580 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
10590 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
105a0 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
105b0 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
105c0 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
105d0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
105e0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
105f0 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
10600 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
10610 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
10620 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
10630 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
10640 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
10650 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
10660 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
10670 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
10680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
10690 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
106a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
106b0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
106c0 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
106d0 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
106e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
106f0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
10700 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
10710 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
10720 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
10730 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
10740 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
10750 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
10760 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
10770 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
10780 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
10790 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
107a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
107b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
107c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
107d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
107e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
107f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
10800 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
10810 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
10820 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
10830 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10840 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
10850 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
10860 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
10870 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
10880 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
10890 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
108a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
108b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
108c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
108d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
108e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
108f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
10900 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
10910 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
10920 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10930 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
10940 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
10950 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
10960 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
10970 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
10980 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
10990 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
109a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
109b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
109c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
109d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
109e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
109f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
10a00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
10a10 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
10a20 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
10a30 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
10a40 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
10a50 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
10a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10a70 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
10a80 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
10a90 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
10aa0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
10ab0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
10ac0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
10ad0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
10ae0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
10af0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
10b00 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
10b10 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10b20 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
10b30 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
10b40 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
10b50 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
10b60 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
10b70 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
10b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
10b90 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
10ba0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
10bb0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
10bc0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
10bd0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
10be0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
10bf0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
10c00 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
10c10 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
10c20 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
10c30 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
10c40 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
10c50 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
10c60 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
10c70 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
10c80 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
10c90 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
10ca0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
10cb0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
10cc0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
10cd0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
10ce0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
10cf0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
10d00 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
10d10 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
10d20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
10d30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
10d40 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
10d50 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
10d60 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
10d70 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
10d80 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
10d90 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
10da0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
10db0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
10dc0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10dd0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
10de0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
10df0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
10e00 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
10e10 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
10e20 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
10e30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10e40 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
10e50 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
10e60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
10e70 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
10e80 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
10e90 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
10ea0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
10eb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
10ec0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
10ed0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
10ee0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
10ef0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
10f00 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
10f10 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
10f20 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
10f30 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
10f40 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
10f50 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
10f60 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
10f70 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
10f80 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10f90 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
10fa0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
10fb0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
10fc0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
10fd0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
10fe0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
10ff0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
11000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
11010 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
11020 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
11030 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
11040 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
11050 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
11060 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
11070 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
11080 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 ailure..*/.SQLIT
11090 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
110a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 3_initialize(voi
110b0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 d);.SQLITE_API i
110c0 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nt sqlite3_shutd
110d0 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 own(void);.SQLIT
110e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
110f0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 3_os_init(void);
11100 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
11110 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 sqlite3_os_end(v
11120 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
11130 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 I3REF: Configuri
11140 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 ng The SQLite Li
11150 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 brary.**.** The
11160 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
11170 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
11180 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 ed to make globa
11190 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a l configuration.
111a0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 ** changes to SQ
111b0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f Lite in order to
111c0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 tune SQLite to
111d0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 the specific nee
111e0 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 ds of.** the app
111f0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 lication. The d
11200 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
11210 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e tion is recommen
11220 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 ded for most.**
11230 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 applications and
11240 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 so this routine
11250 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 is usually not
11260 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 necessary. It i
11270 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f s.** provided to
11280 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 support rare ap
11290 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 plications with
112a0 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a unusual needs..*
112b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
112c0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
112d0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 ace is not threa
112e0 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c dsafe. The appl
112f0 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 ication.** must
11300 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f insure that no o
11310 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
11320 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b rfaces are invok
11330 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 ed by other.** t
11340 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c hreads while sql
11350 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
11360 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 running. Furth
11370 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f ermore, sqlite3_
11380 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 config().** may
11390 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 only be invoked
113a0 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 prior to library
113b0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
113c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
113d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
113e0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 or after shutdow
113f0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 n by [sqlite3_sh
11400 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 utdown()]..** ^I
11410 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 f sqlite3_config
11420 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 () is called aft
11430 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 er [sqlite3_init
11440 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 ialize()] and be
11450 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 fore.** [sqlite3
11460 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 _shutdown()] the
11470 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e n it will return
11480 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a SQLITE_MISUSE..
11490 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
114a0 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f , that ^sqlite3_
114b0 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 config() can be
114c0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f called as part o
114d0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 f the.** impleme
114e0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 ntation of an ap
114f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
11500 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e d [sqlite3_os_in
11510 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 it()]..**.** The
11520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
11530 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
11540 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 g() is an intege
11550 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 r.** [configurat
11560 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 ion option] that
11570 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 determines.** w
11580 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 hat property of
11590 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 SQLite is to be
115a0 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 configured. Sub
115b0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
115c0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 s.** vary depend
115d0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 ing on the [conf
115e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
115f0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 ].** in the firs
11600 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
11610 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 * ^When a config
11620 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
11630 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 s set, sqlite3_c
11640 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 onfig() returns
11650 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 [SQLITE_OK]..**
11660 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 ^If the option i
11670 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c s unknown or SQL
11680 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
11690 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a set the option.
116a0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 ** then this rou
116b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e tine returns a n
116c0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
116d0 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ode]..*/.SQLITE_
116e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
116f0 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 config(int, ...)
11700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
11710 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 F: Configure dat
11720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11730 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 s.**.** The sqli
11740 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
11750 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
11760 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 d to make config
11770 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
11780 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 es to a [databas
11790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
117a0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 The interface is
117b0 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b similar to.** [
117c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
117d0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
117e0 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 e changes apply
117f0 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b to a single.** [
11800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11810 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 ion] (specified
11820 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
11830 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ument)..**.** Th
11840 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
11850 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f t to sqlite3_db_
11860 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 config(D,V,...)
11870 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 is the.** [SQLI
11880 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
11890 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 ASIDE | configur
118a0 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e ation verb] - an
118b0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a integer code .*
118c0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
118d0 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 what aspect of
118e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
118f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 nnection] is bei
11900 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a ng configured..*
11910 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 * Subsequent arg
11920 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 uments vary depe
11930 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e nding on the con
11940 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e figuration verb.
11950 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f .**.** ^Calls to
11960 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
11970 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 ig() return SQLI
11980 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c TE_OK if and onl
11990 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c y if.** the call
119a0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 is considered s
119b0 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 uccessful..*/.SQ
119c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
119d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 ite3_db_config(s
119e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c qlite3*, int op,
119f0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
11a00 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
11a10 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e llocation Routin
11a20 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 es.**.** An inst
11a30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
11a40 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
11a50 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
11a60 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
11a70 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
11a80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
11a90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
11aa0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
11ab0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
11ac0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
11ad0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
11ae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
11af0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
11b00 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
11b10 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
11b20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
11b30 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
11b40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
11b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
11b60 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
11b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
11b80 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
11b90 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
11ba0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
11bb0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
11bc0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
11bd0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
11be0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
11bf0 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
11c00 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
11c10 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
11c20 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
11c30 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
11c40 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
11c50 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
11c60 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
11c70 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
11c80 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
11c90 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
11ca0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
11cb0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
11cc0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
11cd0 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
11ce0 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
11cf0 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
11d00 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
11d10 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
11d20 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
11d30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
11d40 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
11d50 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
11d60 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
11d70 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
11d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11d90 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
11da0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
11db0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
11dc0 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
11dd0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
11de0 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
11df0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
11e00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
11e10 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
11e20 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
11e30 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
11e40 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
11e50 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
11e60 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
11e70 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
11e80 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
11e90 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 The xMalloc, xR
11ea0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 ealloc, and xFre
11eb0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
11ec0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
11ed0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f malloc(), reallo
11ee0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
11ef0 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
11f00 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
11f10 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 rary..** ^SQLite
11f20 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
11f30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
11f40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
11f50 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
11f60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
11f70 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
11f80 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a o xRoundup..**.*
11f90 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
11fa0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
11fb0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
11fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
11fd0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
11fe0 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
11ff0 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
12000 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
12010 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
12020 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
12030 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
12040 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
12050 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
12060 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
12070 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
12080 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
12090 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
120a0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
120b0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
120c0 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
120d0 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
120e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
120f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
12100 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12110 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
12120 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
12130 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
12140 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
12150 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
12160 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
12170 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 power of 2..** E
12180 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
12190 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 cation request c
121a0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 oming in through
121b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
121c0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
121d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 e3_realloc()] fi
121e0 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 rst calls xRound
121f0 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 up. If xRoundup
12200 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 returns 0, .**
12210 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 that causes the
12220 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 corresponding me
12230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12240 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 to fail..**.** T
12250 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
12260 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
12270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
12280 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a . For example,.
12290 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
122a0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
122b0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
122c0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
122d0 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
122e0 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
122f0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
12300 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
12310 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
12320 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
12330 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
12340 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
12350 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
12360 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
12370 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
12380 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
12390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
123a0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
123b0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 down..**.** SQLi
123c0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 te holds the [SQ
123d0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
123e0 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 C_MASTER] mutex
123f0 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
12400 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
12410 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
12420 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
12430 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
12440 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
12450 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
12460 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
12470 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12480 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
12490 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
124a0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
124b0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 r. For all othe
124c0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 r methods, SQLit
124d0 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b e.** holds the [
124e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
124f0 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 TIC_MEM] mutex a
12500 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a s long as the.**
12510 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12520 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 MEMSTATUS] confi
12530 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
12540 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 is turned on (wh
12550 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 ich.** it is by
12560 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 default) and so
12570 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 the methods are
12580 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 automatically se
12590 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 rialized..** How
125a0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 ever, if [SQLITE
125b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
125c0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 S] is disabled,
125d0 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a then the other.*
125e0 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 * methods must b
125f0 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 e threadsafe or
12600 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 else make their
12610 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 own arrangements
12620 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a for.** serializ
12630 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ation..**.** SQL
12640 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 ite will never i
12650 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f nvoke xInit() mo
12660 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 re than once wit
12670 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e hout an interven
12680 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 ing.** call to x
12690 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 Shutdown()..*/.t
126a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
126b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
126c0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
126d0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
126e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
126f0 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
12700 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
12710 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
12720 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
12730 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
12740 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
12750 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
12760 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
12770 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
12780 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
12790 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
127a0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
127b0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
127c0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
127d0 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
127e0 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
127f0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
12800 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
12810 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
12820 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
12830 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
12840 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
12850 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
12860 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
12870 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
12880 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
12890 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
128a0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
128b0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
128c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
128d0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
128e0 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
128f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
12900 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
12910 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
12920 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
12930 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
12940 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
12950 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 KEYWORDS: {conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12970 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
12980 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
12990 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
129a0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
129b0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
129c0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
129d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
129e0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
129f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
12a00 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
12a10 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
12a20 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
12a30 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
12a40 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
12a50 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
12a60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12a70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
12a80 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
12a90 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
12aa0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
12ab0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
12ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12ad0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
12ae0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
12af0 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
12b00 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12b10 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
12b20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
12b30 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
12b40 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
12b50 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
12b60 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
12b70 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
12b80 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
12b90 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f >.** [[SQLITE_CO
12ba0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
12bb0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
12bc0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
12bd0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
12be0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
12bf0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
12c00 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
12c10 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
12c20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
12c30 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 to Single-threa
12c40 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
12c50 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
12c60 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
12c70 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
12c80 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
12c90 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
12ca0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
12cb0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e ngle thread. ^
12cc0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12cd0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12ce0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12cf0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
12d00 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
12d10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
12d20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
12d30 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 t possible to ch
12d40 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 ange the [thread
12d50 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 ing mode] from i
12d60 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 ts default.** va
12d70 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 lue of Single-th
12d80 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c read and so [sql
12d90 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12da0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b ill return .** [
12db0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
12dc0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
12dd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
12de0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 INGLETHREAD.** c
12df0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12e00 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
12e10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12e20 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 MULTITHREAD]] <d
12e30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12e40 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
12e50 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
12e60 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
12e70 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
12e80 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
12e90 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
12ea0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c ing mode] to Mul
12eb0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f ti-thread. In o
12ec0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
12ed0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
12ee0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
12ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
12f00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
12f10 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
12f20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
12f30 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
12f40 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
12f50 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
12f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12f70 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
12f80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
12f90 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
12fa0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
12fb0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
12fc0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
12fd0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
12fe0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
12ff0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
13000 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
13010 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
13020 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
13030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
13040 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
13050 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 ime. ^If SQLite
13060 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
13070 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
13080 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
13090 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
130a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
130b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
130c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
130d0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c e to set the Mul
130e0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
130f0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
13100 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
13110 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
13120 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
13130 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
13140 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
13150 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
13160 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13170 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
13180 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13190 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 _SERIALIZED]] <d
131a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
131b0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
131c0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
131d0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
131e0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
131f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
13200 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
13210 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 ng mode] to Seri
13220 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 alized. In other
13230 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 words, this opt
13240 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
13250 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
13260 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
13270 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
13280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13290 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
132a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
132b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
132c0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
132d0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
132e0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
132f0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
13300 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
13310 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
13320 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
13330 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
13340 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
13350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13360 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
13370 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
13380 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
13390 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
133a0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
133b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
133c0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
133d0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
133e0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
133f0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
13400 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
13410 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 .** ^If SQLite i
13420 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
13430 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
13440 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
13450 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
13460 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
13470 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
13480 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
13490 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 to set the Seria
134a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
134b0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
134c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
134d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
134e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
134f0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
13500 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
13510 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 SERIALIZED confi
13520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
13530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
13550 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
13560 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
13570 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
13580 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
13590 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
135a0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
135b0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 ter to an.** ins
135c0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
135d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
135e0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
135f0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
13600 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
13610 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
13620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13630 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
13640 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 used in place of
13650 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
13660 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
13670 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 es built into SQ
13680 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 Lite.)^ ^SQLite
13690 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e makes.** its own
136a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
136b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
136d0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
136e0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 ure.** before th
136f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
13700 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e g()] call return
13710 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
13720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
13730 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 TMALLOC]] <dt>SQ
13740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
13750 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
13760 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
13770 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
13780 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
13790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
137a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
137b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
137c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
137d0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 ture. The [sqli
137e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
137f0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
13800 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
13810 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
13820 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
13830 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e tion routines.)^
13840 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
13850 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
13860 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
13870 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
13880 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
13890 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
138a0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
138b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
138c0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
138d0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
138e0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
138f0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 le. </dd>.**.**
13900 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13910 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e MEMSTATUS]] <dt>
13920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
13930 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
13940 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
13950 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
13960 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
13970 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
13980 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 as a .** boolea
13990 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
139a0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
139b0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d collection of m
139c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
139d0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e .** statistics.
139e0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 ^(When memory a
139f0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
13a00 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
13a10 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f d, the .** follo
13a20 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
13a30 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
13a40 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
13a50 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
13a60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
13a70 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
13a80 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
13a90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
13aa0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
13ab0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
13ac0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
13ad0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
13ae0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c tus()].** </ul
13af0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
13b00 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
13b10 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
13b20 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
13b30 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
13b40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
13b50 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
13b60 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
13b70 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
13b80 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
13b90 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
13ba0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
13bb0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
13bc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13bd0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 _SCRATCH]] <dt>S
13be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
13bf0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATCH</dt>.** <dd
13c00 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 > ^This option s
13c10 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 pecifies a stati
13c20 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 c memory buffer
13c30 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
13c40 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 use for.** scrat
13c50 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 ch memory. Ther
13c60 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
13c70 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 ments: A pointe
13c80 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
13c90 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
13ca0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
13cb0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f the scratch allo
13cc0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a cations will be.
13cd0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 ** drawn, the si
13ce0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 ze of each scrat
13cf0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 ch allocation (s
13d00 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d z),.** and the m
13d10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
13d20 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
13d30 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 ions (N). The s
13d40 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 z.** argument mu
13d50 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 st be a multiple
13d60 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 of 16..** The f
13d70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
13d80 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 st be a pointer
13d90 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 to an 8-byte ali
13da0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f gned buffer.** o
13db0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
13dc0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
13dd0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
13de0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
13df0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 n two scratch bu
13e00 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 ffers per thread
13e10 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c . So.** N shoul
13e20 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 d be set to twic
13e30 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d e the expected m
13e40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
13e50 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 threads..** ^SQ
13e60 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
13e70 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 require a scratc
13e80 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 h buffer that is
13e90 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 more than 6.**
13ea0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 times the databa
13eb0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 se page size. ^I
13ec0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e f SQLite needs n
13ed0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a eeds additional.
13ee0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
13ef0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 y beyond what is
13f00 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
13f10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
13f20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a option, then .**
13f30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13f40 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 ()] will be used
13f50 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d to obtain the m
13f60 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 emory needed.</d
13f70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
13f80 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
13f90 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f HE]] <dt>SQLITE_
13fa0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
13fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
13fc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
13fd0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
13fe0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
13ff0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
14000 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 for.** the datab
14010 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
14020 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
14030 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
14040 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 mentation. .**
14050 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 This configurati
14060 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 on should not be
14070 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c used if an appl
14080 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 ication-define p
14090 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 age.** cache imp
140a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c lementation is l
140b0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 oaded using the
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
140d0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a ACHE2 option..**
140e0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 There are three
140f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
14100 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 is option: A poi
14110 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 nter to 8-byte a
14120 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 ligned.** memory
14130 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
14140 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 ch page buffer (
14150 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d sz), and the num
14160 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 ber of pages (N)
14170 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 ..** The sz argu
14180 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 ment should be t
14190 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c he size of the l
141a0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 argest database
141b0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 page.** (a power
141c0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 of two between
141d0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 512 and 32768) p
141e0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 lus a little ext
141f0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 ra for each.** p
14200 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
14210 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 e page header si
14220 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 ze is 20 to 40 b
14230 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f ytes depending o
14240 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 n.** the host ar
14250 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 chitecture. ^It
14260 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 is harmless, ap
14270 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 art from the was
14280 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 ted memory,.** t
14290 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 o make sz a litt
142a0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 le too large. T
142b0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 he first.** argu
142c0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e ment should poin
142d0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 t to an allocati
142e0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 on of at least s
142f0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
14300 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ory..** ^SQLite
14310 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d will use the mem
14320 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 ory provided by
14330 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
14340 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 nt to satisfy it
14350 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 s.** memory need
14360 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 s for the first
14370 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 N pages that it
14380 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 adds to cache.
14390 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ^If additional.*
143a0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d * page cache mem
143b0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 ory is needed be
143c0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
143d0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 vided by this op
143e0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 tion, then.** SQ
143f0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 Lite goes to [sq
14400 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
14410 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e for the addition
14420 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 al storage space
14430 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 ..** The pointer
14440 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
14450 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 gument must.** b
14460 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
14470 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 8-byte boundary
14480 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 or subsequent be
14490 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 havior of SQLite
144a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 .** will be unde
144b0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a fined.</dd>.**.*
144c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
144d0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c G_HEAP]] <dt>SQL
144e0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c ITE_CONFIG_HEAP<
144f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
14500 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
14510 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
14520 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
14530 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
14540 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ** for all of it
14550 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
14560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
14570 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 s beyond those p
14580 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 rovided.** for b
14590 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
145a0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 _SCRATCH] and [S
145b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
145c0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 ECACHE]..** Ther
145d0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
145e0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 ments: An 8-byte
145f0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
14600 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
14610 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
14620 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
14630 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
14640 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
14650 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
14660 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^If the first p
14670 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
14680 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
14690 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
146a0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
146b0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
146c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
146d0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
146e0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
146f0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
14700 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
14710 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
14720 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
14730 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d ]. ^If the.** m
14740 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 emory pointer is
14750 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 not NULL and ei
14760 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ther [SQLITE_ENA
14770 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a BLE_MEMSYS3] or.
14780 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
14790 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 E_MEMSYS5] are d
147a0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 efined, then the
147b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d alternative mem
147c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
147d0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 is engaged to h
147e0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c andle all of SQL
147f0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ites memory allo
14800 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a cation needs..**
14810 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 The first point
14820 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
14830 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 ointer) must be
14840 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
14850 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 byte.** boundary
14860 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 or subsequent b
14870 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 ehavior of SQLit
14880 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 e will be undefi
14890 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 ned..** The mini
148a0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
148b0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 ize is capped at
148c0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 2**12. Reasonab
148d0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
148e0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
148f0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
14900 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2**5 through 2*
14910 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b *8.</dd>.**.** [
14920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
14930 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
14940 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f E_CONFIG_MUTEX</
14950 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14960 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
14970 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
14980 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
14990 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
149a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
149b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
149c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
149d0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
149e0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
149f0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
14a00 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 l mutex routines
14a10 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
14a20 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 lace.** the mute
14a30 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 x routines built
14a40 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
14a50 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
14a60 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
14a70 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
14a80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
14a90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
14aa0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c before the call
14ab0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
14ac0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e config()] return
14ad0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 s. ^If SQLite is
14ae0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
14af0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
14b00 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
14b10 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
14b20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
14b30 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
14b40 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
14b50 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
14b60 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
14b70 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
14b80 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
14b90 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
14ba0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
14bb0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 FIG_MUTEX config
14bc0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 uration option w
14bd0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 ill.** return [S
14be0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 QLITE_ERROR].</d
14bf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
14c10 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
14c20 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f ONFIG_GETMUTEX</
14c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
14c40 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
14c50 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
14c60 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
14c70 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
14c80 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
14c90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
14ca0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
14cb0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
14cc0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
14cd0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
14ce0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
14cf0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
14d00 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
14d10 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
14d20 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
14d30 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
14d40 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
14d50 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
14d60 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
14d70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
14d80 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
14d90 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
14da0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
14db0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
14dc0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 le. ^If SQLite
14dd0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
14de0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
14df0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
14e00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
14e10 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
14e20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
14e30 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
14e40 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
14e50 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
14e60 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
14e70 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
14e80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
14e90 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
14ea0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
14eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14ec0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
14ed0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
14ee0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
14ef0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
14f00 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 OOKASIDE]] <dt>S
14f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
14f20 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
14f30 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
14f40 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
14f50 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
14f60 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 mine the default
14f70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
14f80 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f ation for the lo
14f90 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
14fa0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 llocator on each
14fb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
14fc0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
14fd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
14fe0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
14ff0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
15000 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
15010 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 the second is th
15020 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
15030 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 lots allocated t
15040 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
15050 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e connection.)^ ^
15060 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 (This option set
15070 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 s the.** <i>defa
15080 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 ult</i> lookasid
15090 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c e size. The [SQL
150a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
150b0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 KASIDE].** verb
150c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
150d0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 onfig()] can be
150e0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
150f0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 he lookaside.**
15100 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e configuration on
15110 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e individual conn
15120 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e ections.)^ </dd>
15130 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15140 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d CONFIG_PCACHE2]]
15150 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15160 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a IG_PCACHE2</dt>.
15170 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
15180 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
15190 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
151a0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
151b0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 to.** an [sqlit
151c0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
151d0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 s2] object. Thi
151e0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 s object specifi
151f0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
15200 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 .** to a custom
15210 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
15220 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 mentation.)^ ^S
15230 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
15240 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a py of the.** obj
15250 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 ect and uses it
15260 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
15270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15280 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b s.</dd>.**.** [[
15290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
152a0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 TPCACHE2]] <dt>S
152b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
152c0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
152d0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
152e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
152f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
15300 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
15310 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
15320 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
15330 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
15340 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 copies of the c
15350 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 urrent.** page c
15360 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
15370 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
15380 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ject.)^ </dd>.**
15390 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
153a0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 FIG_LOG]] <dt>SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c LITE_CONFIG_LOG<
153c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 /dt>.** <dd> The
153d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
153e0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 OG option is use
153f0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 d to configure t
15400 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f he SQLite.** glo
15410 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e bal [error log].
15420 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 .** (^The SQLITE
15430 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
15440 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
15450 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
15460 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
15470 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
15480 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
15490 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
154a0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
154b0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
154c0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
154d0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
154e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
154f0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
15500 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
15510 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
15520 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
15530 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
15540 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
15550 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
15560 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
15570 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
15580 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
15590 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
155a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
155b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
155c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
155d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
155e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
155f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
15600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
15610 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
15620 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
15630 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
15640 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
15650 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
15660 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
15670 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
15680 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
15690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
156a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
156b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
156c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
156d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
156e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
156f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
15700 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
15710 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
15720 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
15730 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
15740 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
15750 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
15760 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
15770 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
15780 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
15790 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
157a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
157b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
157c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
157d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
157e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
157f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
15800 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
15810 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
15820 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
15830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
15840 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
15850 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
15860 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
15870 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15880 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 URI]] <dt>SQLITE
15890 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c _CONFIG_URI.** <
158a0 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e dd>^(This option
158b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
158c0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
158d0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 int. If non-zer
158e0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 o, then.** URI h
158f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
15900 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 lly enabled. If
15910 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
15920 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 zero, then URI
15930 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 handling.** is g
15940 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
15950 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 .)^ ^If URI hand
15960 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
15970 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 enabled, all fi
15980 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 lenames.** passe
15990 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d to [sqlite3_op
159a0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
159b0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c open_v2()], [sql
159c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f ite3_open16()] o
159d0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 r.** specified a
159e0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 s part of [ATTAC
159f0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 H] commands are
15a00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
15a10 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a RIs, regardless.
15a20 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ** of whether or
15a30 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 not the [SQLITE
15a40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
15a50 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 is set when the
15a60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
15a70 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
15a80 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 . ^If it is glob
15a90 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 ally disabled, f
15aa0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 ilenames are.**
15ab0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 only interpreted
15ac0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 as URIs if the
15ad0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 SQLITE_OPEN_URI
15ae0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
15af0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
15b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
15b10 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 pened. ^(By defa
15b20 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e ult, URI handlin
15b30 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
15b40 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 disabled. The d
15b50 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 efault value may
15b60 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 be changed by c
15b70 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 ompiling with th
15b80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 e.** [SQLITE_USE
15b90 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 _URI] symbol def
15ba0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ined.)^.**.** [[
15bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
15bc0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
15bd0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
15be0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
15bf0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
15c00 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 >^This option ta
15c10 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
15c20 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 eger argument wh
15c30 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ich is interpret
15c40 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 ed as.** a boole
15c50 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
15c60 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
15c70 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
15c80 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
15c90 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 .** full table s
15ca0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
15cb0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 y optimizer. ^T
15cc0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
15cd0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
15ce0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
15cf0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
15d00 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
15d10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
15d20 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
15d30 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
15d40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
15d50 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
15d60 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
15d70 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
15d80 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
15d90 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
15da0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
15db0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
15dc0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
15dd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
15de0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
15df0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d * when the optim
15e00 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c ization is enabl
15e10 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 ed. Providing t
15e20 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a he ability to.**
15e30 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 disable the opt
15e40 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 imization allows
15e50 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 the older, bugg
15e60 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f y application co
15e70 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 de to work.** wi
15e80 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 thout change eve
15e90 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 n with newer ver
15ea0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
15eb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15ec0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 CONFIG_PCACHE]]
15ed0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15ee0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c GETPCACHE]].** <
15ef0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15f00 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 _PCACHE and SQLI
15f10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
15f20 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 CHE.** <dd> Thes
15f30 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 e options are ob
15f40 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c solete and shoul
15f50 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 d not be used by
15f60 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 new code..** Th
15f70 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 ey are retained
15f80 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
15f90 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 mpatibility but
15fa0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a are now no-ops..
15fb0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
15fc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15fd0 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 QLLOG]].** <dt>S
15fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
15ff0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 LOG.** <dd>This
16000 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
16010 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 vailable if sqli
16020 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
16030 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
16040 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 TE_ENABLE_SQLLOG
16050 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
16060 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 macro defined. T
16070 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
16080 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 t should.** be a
16090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 pointer to a fu
160a0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 nction of type v
160b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
160c0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 ite3*,const char
160d0 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 *, int)..** The
160e0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 second should be
160f0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 of type (void*)
16100 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 . The callback i
16110 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 s invoked by the
16120 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 library.** in t
16130 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 hree separate ci
16140 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 rcumstances, ide
16150 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 ntified by the v
16160 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
16170 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
16180 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 ameter. If the f
16190 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
161a0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 is 0, then the d
161b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
161c0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 on.** passed as
161d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
161e0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 ent has just bee
161f0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 n opened. The th
16200 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ird argument.**
16210 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 points to a buff
16220 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 er containing th
16230 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 e name of the ma
16240 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
16250 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 . If the.** four
16260 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
16270 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
16280 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 statement that t
16290 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
162a0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 er.** points to
162b0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 has just been ex
162c0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 ecuted. Or, if t
162d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
162e0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a ter is 2, then.*
162f0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e * the connection
16300 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 being passed as
16310 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
16320 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 meter is being c
16330 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 losed. The.** th
16340 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
16350 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 passed NULL In
16360 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 this case. An e
16370 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 xample of using
16380 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 this.** configur
16390 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e ation option can
163a0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 be seen in the
163b0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 "test_sqllog.c"
163c0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a source file in.*
163d0 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 * the canonical
163e0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 SQLite source tr
163f0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ee.</dd>.**.** [
16400 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
16410 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 MAP_SIZE]].** <d
16420 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16430 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 MMAP_SIZE.** <dd
16440 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f >^SQLITE_CONFIG_
16450 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 MMAP_SIZE takes
16460 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 two 64-bit integ
16470 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 er (sqlite3_int6
16480 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 4) values.** tha
16490 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c t are the defaul
164a0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 t mmap size limi
164b0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 t (the default s
164c0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 etting for.** [P
164d0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
164e0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 ) and the maximu
164f0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 m allowed mmap s
16500 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 ize limit..** ^T
16510 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
16520 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 ng can be overri
16530 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 dden by each dat
16540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
16550 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 using.** either
16560 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 the [PRAGMA mma
16570 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c p_size] command,
16580 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 or by using the
16590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
165a0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
165b0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 e control. ^(Th
165c0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
165d0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 d mmap size.** c
165e0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
165f0 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e at run-time. N
16600 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d or may the maxim
16610 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
16620 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 size.** exceed t
16630 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
16640 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a maximum mmap siz
16650 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 e set by the.**
16660 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 [SQLITE_MAX_MMAP
16670 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 _SIZE] compile-t
16680 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a ime option.)^.**
16690 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 ^If either argu
166a0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 ment to this opt
166b0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c ion is negative,
166c0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d then that argum
166d0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 ent is.** change
166e0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 d to its compile
166f0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a -time default..*
16700 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16710 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
16720 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
16730 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
16740 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 _HEAPSIZE.** <dd
16750 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 >^This option is
16760 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
16770 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
16780 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 piled for Window
16790 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 s.** with the [S
167a0 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c QLITE_WIN32_MALL
167b0 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f OC] pre-processo
167c0 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e r macro defined.
167d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
167e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
167f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 takes a 32-bit
16800 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
16810 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 value.** that s
16820 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 pecifies the max
16830 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 imum size of the
16840 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a created heap..*
16850 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
16860 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16870 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
16880 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
16890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
168a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
168b0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
168c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
168d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
168e0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
168f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16900 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
16910 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
16920 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
16930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16940 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
16950 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
16960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
16970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16980 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
16990 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
169a0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
169b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
169c0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
169d0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
169e0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
169f0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
16a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
16a10 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
16a20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
16a30 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
16a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16a50 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
16a60 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
16a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16a80 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
16a90 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
16aa0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
16ab0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
16ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
16ad0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
16ae0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
16af0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
16b00 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
16b10 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
16b20 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
16b30 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
16b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16b50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
16b60 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
16b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
16b90 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 14 /* no-o
16ba0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
16bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
16bc0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e ACHE 15 /* n
16bd0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 o-op */.#define
16be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
16bf0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f G 16 /
16c00 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a * xFunc, void* *
16c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16c20 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 _CONFIG_URI
16c30 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 17 /* int
16c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
16c60 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 18 /* sql
16c70 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
16c80 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 ods2* */.#define
16c90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
16ca0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 ETPCACHE2 19
16cb0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
16cc0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
16cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16ce0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
16cf0 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 DEX_SCAN 20 /*
16d00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
16d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
16d20 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a LOG 21 /*
16d30 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 xSqllog, void*
16d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16d50 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
16d60 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c ZE 22 /* sql
16d70 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 ite3_int64, sqli
16d80 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 te3_int64 */.#de
16d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16da0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
16db0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e E 23 /* in
16dc0 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a t nByte */../*.*
16dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
16de0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
16df0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
16e00 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
16e10 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
16e20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
16e30 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
16e40 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
16e50 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
16e60 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
16e70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
16e80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
16e90 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
16ea0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
16eb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
16ec0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
16ed0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
16ee0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
16ef0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
16f00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
16f10 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
16f20 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
16f30 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
16f40 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
16f50 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
16f60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f _db_config()] to
16f70 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
16f80 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
16f90 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 ed. ^The [sqlit
16fa0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
16fb0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
16fc0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
16fd0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
16fe0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
16ff0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
17000 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
17010 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
17020 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
17030 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
17040 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
17050 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
17060 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
17070 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e s three addition
17080 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 al arguments tha
17090 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
170a0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d .** [lookaside m
170b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
170c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
170d0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 or the [database
170e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
170f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
17100 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
17110 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
17120 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
17130 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
17140 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
17150 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
17160 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
17170 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 y..** ^The first
17180 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 argument after
17190 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
171a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 FIG_LOOKASIDE ve
171b0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rb.** may be NUL
171c0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
171d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
171e0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b cate the.** look
171f0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 aside buffer its
17200 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
17210 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 e3_malloc()]. ^T
17220 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
17230 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
17240 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
17250 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e ide buffer slot.
17260 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 ^The third arg
17270 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
17280 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
17290 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
172a0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
172b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
172c0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
172d0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
172e0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
172f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
17300 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
17310 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a . The buffer.**
17320 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
17330 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
17340 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 undary. ^If the
17350 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
17360 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 to.** SQLITE_DB
17370 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
17380 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 is not a multip
17390 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 le of 8, it is i
173a0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 nternally.** rou
173b0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 nded down to the
173c0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 next smaller mu
173d0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 ltiple of 8. ^(
173e0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 The lookaside me
173f0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 mory.** configur
17400 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 ation for a data
17410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
17420 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e can only be chan
17430 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a ged when that.**
17440 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e connection is n
17450 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 ot currently usi
17460 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
17470 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 ory, or in other
17480 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 words.** when t
17490 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 he "current valu
174a0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a e" returned by.*
174b0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
174c0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f atus](D,[SQLITE_
174d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
174e0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a ],...) is zero..
174f0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
17500 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
17510 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f kaside memory co
17520 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e nfiguration when
17530 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
17540 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c mory is in use l
17550 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 eaves the config
17560 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 uration unchange
17570 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a d and returns .*
17580 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
17590 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 )^</dd>.**.** <d
175a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
175b0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 G_ENABLE_FKEY</d
175c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
175d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
175e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
175f0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 able the enforce
17600 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 ment of.** [fore
17610 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 ign key constrai
17620 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f nts]. There sho
17630 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
17640 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
17650 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
17660 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
17670 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
17680 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e to disable FK en
17690 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f forcement,.** po
176a0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
176b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
176c0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
176d0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d eave FK enforcem
176e0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ent.** unchanged
176f0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17700 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
17710 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
17720 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
17730 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
17740 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
17750 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 hether FK enforc
17760 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 ement is off or
17770 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 on.** following
17780 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
17790 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
177a0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
177b0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
177c0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 ich case the FK
177d0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 enforcement sett
177e0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
177f0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
17800 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
17810 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
17820 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a _TRIGGER</dt>.**
17830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
17840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
17850 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
17860 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
17870 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 | triggers]..**
17880 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
17890 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
178a0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
178b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
178c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
178d0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
178e0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a ble triggers,.**
178f0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
17900 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 ble triggers or
17910 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
17920 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e e the setting un
17930 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 changed..** The
17940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17950 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17960 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
17970 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
17980 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
17990 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
179a0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 triggers are dis
179b0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
179c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
179d0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
179e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
179f0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
17a00 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
17a10 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 h case the trigg
17a20 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f er setting is no
17a30 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
17a40 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 </dd>.**.** </d
17a50 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
17a60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
17a70 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 OKASIDE 10
17a80 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 01 /* void* int
17a90 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
17aa0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
17ab0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 ENABLE_FKEY
17ac0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 1002 /* int int
17ad0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
17ae0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
17af0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 BLE_TRIGGER 100
17b00 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 3 /* int int* *
17b10 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 /.../*.** CAPI3R
17b20 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
17b30 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 sable Extended R
17b40 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a esult Codes.**.*
17b50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
17b60 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
17b70 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 odes() routine e
17b80 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
17b90 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e es the.** [exten
17ba0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
17bb0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c ] feature of SQL
17bc0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 ite. ^The extend
17bd0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 ed result.** cod
17be0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 es are disabled
17bf0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 by default for h
17c00 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
17c10 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 ibility..*/.SQLI
17c20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
17c30 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
17c40 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
17c50 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
17c60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17c70 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
17c80 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e d.**.** ^Each en
17c90 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 try in most SQLi
17ca0 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 te tables (excep
17cb0 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 t for [WITHOUT R
17cc0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a OWID] tables).**
17cd0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 has a unique 64
17ce0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 -bit signed.** i
17cf0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 nteger key calle
17d00 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 d the [ROWID | "
17d10 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f rowid"]. ^The ro
17d20 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 wid is always av
17d30 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e ailable.** as an
17d40 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 undeclared colu
17d50 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 mn named ROWID,
17d60 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 OID, or _ROWID_
17d70 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 as long as those
17d80 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f .** names are no
17d90 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 t also used by e
17da0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
17db0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a ed columns. ^If.
17dc0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 ** the table has
17dd0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 a column of typ
17de0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 e [INTEGER PRIMA
17df0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 RY KEY] then tha
17e00 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
17e10 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
17e20 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
17e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c * ^The sqlite3_l
17e40 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17e50 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (D) interface re
17e60 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
17e70 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 ] of the .** mos
17e80 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 t recent success
17e90 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
17ea0 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 o a rowid table
17eb0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c or [virtual tabl
17ec0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 e].** on databas
17ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a e connection D..
17ee0 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f ** ^Inserts into
17ef0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d [WITHOUT ROWID]
17f00 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 tables are not
17f10 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 recorded..** ^If
17f20 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b no successful [
17f30 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f INSERT]s into ro
17f40 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 wid tables.** ha
17f50 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
17f60 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
17f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a connection D, .
17f80 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
17f90 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
17fa0 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 d(D) returns zer
17fb0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e o..**.** ^(If an
17fc0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 [INSERT] occurs
17fd0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
17fe0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 r or within a [v
17ff0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
18000 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
18010 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
18020 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 return the [rowi
18030 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 d] of the insert
18040 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e ed.** row as lon
18050 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
18060 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c or virtual tabl
18070 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e e method is runn
18080 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 ing..** But once
18090 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 the trigger or
180a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 virtual table me
180b0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 thod ends, the v
180c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a alue returned .*
180d0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e * by this routin
180e0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 e reverts to wha
180f0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 t it was before
18100 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
18110 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 irtual.** table
18120 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a method began.)^.
18130 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 **.** ^An [INSER
18140 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 T] that fails du
18150 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
18160 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
18170 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
18180 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 ul [INSERT] and
18190 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
181a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
181b0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f ed by this.** ro
181c0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e utine. ^Thus IN
181d0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e SERT OR FAIL, IN
181e0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 SERT OR IGNORE,
181f0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 INSERT OR ROLLBA
18200 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 CK,.** and INSER
18210 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 T OR ABORT make
18220 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 no changes to th
18230 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
18240 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e f this.** routin
18250 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 e when their ins
18260 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e ertion fails. ^
18270 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 (When INSERT OR
18280 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
18290 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
182a0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
182b0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
182c0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
182d0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
182e0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
182f0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
18300 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
18310 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
18320 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
18330 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
18340 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
18350 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
18360 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 this interface.)
18370 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ^.**.** ^For the
18380 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
18390 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 s routine, an [I
183a0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 NSERT] is consid
183b0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 ered to.** be su
183c0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 ccessful even if
183d0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e it is subsequen
183e0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e tly rolled back.
183f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
18400 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 tion is accessib
18410 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d le to SQL statem
18420 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 ents via the.**
18430 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 [last_insert_row
18440 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f id() SQL functio
18450 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
18460 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 eparate thread p
18470 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 erforms a new [I
18480 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 NSERT] on the sa
18490 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 me.** database c
184a0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
184b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 the [sqlite3_las
184c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
184d0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 ].** function is
184e0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 running and thu
184f0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 s changes the la
18500 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
18510 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 ],.** then the v
18520 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
18530 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
18540 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 nsert_rowid()] i
18550 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 s.** unpredictab
18560 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 le and might not
18570 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 equal either th
18580 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 e old or the new
18590 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 .** last insert
185a0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 [rowid]..*/.SQLI
185b0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
185c0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
185d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
185e0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
185f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
18600 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
18610 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
18620 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
18630 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
18640 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
18650 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 rows that were
18660 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e changed.** or in
18670 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
18680 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
18690 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
186a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
186b0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * on the [databa
186c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
186d0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
186e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
186f0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 .** ^(Only chang
18700 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 es that are dire
18710 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 ctly specified b
18720 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 y the [INSERT],
18730 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 [UPDATE],.** or
18740 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
18750 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 nt are counted.
18760 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 Auxiliary chang
18770 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 es caused by.**
18780 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 triggers or [for
18790 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
187a0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
187b0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 d.)^ Use the.**
187c0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
187d0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
187e0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 on to find the t
187f0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
18800 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 hanges.** includ
18810 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
18820 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 ed by triggers a
18830 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 nd foreign key a
18840 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ctions..**.** ^C
18850 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
18860 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 that are simula
18870 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 ted by an [INSTE
18880 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a AD OF trigger].*
18890 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 * are not counte
188a0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 d. Only real ta
188b0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 ble changes are
188c0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e counted..**.** ^
188d0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 (A "row change"
188e0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
188f0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
18900 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
18910 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
18920 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
18930 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
18940 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
18950 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
18960 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
18970 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
18980 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c aint resolution,
18990 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 .** rollback, AB
189a0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
189b0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 [DROP TABLE], or
189c0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
189d0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
189e0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
189f0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 ct row changes.)
18a00 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ^.**.** A "trigg
18a10 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
18a20 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
18a30 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
18a40 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
18a50 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
18a60 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
18a70 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a | trigger]. .**
18a80 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
18a90 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
18aa0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
18ab0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
18ac0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
18ad0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
18ae0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
18af0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
18b00 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
18b10 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
18b20 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
18b30 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
18b40 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
18b50 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
18b60 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
18b70 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
18b80 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
18b90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 on..**.** ^Calli
18ba0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ng [sqlite3_exec
18bb0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
18bc0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
18bd0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ely does.** not
18be0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 create a new tri
18bf0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
18c00 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
18c10 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
18c20 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 umber of direct
18c30 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 row changes in t
18c40 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e he.** most recen
18c50 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
18c60 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 , or DELETE stat
18c70 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
18c80 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 same.** trigger
18c90 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
18ca0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c ^Thus, when call
18cb0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 ed from the top
18cc0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 level, this func
18cd0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
18ce0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 .** number of ch
18cf0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
18d00 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
18d10 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
18d20 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 TE.** that also
18d30 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 occurred at the
18d40 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 top level. ^(Wi
18d50 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
18d60 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
18d70 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
18d80 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
18d90 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
18da0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
18db0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
18dc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18dd0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
18de0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
18df0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
18e00 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
18e10 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
18e20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
18e30 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
18e40 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
18e50 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
18e60 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
18e70 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
18e80 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
18e90 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e r own context.)^
18ea0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
18eb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
18ec0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
18ed0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
18ee0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
18ef0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
18f00 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
18f10 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
18f20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
18f30 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
18f40 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
18f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18f60 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
18f70 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
18f80 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
18f90 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
18fa0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
18fb0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
18fc0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
18fd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
18fe0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
18ff0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
19000 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
19010 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
19020 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
19030 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
19040 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
19050 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 f row changes ca
19060 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d used by [INSERT]
19070 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 ,.** [UPDATE] or
19080 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
19090 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b ents since the [
190a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
190b0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e ion] was opened.
190c0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 .** ^(The count
190d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
190e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
190f0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c s() includes all
19100 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d changes.** from
19110 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 all [CREATE TRI
19120 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 GGER | trigger]
19130 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 contexts and cha
19140 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 nges made by.**
19150 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
19160 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a ions]. However,.
19170 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
19180 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
19190 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
191a0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 plement [REPLACE
191b0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a ] constraints,.*
191c0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f * do rollbacks o
191d0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 r ABORT processi
191e0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 ng, or [DROP TAB
191f0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 LE] processing.
19200 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f The.** count do
19210 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 es not include r
19220 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 ows of views tha
19230 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 t fire an [INSTE
19240 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a AD OF trigger],.
19250 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 ** though if the
19260 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
19270 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ger makes change
19280 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 s of its own, th
19290 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 ose changes .**
192a0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a are counted.)^.*
192b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
192c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 otal_changes() f
192d0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 unction counts t
192e0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f he changes as so
192f0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 on as.** the sta
19300 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
19310 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
19320 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
19330 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a atement handle.*
19340 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b * is passed to [
19350 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
19360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
19370 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alize()])..**.**
19380 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
19390 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
193a0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
193b0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
193c0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
193d0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 the [total_chang
193e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
193f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
19400 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
19410 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
19420 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
19430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
19440 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
19450 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
19460 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
19470 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
19480 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
19490 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
194a0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
194b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
194c0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
194d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
194e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
194f0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
19500 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a Running Query.**
19510 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
19520 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 on causes any pe
19530 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f nding database o
19540 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 peration to abor
19550 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 t and.** return
19560 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 at its earliest
19570 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 opportunity. Thi
19580 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 s routine is typ
19590 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 ically.** called
195a0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
195b0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 a user action su
195c0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 ch as pressing "
195d0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 Cancel".** or Ct
195e0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 rl-C where the u
195f0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 ser wants a long
19600 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e query operation
19610 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 to halt.** imme
19620 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e diately..**.** ^
19630 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
19640 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
19650 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
19660 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
19670 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
19680 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
19690 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
196a0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
196b0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
196c0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
196d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
196e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
196f0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
19700 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
19710 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
19720 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
19730 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
19740 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 ^If an SQL oper
19750 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
19760 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
19770 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
19780 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
19790 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
197a0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
197b0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
197c0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
197d0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
197e0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
197f0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
19800 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 .** ^An SQL oper
19810 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
19820 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
19830 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
19840 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 TERRUPT]..** ^If
19850 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
19860 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
19870 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
19880 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
19890 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
198a0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
198b0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
198c0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
198d0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
198e0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
198f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
19900 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
19910 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c nterrupt(D) call
19920 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e is in effect un
19930 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c til all currentl
19940 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c y running.** SQL
19950 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b statements on [
19960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
19970 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e ion] D complete.
19980 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 ^Any new SQL s
19990 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
199a0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
199b0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
199c0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
199d0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
199e0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 .** running stat
199f0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a ements reaches z
19a00 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 ero are interrup
19a10 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 ted as if they h
19a20 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 ad been.** runni
19a30 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ng prior to the
19a40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19a50 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 t() call. ^New
19a60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
19a70 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
19a80 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e ed after the run
19a90 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 ning statement c
19aa0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 ount reaches zer
19ab0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 o are.** not eff
19ac0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c ected by the sql
19ad0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
19ae0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 ..** ^A call to
19af0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
19b00 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 t(D) that occurs
19b10 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 when there are
19b20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 no running.** SQ
19b30 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 L statements is
19b40 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 a no-op and has
19b50 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c no effect on SQL
19b60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
19b70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
19b80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
19b90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
19ba0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ll returns..**.*
19bb0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
19bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
19bd0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
19be0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
19bf0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
19c00 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
19c10 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
19c20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
19c30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
19c40 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
19c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
19c60 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
19c70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
19c80 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
19c90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
19ca0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
19cb0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
19cc0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
19cd0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
19ce0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
19cf0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
19d00 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
19d10 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
19d20 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
19d30 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
19d40 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
19d50 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
19d60 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
19d70 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
19d80 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
19d90 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
19da0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
19db0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
19dc0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
19dd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
19de0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
19df0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
19e00 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
19e10 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
19e20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
19e30 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
19e40 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
19e50 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
19e60 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
19e70 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
19e80 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
19e90 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
19ea0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
19eb0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
19ec0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
19ed0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
19ee0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
19ef0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
19f00 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
19f10 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
19f20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
19f30 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
19f40 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
19f50 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
19f60 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
19f70 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
19f80 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
19f90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
19fa0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
19fb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
19fc0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
19fd0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
19fe0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
19ff0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
1a000 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
1a010 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
1a020 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
1a030 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
1a040 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
1a050 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
1a060 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
1a070 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
1a080 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
1a090 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
1a0a0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
1a0b0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1a0c0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
1a0d0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
1a0e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
1a0f0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
1a100 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
1a110 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
1a120 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
1a130 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
1a140 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
1a150 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
1a160 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
1a170 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
1a180 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
1a190 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
1a1a0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
1a1b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1a1c0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
1a1d0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
1a1e0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
1a1f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
1a200 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
1a210 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
1a220 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
1a230 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
1a240 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
1a250 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
1a260 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
1a270 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
1a280 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
1a290 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 yte order..*/.SQ
1a2a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1a2b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
1a2c0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
1a2d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1a2e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1a2f0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
1a300 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1a310 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
1a320 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
1a330 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
1a340 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rrors.**.** ^The
1a350 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1a360 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 ndler(D,X,P) rou
1a370 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c tine sets a call
1a380 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a back function X.
1a390 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 ** that might be
1a3a0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 invoked with ar
1a3b0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 gument P wheneve
1a3c0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
1a3d0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 is made to acces
1a3e0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 s a database tab
1a3f0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 le associated wi
1a400 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 th.** [database
1a410 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 connection] D wh
1a420 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 en another threa
1a430 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 d.** or process
1a440 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f has the table lo
1a450 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cked..** The sql
1a460 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1a470 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 r() interface is
1a480 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
1a490 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nt.** [sqlite3_b
1a4a0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 usy_timeout()] a
1a4b0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f nd [PRAGMA busy_
1a4c0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 timeout]..**.**
1a4d0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
1a4e0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 lback is NULL, t
1a4f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 hen [SQLITE_BUSY
1a500 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
1a510 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f immediately upo
1a520 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 n encountering t
1a530 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 he lock. ^If th
1a540 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a e busy callback.
1a550 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 ** is not NULL,
1a560 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 then the callbac
1a570 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b k might be invok
1a580 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 ed with two argu
1a590 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
1a5a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a5b0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e to the busy han
1a5c0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f dler is a copy o
1a5d0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e f the void* poin
1a5e0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
1a5f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
1a600 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 nt to sqlite3_bu
1a610 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e sy_handler(). ^
1a620 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
1a630 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 ent to.** the bu
1a640 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy handler callb
1a650 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
1a660 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
1a670 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a680 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
1a690 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d oked for the sam
1a6a0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e e locking event.
1a6b0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
1a6c0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
1a6d0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
1a6e0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
1a6f0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
1a700 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
1a710 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
1a720 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e _BUSY] is return
1a730 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 ed.** to the app
1a740 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 lication..** ^If
1a750 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1a760 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
1a770 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
1a780 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
1a790 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 to access the da
1a7a0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 tabase and the c
1a7b0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
1a7c0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
1a7d0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
1a7e0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
1a7f0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 antee that it wi
1a800 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
1a810 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
1a820 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 ock contention.
1a830 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 ^If SQLite deter
1a840 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
1a850 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 ing the busy.**
1a860 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 handler could re
1a870 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f sult in a deadlo
1a880 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 ck, it will go a
1a890 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 head and return
1a8a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
1a8b0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
1a8c0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ion instead of i
1a8d0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 nvoking the .**
1a8e0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1a8f0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
1a900 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
1a910 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1a920 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
1a930 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
1a940 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
1a950 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
1a960 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
1a970 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1a980 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
1a990 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
1a9a0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
1a9b0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
1a9c0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
1a9d0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
1a9e0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
1a9f0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1aa00 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
1aa10 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
1aa20 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
1aa30 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
1aa40 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
1aa50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
1aa60 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
1aa70 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
1aa80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
1aa90 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
1aaa0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
1aab0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
1aac0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
1aad0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
1aae0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
1aaf0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
1ab00 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
1ab10 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
1ab20 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
1ab30 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
1ab40 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
1ab50 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
1ab60 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
1ab70 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
1ab80 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
1ab90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 LL..**.** ^(Ther
1aba0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1abb0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1abc0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1abd0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1abe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1abf0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1ac00 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1ac10 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1ac20 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1ac30 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1ac40 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1ac50 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1ac60 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 ** or evaluating
1ac70 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1ac80 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 meout=N] will ch
1ac90 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 ange the.** busy
1aca0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 handler and thu
1acb0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 s clear any prev
1acc0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 iously set busy
1acd0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
1ace0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1acf0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
1ad00 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
1ad10 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
1ad20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1ad30 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1ad40 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
1ad50 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f er. In other wo
1ad60 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 rds,.** the busy
1ad70 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 handler is not
1ad80 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 reentrant. Any
1ad90 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
1ada0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
1adb0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
1adc0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
1add0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
1ade0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1adf0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
1ae00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ae10 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
1ae20 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1ae30 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ler..*/.SQLITE_A
1ae40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1ae50 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 usy_handler(sqli
1ae60 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 te3*, int(*)(voi
1ae70 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b d*,int), void*);
1ae80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ae90 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d : Set A Busy Tim
1aea0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 eout.**.** ^This
1aeb0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1aec0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1aed0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
1aee0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
1aef0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
1af00 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
1af10 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
1af20 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 is locked. ^Th
1af30 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c e handler.** wil
1af40 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
1af50 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 times until at
1af60 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1af70 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1af80 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 ing.** have accu
1af90 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 mulated. ^After
1afa0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1afb0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1afc0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 leeping,.** the
1afd0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
1afe0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 0 which causes [
1aff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1b000 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 to return.** [SQ
1b010 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a LITE_BUSY]..**.*
1b020 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
1b030 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
1b040 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
1b050 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
1b060 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
1b070 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
1b080 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
1b090 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1b0a0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1b0b0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
1b0c0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1b0d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
1b0e0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
1b0f0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
1b100 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
1b110 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
1b120 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1b130 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
1b140 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
1b150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
1b160 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
1b170 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
1b180 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 d.)^.**.** See a
1b190 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 lso: [PRAGMA bu
1b1a0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 sy_timeout].*/.S
1b1b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1b1c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1b1d0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
1b1e0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
1b1f0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
1b200 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
1b210 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
1b220 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1b230 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1b240 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1b250 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1b260 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1b270 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1b280 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1b290 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1b2a0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1b2b0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1b2c0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1b2d0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1b2e0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1b2f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1b300 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1b310 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1b320 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1b330 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1b340 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1b350 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1b360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1b370 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1b380 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1b390 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1b3a0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1b3b0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1b3c0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1b3d0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1b3e0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1b3f0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1b400 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1b410 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1b420 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1b430 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1b440 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1b450 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1b460 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1b470 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1b480 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1b490 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1b4a0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1b4b0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1b4c0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1b4d0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1b4e0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1b4f0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1b500 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1b510 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1b520 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1b530 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1b540 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1b550 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1b560 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1b570 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1b580 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1b590 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1b5a0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1b5b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1b5c0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1b5d0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1b5e0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1b5f0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1b600 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1b610 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1b620 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1b630 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1b640 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1b650 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1b660 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1b670 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1b680 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1b690 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1b6a0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1b6b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1b6c0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1b6d0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1b6e0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1b6f0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1b700 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1b710 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1b720 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1b730 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1b740 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1b750 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1b760 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1b770 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1b780 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1b790 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1b7a0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1b7b0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1b7c0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1b7d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1b7e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1b7f0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1b800 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1b810 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1b820 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1b830 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1b840 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1b850 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1b860 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1b870 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1b880 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1b890 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1b8a0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1b8b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1b8c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1b8d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1b8e0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1b8f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1b900 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1b910 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1b920 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1b930 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1b940 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1b950 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1b960 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1b970 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1b980 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1b990 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1b9a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b9b0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1b9c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1b9d0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1b9e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1b9f0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1ba00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1ba10 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1ba20 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1ba30 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1ba40 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1ba50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1ba60 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1ba70 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1ba80 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1ba90 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1baa0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1bab0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1bac0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1bad0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1bae0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1baf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1bb00 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1bb10 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1bb20 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1bb30 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1bb40 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1bb50 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1bb60 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1bb70 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1bb80 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1bb90 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1bba0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1bbb0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1bbc0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1bbd0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1bbe0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1bbf0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1bc00 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1bc10 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1bc20 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1bc30 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1bc40 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1bc50 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1bc60 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1bc70 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1bc80 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1bc90 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1bca0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1bcb0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1bcc0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1bcd0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1bce0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1bcf0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1bd00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1bd10 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1bd20 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1bd30 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1bd40 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1bd50 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1bd60 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1bd70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1bd80 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1bd90 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1bda0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1bdb0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1bdc0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1bdd0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1bde0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1bdf0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1be00 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1be10 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1be20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1be30 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1be40 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1be50 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f g()]..*/.SQLITE_
1be60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1be70 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c get_table(. sql
1be80 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1be90 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
1bea0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
1beb0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1bec0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
1bed0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 valuated */. ch
1bee0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c ar ***pazResult,
1bef0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f /* Results o
1bf00 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 f the query */.
1bf10 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 int *pnRow,
1bf20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1bf30 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 of result rows
1bf40 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1bf50 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c int *pnColumn,
1bf60 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1bf70 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 r of result colu
1bf80 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 mns written here
1bf90 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 */. char **pzE
1bfa0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 rrmsg /* E
1bfb0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
1bfc0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 here */.);.SQLI
1bfd0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
1bfe0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
1bff0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
1c000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c010 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
1c020 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
1c030 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1c040 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
1c050 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
1c060 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
1c070 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
1c080 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
1c090 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
1c0a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1c0b0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
1c0c0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1c0d0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
1c0e0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
1c0f0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
1c100 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
1c110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
1c120 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
1c130 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
1c140 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
1c150 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
1c160 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
1c170 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
1c180 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1c190 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
1c1a0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
1c1b0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
1c1c0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
1c1d0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
1c1e0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
1c1f0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
1c200 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
1c210 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
1c220 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
1c230 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
1c240 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
1c250 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
1c260 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
1c270 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
1c280 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
1c290 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1c2a0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
1c2b0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
1c2c0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
1c2d0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
1c2e0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
1c2f0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
1c300 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
1c310 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
1c320 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 printf().)^ Thi
1c330 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
1c340 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
1c350 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
1c360 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
1c370 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
1c380 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
1c390 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 ^(Note also th
1c3a0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 at sqlite3_snpri
1c3b0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 ntf().** returns
1c3c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
1c3d0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 s buffer instead
1c3e0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
1c3f0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 f.** characters
1c400 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e actually written
1c410 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 into the buffer
1c420 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 .)^ We admit th
1c430 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 at.** the number
1c440 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 of characters w
1c450 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 ritten would be
1c460 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 a more useful re
1c470 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 turn.** value bu
1c480 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e t we cannot chan
1c490 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ge the implement
1c4a0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
1c4b0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e _snprintf().** n
1c4c0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ow without break
1c4d0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ing compatibilit
1c4e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e y..**.** ^As lon
1c4f0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
1c500 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
1c510 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
1c520 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1c530 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
1c540 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
1c550 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
1c560 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 nated. ^The fir
1c570 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
1c580 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
1c590 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
1c5a0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
1c5b0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
1c5c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1c5d0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
1c5e0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
1c5f0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
1c600 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
1c610 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
1c620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1c630 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 ite3_vsnprintf()
1c640 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 routine is a va
1c650 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 rargs version of
1c660 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1c670 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 f()..**.** These
1c680 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
1c690 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
1c6a0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
1c6b0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
1c6c0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
1c6d0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
1c6e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
1c6f0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
1c700 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
1c710 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
1c720 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
1c730 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
1c740 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
1c750 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
1c760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 ..**.** ^(The %q
1c770 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1c780 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
1c790 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
1c7a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
1c7b0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
1c7c0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
1c7d0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
1c7e0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
1c7f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
1c800 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
1c810 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
1c820 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
1c830 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
1c840 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
1c850 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
1c860 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
1c870 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
1c880 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
1c890 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
1c8a0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1c8b0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
1c8c0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
1c8d0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
1c8e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1c8f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1c900 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1c910 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
1c920 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
1c930 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c940 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
1c950 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
1c960 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
1c970 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
1c980 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1c990 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1c9a0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
1c9b0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
1c9c0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
1c9d0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
1c9e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1c9f0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1ca00 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1ca10 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1ca20 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1ca30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
1ca40 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
1ca50 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
1ca60 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
1ca70 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
1ca80 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
1ca90 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
1caa0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
1cab0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1cac0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
1cad0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
1cae0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
1caf0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
1cb00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1cb10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
1cb20 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
1cb30 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
1cb40 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
1cb50 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
1cb60 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
1cb70 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
1cb80 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1cb90 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1cba0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1cbb0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
1cbc0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
1cbd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1cbe0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
1cbf0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
1cc00 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
1cc10 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
1cc20 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
1cc30 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
1cc40 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
1cc50 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
1cc60 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
1cc70 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
1cc80 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
1cc90 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
1cca0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
1ccb0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
1ccc0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
1ccd0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
1cce0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
1ccf0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
1cd00 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
1cd10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
1cd20 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
1cd30 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
1cd40 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
1cd50 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
1cd60 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
1cd70 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
1cd80 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
1cd90 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
1cda0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1cdb0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1cdc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1cdd0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1cde0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
1cdf0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
1ce00 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
1ce10 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
1ce20 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
1ce30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1ce40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1ce50 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
1ce60 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
1ce70 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
1ce80 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
1ce90 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
1cea0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
1ceb0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
1cec0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
1ced0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
1cee0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
1cef0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
1cf00 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
1cf10 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
1cf20 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
1cf30 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
1cf40 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
1cf50 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
1cf60 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
1cf70 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
1cf80 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 ring.)^.*/.SQLIT
1cf90 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
1cfa0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
1cfb0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 t char*,...);.SQ
1cfc0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
1cfd0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1cfe0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1cff0 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 list);.SQLITE_AP
1d000 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1d010 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1d020 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1d030 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
1d040 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
1d050 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1d060 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1d070 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1d080 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1d090 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1d0a0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1d0b0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1d0c0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1d0d0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1d0e0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1d0f0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1d100 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1d110 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1d120 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1d130 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1d140 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1d150 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1d160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1d170 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1d180 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1d190 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1d1a0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1d1b0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1d1c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1d1d0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1d1e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1d1f0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1d200 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1d210 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1d220 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1d230 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1d240 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1d250 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1d260 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1d270 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1d280 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1d290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1d2a0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1d2b0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1d2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1d2d0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1d2e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1d2f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1d300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1d310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1d320 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 te3_malloc64(N)
1d330 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 routine works ju
1d340 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 st like.** sqlit
1d350 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 e3_malloc(N) exc
1d360 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e ept that N is an
1d370 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 unsigned 64-bit
1d380 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 integer instead
1d390 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 .** of a signed
1d3a0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 32-bit integer..
1d3b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1d3c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1d3d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1d3e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1d3f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1d400 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1d410 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1d420 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1d430 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1d440 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1d450 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1d460 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1d470 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1d480 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1d490 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1d4a0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1d4b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1d4c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1d4d0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1d4e0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1d4f0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1d500 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1d510 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1d520 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1d530 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1d540 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1d550 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1d560 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1d570 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1d580 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1d590 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1d5a0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1d5b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1d5c0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1d5d0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1d5e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1d5f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1d600 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1d610 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1d620 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1d630 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1d640 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1d650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
1d660 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 lloc(X,N) interf
1d670 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
1d680 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
1d690 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
1d6a0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c ion X to be at l
1d6b0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a east N bytes..**
1d6c0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d ^If the X param
1d6d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1d6e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 realloc(X,N).**
1d6f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1d700 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
1d710 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
1d720 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
1d730 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1d740 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 ..** ^If the N p
1d750 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1d760 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d770 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
1d780 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
1d790 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
1d7a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
1d7b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1d7c0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 te3_free(X)..**
1d7d0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1d7e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 (X,N) returns a
1d7f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
1d800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
1d810 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
1d820 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
1d830 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 NULL if insuffi
1d840 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
1d850 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
1d860 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
1d870 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d880 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
1d890 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
1d8a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d8b0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
1d8c0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
1d8d0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
1d8e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1d8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d900 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f ,N) and the prio
1d910 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1d920 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
1d930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1d940 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 N) returns NULL
1d950 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 and N is positiv
1d960 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 e, then the.** p
1d970 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1d980 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
1d990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1d9a0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 _realloc64(X,N)
1d9b0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 interfaces works
1d9c0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
1d9d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d9e0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 X,N) except that
1d9f0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 N is a 64-bit u
1da00 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
1da10 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1da20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
1da30 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 teger..**.** ^If
1da40 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 X is a memory a
1da50 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f llocation previo
1da60 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
1da70 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1da80 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
1da90 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 malloc64(), sqli
1daa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f te3_realloc(), o
1dab0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1dac0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 c64(), then.** s
1dad0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1dae0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
1daf0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 of that memory
1db00 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 allocation in by
1db10 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c tes..** ^The val
1db20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1db30 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1db40 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
1db50 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a than the number.
1db60 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 ** of bytes requ
1db70 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 ested when X was
1db80 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 allocated. ^If
1db90 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 X is a NULL poi
1dba0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c nter then.** sql
1dbb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1dbc0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 turns zero. If
1dbd0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 X points to some
1dbe0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f thing that is no
1dbf0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 t.** the beginni
1dc00 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c ng of memory all
1dc10 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 ocation, or if i
1dc20 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f t points to a fo
1dc30 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 rmerly.** valid
1dc40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1dc50 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 n that has now b
1dc60 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 een freed, then
1dc70 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
1dc80 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 of sqlite3_msize
1dc90 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 (X) is undefined
1dca0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 and possibly ha
1dcb0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rmful..**.** ^Th
1dcc0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
1dcd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
1dce0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 loc(), sqlite3_r
1dcf0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c ealloc(),.** sql
1dd00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c ite3_malloc64(),
1dd10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
1dd20 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 lloc64().** is a
1dd30 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
1dd40 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
1dd50 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
1dd60 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
1dd70 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
1dd80 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
1dd90 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
1dda0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
1ddb0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
1ddc0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
1ddd0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
1dde0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
1ddf0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
1de00 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
1de10 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
1de20 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
1de30 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
1de40 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
1de50 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
1de60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
1de70 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
1de80 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
1de90 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
1dea0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
1deb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1dec0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
1ded0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
1dee0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1def0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
1df00 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
1df10 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
1df20 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
1df30 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1df40 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
1df50 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
1df60 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
1df70 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
1df80 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
1df90 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
1dfa0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
1dfb0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
1dfc0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
1dfd0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
1dfe0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
1dff0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
1e000 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
1e010 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
1e020 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
1e030 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
1e040 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
1e050 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
1e060 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
1e070 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
1e080 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
1e090 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1e0a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1e0b0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
1e0c0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
1e0d0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
1e0e0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
1e0f0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
1e100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
1e110 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
1e120 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1e130 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
1e140 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
1e150 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
1e160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
1e170 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
1e180 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
1e190 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
1e1a0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
1e1b0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
1e1c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1e1d0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
1e1e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1e1f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1e200 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d void *sqlite3_m
1e210 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 alloc(int);.SQLI
1e220 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
1e230 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
1e240 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 lite3_uint64);.S
1e250 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
1e260 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1e270 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c void*, int);.SQL
1e280 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
1e290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
1e2a0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
1e2b0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
1e2c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
1e2d0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c free(void*);.SQL
1e2e0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1e2f0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d uint64 sqlite3_m
1e300 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a size(void*);../*
1e310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1e320 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
1e330 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
1e340 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
1e350 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
1e360 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
1e370 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
1e380 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
1e390 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
1e3a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
1e3b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1e3c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
1e3d0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
1e3e0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
1e3f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1e400 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
1e410 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
1e420 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
1e430 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1e440 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
1e450 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
1e460 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
1e470 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
1e480 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
1e490 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1e4a0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1e4b0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
1e4c0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
1e4d0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
1e4e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1e4f0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
1e500 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
1e510 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
1e520 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
1e530 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1e540 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1e550 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1e560 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1e570 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
1e580 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
1e590 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
1e5a0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
1e5b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1e5c0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
1e5d0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
1e5e0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
1e5f0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
1e600 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
1e610 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
1e620 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
1e630 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
1e640 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
1e650 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
1e660 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
1e670 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
1e680 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1e690 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
1e6a0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
1e6b0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
1e6c0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1e6d0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
1e6e0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
1e6f0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
1e700 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1e710 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
1e720 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1e730 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
1e740 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f eset..*/.SQLITE_
1e750 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
1e760 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
1e770 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
1e780 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
1e790 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
1e7a0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
1e7b0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
1e7c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e7d0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
1e7e0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a mber Generator.*
1e7f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 *.** SQLite cont
1e800 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c ains a high-qual
1e810 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f ity pseudo-rando
1e820 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 m number generat
1e830 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 or (PRNG) used t
1e840 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 o.** select rand
1e850 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 om [ROWID | ROWI
1e860 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 Ds] when inserti
1e870 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 ng new records i
1e880 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 nto a table that
1e890 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 .** already uses
1e8a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 the largest pos
1e8b0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 sible [ROWID].
1e8c0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f The PRNG is also
1e8d0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 used for.** the
1e8e0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d build-in random
1e8f0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f () and randomblo
1e900 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e b() SQL function
1e910 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 s. This interfa
1e920 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 ce allows.** app
1e930 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 lications to acc
1e940 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e ess the same PRN
1e950 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 G for other purp
1e960 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 oses..**.** ^A c
1e970 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 all to this rout
1e980 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 ine stores N byt
1e990 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
1e9a0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a into buffer P..
1e9b0 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 ** ^If N is less
1e9c0 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 than one, then
1e9d0 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 P can be a NULL
1e9e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
1e9f0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
1ea00 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 has not been pre
1ea10 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f viously called o
1ea20 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 r if the previou
1ea30 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 s.** call had N
1ea40 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 less than one, t
1ea50 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20 hen the PRNG is
1ea60 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
1ea70 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 domness.** obtai
1ea80 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 ned from the xRa
1ea90 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
1eaa0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
1eab0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
1eac0 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ect..** ^If the
1ead0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
1eae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
1eaf0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d d an N of 1 or m
1eb00 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ore then.** the
1eb10 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 pseudo-randomnes
1eb20 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a s is generated.*
1eb30 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 * internally and
1eb40 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 without recours
1eb50 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 e to the [sqlite
1eb60 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 3_vfs] xRandomne
1eb70 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f ss.** method..*/
1eb80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1eb90 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
1eba0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
1ebb0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
1ebc0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
1ebd0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
1ebe0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
1ebf0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
1ec00 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 egisters an auth
1ec10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1ec20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
1ec30 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1ec40 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
1ec50 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
1ec60 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e t argument..** ^
1ec70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
1ec80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1ec90 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
1eca0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
1ecb0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
1ecc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1ecd0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
1ece0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
1ecf0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
1ed00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1ed10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1ed20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
1ed30 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a ^At various.**
1ed40 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 points during t
1ed50 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 he compilation p
1ed60 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 rocess, as logic
1ed70 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 is being create
1ed80 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 d.** to perform
1ed90 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c various actions,
1eda0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1edb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
1edc0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 ked to.** see if
1edd0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 those actions a
1ede0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 re allowed. ^Th
1edf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1ee00 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
1ee10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
1ee20 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 K] to allow the
1ee30 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f action, [SQLITE_
1ee40 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c IGNORE] to disal
1ee50 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 low the.** speci
1ee60 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 fic action but a
1ee70 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 llow the SQL sta
1ee80 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e tement to contin
1ee90 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ue to be.** comp
1eea0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 iled, or [SQLITE
1eeb0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 _DENY] to cause
1eec0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 the entire SQL s
1eed0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a tatement to be.*
1eee0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 * rejected with
1eef0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 an error. ^If t
1ef00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1ef10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
1ef20 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
1ef30 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
1ef40 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
1ef50 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
1ef60 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
1ef70 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
1ef80 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
1ef90 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
1efa0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
1efb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
1efc0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
1efd0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
1efe0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
1eff0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
1f000 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
1f010 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
1f020 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
1f030 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 is ok. ^When t
1f040 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1f050 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
1f060 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
1f070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f080 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
1f090 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
1f0a0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
1f0b0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
1f0c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
1f0d0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
1f0e0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
1f0f0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a s denied. .**.**
1f100 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
1f110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
1f120 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1f130 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
1f140 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
1f150 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
1f160 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1f170 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 er() interface.
1f180 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
1f190 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
1f1a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
1f1b0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 nteger [SQLITE_C
1f1c0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
1f1d0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
1f1e0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 s.** the particu
1f1f0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 lar action to be
1f200 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 authorized. ^Th
1f210 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
1f220 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
1f230 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
1f240 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 ack are zero-ter
1f250 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1f260 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
1f270 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
1f280 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
1f290 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1f2a0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ized..**.** ^If
1f2b0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
1f2c0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
1f2d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
1f2e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1f2f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
1f300 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
1f310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 ed statement] st
1f320 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 atement is const
1f330 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 ructed to substi
1f340 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 tute.** a NULL v
1f350 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
1f360 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
1f370 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
1f380 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
1f390 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
1f3a0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
1f3b0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
1f3c0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
1f3d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
1f3e0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
1f3f0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
1f400 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
1f410 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
1f420 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 ..** ^If the act
1f430 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
1f440 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
1f450 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1f460 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
1f470 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
1f480 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
1f490 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
1f4a0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
1f4b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
1f4c0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
1f4d0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
1f4e0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
1f4f0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
1f500 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
1f510 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
1f520 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
1f530 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
1f540 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
1f550 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
1f560 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
1f570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
1f580 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
1f590 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
1f5a0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
1f5b0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
1f5c0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
1f5d0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
1f5e0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
1f5f0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
1f600 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
1f610 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
1f620 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
1f630 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
1f640 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
1f650 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
1f660 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
1f670 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
1f680 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
1f690 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
1f6a0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
1f6b0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
1f6c0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
1f6d0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
1f6e0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
1f6f0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
1f700 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
1f710 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
1f720 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
1f730 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
1f740 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
1f750 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
1f760 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
1f770 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
1f780 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
1f790 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
1f7a0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
1f7b0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
1f7c0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
1f7d0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
1f7e0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
1f7f0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
1f800 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
1f810 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
1f820 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
1f830 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
1f840 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
1f850 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
1f860 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
1f870 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
1f880 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 r..**.** ^(Only
1f890 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
1f8a0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
1f8b0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
1f8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1f8d0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
1f8e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
1f8f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1f900 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
1f910 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 previous call.)
1f920 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 ^ ^Disable the
1f930 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
1f940 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
1f950 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
1f960 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
1f970 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
1f980 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
1f990 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1f9a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
1f9b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
1f9c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
1f9d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f9e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1f9f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1fa00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
1fa10 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
1fa20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
1fa30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1fa40 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
1fa50 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
1fa60 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
1fa70 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
1fa80 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
1fa90 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
1faa0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f ^When [sqlite3_
1fab0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 prepare_v2()] is
1fac0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 used to prepare
1fad0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 a statement, th
1fae0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d e.** statement m
1faf0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 ight be re-prepa
1fb00 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
1fb10 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
1fb20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
1fb30 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
1fb40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1fb50 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
1fb60 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
1fb70 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
1fb80 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
1fb90 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
1fba0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1fbb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 )]..**.** ^Note
1fbc0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
1fbd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1fbe0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
1fbf0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1fc00 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
1fc10 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
1fc20 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
1fc30 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
1fc40 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
1fc50 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
1fc60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
1fc70 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 unless.** as sta
1fc80 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 ted in the previ
1fc90 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 ous paragraph, s
1fca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
1fcb0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 vokes.** sqlite3
1fcc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f _prepare_v2() to
1fcd0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 reprepare a sta
1fce0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 tement after a s
1fcf0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f chema change..*/
1fd00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1fd10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1fd20 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 orizer(. sqlite
1fd30 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 3*,. int (*xAut
1fd40 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e h)(void*,int,con
1fd50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
1fd60 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1fd70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 ,const char*),.
1fd80 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 void *pUserData
1fd90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1fda0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
1fdb0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a Return Codes.**.
1fdc0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
1fdd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1fde0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fdf0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d back function] m
1fe00 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 ust.** return ei
1fe10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ther [SQLITE_OK]
1fe20 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 or one of these
1fe30 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 two constants i
1fe40 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 n order.** to si
1fe50 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 gnal SQLite whet
1fe60 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 her or not the a
1fe70 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
1fe80 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 ed. See the.**
1fe90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1fea0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
1feb0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 izer documentati
1fec0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e on] for addition
1fed0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
1fee0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 n..**.** Note th
1fef0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 at SQLITE_IGNORE
1ff00 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 is also used as
1ff10 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 a [conflict res
1ff20 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a olution mode].**
1ff30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 returned from t
1ff40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 he [sqlite3_vtab
1ff50 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 _on_conflict()]
1ff60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 interface..*/.#d
1ff70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e efine SQLITE_DEN
1ff80 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 Y 1 /* Abort
1ff90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1ffa0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 nt with an error
1ffb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ffc0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a TE_IGNORE 2 /*
1ffd0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 Don't allow acc
1ffe0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 ess, but don't g
1fff0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 enerate an error
20000 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
20010 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
20020 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a Action Codes.**.
20030 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
20040 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
20050 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
20060 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
20070 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 function.** tha
20080 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 t is invoked to
20090 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 authorize certai
200a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
200b0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a actions. The.**
200c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
200d0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 r to the callbac
200e0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
200f0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 code that specif
20100 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 ies.** what acti
20110 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 on is being auth
20120 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 orized. These a
20130 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 re the integer a
20140 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 ction codes that
20150 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
20160 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 er callback may
20170 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a be passed..**.**
20180 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f These action co
20190 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 de values signif
201a0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f y what kind of o
201b0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 peration is to b
201c0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e e.** authorized.
201d0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 The 3rd and 4t
201e0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
201f0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f the authorizatio
20200 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 n.** callback fu
20210 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 nction will be p
20220 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c arameters or NUL
20230 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 L depending on w
20240 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a hich of these.**
20250 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 codes is used a
20260 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
20270 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 ameter. ^(The 5
20280 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
20290 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
202a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
202b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
202c0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 tabase ("main",
202d0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 "temp",.** etc.)
202e0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 if applicable.)
202f0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 ^ ^The 6th para
20300 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
20310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20320 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
20330 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 of the inner-mos
20340 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 t trigger or vie
20350 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e w that is respon
20360 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 sible for.** the
20370 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
20380 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 or NULL if this
20390 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 access attempt i
203a0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a s directly from.
203b0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c ** top-level SQL
203c0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
203d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
203e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
203f0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
20400 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
20410 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
20420 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
20430 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
20440 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
20450 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
20460 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20470 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
20480 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
20490 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
204a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
204b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
204c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
204d0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
204e0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
204f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20500 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20510 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
20520 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
20530 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20540 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
20550 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20560 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
20570 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
20580 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
20590 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
205a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
205b0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
205c0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
205d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
205e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
205f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20600 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
20610 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
20620 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
20630 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
20640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20650 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
20660 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
20670 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
20680 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
206a0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
206b0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
206c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
206d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
206e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
206f0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
20700 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
20710 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
20720 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
20730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
20740 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
20750 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
20760 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
20770 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
20780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
20790 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
207a0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
207b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
207c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
207d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
207e0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
207f0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
20800 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20810 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
20820 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
20830 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
20840 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
20850 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
20860 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
20870 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
20880 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
20890 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
208a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
208b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
208c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
208d0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
208e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
208f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20900 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20910 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
20920 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
20930 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
20940 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
20950 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20960 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
20970 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
20980 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20990 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
209a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
209b0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
209c0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
209d0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
209e0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
209f0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
20a00 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
20a10 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
20a20 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
20a30 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
20a40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
20a50 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
20a60 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
20a70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20a80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20aa0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
20ab0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
20ac0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
20ad0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20af0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
20b00 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
20b10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
20b20 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
20b30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20b40 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
20b50 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
20b60 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
20b70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20b90 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
20ba0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
20bb0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
20bc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
20bd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
20be0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
20bf0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
20c00 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
20c10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
20c20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
20c30 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
20c40 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
20c50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
20c60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
20c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
20c80 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
20c90 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
20ca0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
20cb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
20cc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
20cd0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
20ce0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
20cf0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
20d00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
20d10 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
20d20 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
20d30 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
20d40 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
20d50 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
20d60 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
20d70 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
20d80 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
20d90 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 Function
20da0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
20db0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 e SQLITE_SAVEPOI
20dc0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 NT 32
20dd0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
20de0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 Savepoint
20df0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 Name */.#define
20e00 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
20e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
20e20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
20e30 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 sed */.#define S
20e40 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 QLITE_RECURSIVE
20e50 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 33
20e60 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
20e70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20e80 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */../*.** CAP
20e90 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
20ea0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
20eb0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
20ec0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
20ed0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
20ee0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
20ef0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
20f00 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
20f10 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
20f20 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
20f30 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
20f40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
20f50 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
20f60 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
20f70 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
20f80 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
20f90 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
20fa0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
20fb0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
20fc0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
20fd0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
20fe0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
20ff0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
21000 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
21010 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
21020 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
21030 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
21040 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
21050 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
21060 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
21070 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
21080 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
21090 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
210a0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
210b0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
210c0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
210d0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
210e0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
210f0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
21100 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
21110 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
21120 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
21130 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
21140 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
21150 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 d to limit.** th
21160 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 e length of [bou
21170 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 nd parameter] ex
21180 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f pansion in the o
21190 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 utput of sqlite3
211a0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 _trace()..**.**
211b0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
211c0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
211d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
211e0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
211f0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
21200 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
21210 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
21220 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
21230 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
21240 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
21250 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
21260 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
21270 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
21280 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
21290 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
212a0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
212b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 callback.** time
212c0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 is in units of
212d0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 nanoseconds, how
212e0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 ever the current
212f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
21300 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 ** is only capab
21310 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e le of millisecon
21320 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 d resolution so
21330 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 the six least si
21340 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 gnificant.** dig
21350 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 its in the time
21360 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e are meaningless.
21370 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
21380 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
21390 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 ight provide gre
213a0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 ater resolution
213b0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 on the profiler
213c0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a callback. The.*
213d0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c * sqlite3_profil
213e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
213f0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 considered exper
21400 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a imental and is.*
21410 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 * subject to cha
21420 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 nge in future ve
21430 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
21440 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
21450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 void *sqlite3_tr
21460 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ace(sqlite3*, vo
21470 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
21480 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
21490 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
214a0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
214b0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c MENTAL void *sql
214c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
214d0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
214e0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
214f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
21500 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 te3_uint64), voi
21510 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
21520 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 3REF: Query Prog
21530 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a ress Callbacks.*
21540 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
21550 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
21560 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 er(D,N,X,P) inte
21570 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 rface causes the
21580 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
21590 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e ction X to be in
215a0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c voked periodical
215b0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 ly during long r
215c0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a unning calls to.
215d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
215e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
215f0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ep()] and [sqlit
21600 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
21610 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 for.** database
21620 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 connection D. A
21630 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f n example use fo
21640 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 r this.** interf
21650 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 ace is to keep a
21660 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 GUI updated dur
21670 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 ing a large quer
21680 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 y..**.** ^The pa
21690 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 rameter P is pas
216a0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
216b0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
216c0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c r to the .** cal
216d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
216e0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 . ^The paramete
216f0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f r N is the appro
21700 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 ximate number of
21710 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 .** [virtual ma
21720 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f chine instructio
21730 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 ns] that are eva
21740 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 luated between s
21750 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 uccessive.** inv
21760 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
21770 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 callback X. ^If
21780 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
21790 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f one then the pro
217a0 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 gress.** handler
217b0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a is disabled..**
217c0 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 .** ^Only a sing
217d0 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 le progress hand
217e0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e ler may be defin
217f0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 ed at one time p
21800 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 er.** [database
21810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 connection]; set
21820 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 ting a new progr
21830 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 ess handler canc
21840 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f els the.** old o
21850 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 ne. ^Setting pa
21860 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c rameter X to NUL
21870 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 L disables the p
21880 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
21890 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 .** ^The progres
218a0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 s handler is als
218b0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 o disabled by se
218c0 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c tting N to a val
218d0 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 ue less.** than
218e0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 1..**.** ^If the
218f0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
21900 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
21910 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 ero, the operati
21920 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
21930 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
21940 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
21950 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
21960 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
21970 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 n on a GUI progr
21980 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a ess dialog box..
21990 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 **.** The progre
219a0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 ss handler callb
219b0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
219c0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
219d0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
219e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
219f0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
21a00 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
21a10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
21a20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
21a30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
21a40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21a50 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
21a60 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
21a70 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
21a80 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
21a90 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
21aa0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a aragraph..**.*/.
21ab0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
21ac0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
21ad0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
21ae0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 *, int, int(*)(v
21af0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a oid*), void*);..
21b00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21b10 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 Opening A New Da
21b20 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
21b30 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 n.**.** ^These r
21b40 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 outines open an
21b50 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
21b60 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 file as specifie
21b70 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c d by the .** fil
21b80 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 ename argument.
21b90 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 ^The filename ar
21ba0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 gument is interp
21bb0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 reted as UTF-8 f
21bc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
21bd0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
21be0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 _open_v2() and a
21bf0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 s UTF-16 in the
21c00 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f native byte.** o
21c10 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 rder for sqlite3
21c20 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b _open16(). ^(A [
21c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21c40 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 ion] handle is u
21c50 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e sually.** return
21c60 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 ed in *ppDb, eve
21c70 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 n if an error oc
21c80 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 curs. The only
21c90 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 exception is tha
21ca0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 t.** if SQLite i
21cb0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
21cc0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
21cd0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 old the [sqlite3
21ce0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e ] object,.** a N
21cf0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 ULL will be writ
21d00 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 ten into *ppDb i
21d10 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e nstead of a poin
21d20 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
21d30 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 te3].** object.)
21d40 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 ^ ^(If the datab
21d50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
21d60 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
21d70 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
21d80 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
21d90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
21da0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
21db0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
21dc0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 rned.)^ ^The.**
21dd0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
21de0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
21df0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 rrmsg16()] routi
21e00 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nes can be used
21e10 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 to obtain.** an
21e20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 English language
21e30 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
21e40 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 the error follow
21e50 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 ing a failure of
21e60 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 any.** of the s
21e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f qlite3_open() ro
21e80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 utines..**.** ^T
21e90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
21ea0 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ing will be UTF-
21eb0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 8 for databases
21ec0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a created using.**
21ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
21ee0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
21ef0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 v2(). ^The defa
21f00 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ult encoding for
21f10 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 databases.** cr
21f20 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 eated using sqli
21f30 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c te3_open16() wil
21f40 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 l be UTF-16 in t
21f50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
21f60 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 rder..**.** Whet
21f70 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 her or not an er
21f80 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 ror occurs when
21f90 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 it is opened, re
21fa0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 sources.** assoc
21fb0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
21fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
21fd0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 ion] handle shou
21fe0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 ld be released b
21ff0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 y.** passing it
22000 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
22010 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 e()] when it is
22020 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 no longer requir
22030 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
22040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
22050 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 interface works
22060 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 like sqlite3_ope
22070 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
22080 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 at it accepts tw
22090 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 o additional par
220a0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 ameters for addi
220b0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a tional control.*
220c0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 * over the new d
220d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
220e0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 on. ^(The flags
220f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
22100 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
22110 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 () can take one
22120 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
22130 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
22140 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
22150 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
22160 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
22170 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 NOMUTEX], [SQLIT
22180 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
22190 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
221a0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a SHAREDCACHE],.**
221b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
221c0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 IVATECACHE], and
221d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e /or [SQLITE_OPEN
221e0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a _URI] flags:)^.*
221f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
22200 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
22210 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
22220 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
22230 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
22240 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
22250 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
22260 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
22270 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
22280 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
22290 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
222a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
222b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
222c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
222d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
222e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
222f0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
22300 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
22310 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
22320 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
22330 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
22340 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
22350 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
22360 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
22370 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
22380 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
22390 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
223a0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
223b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
223c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
223d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
223e0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
223f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
22400 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
22410 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
22420 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 , and is created
22430 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
22440 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
22450 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
22460 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
22470 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
22480 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
22490 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
224a0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a n16().</dd>)^.**
224b0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
224c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
224d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
224e0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
224f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
22500 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
22510 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 bove optionally
22520 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 combined with ot
22530 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f her.** [SQLITE_O
22540 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 PEN_READONLY | S
22550 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 QLITE_OPEN_* bit
22560 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 s].** then the b
22570 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
22580 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ined..**.** ^If
22590 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
225a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 _NOMUTEX] flag i
225b0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 s set, then the
225c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
225d0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 ion.** opens in
225e0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 the multi-thread
225f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
22600 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ] as long as the
22610 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a single-thread.*
22620 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 * mode has not b
22630 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 een set at compi
22640 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
22650 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a -time. ^If the.
22660 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
22670 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 FULLMUTEX] flag
22680 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 is set then the
22690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
226a0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 ion opens.** in
226b0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
226c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
226d0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 unless single-th
226e0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 read was.** prev
226f0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 iously selected
22700 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
22710 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a or start-time..*
22720 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
22730 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
22740 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
22750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
22760 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c tion to be.** el
22770 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 igible to use [s
22780 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
22790 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ], regardless of
227a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
227b0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
227c0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 is enabled using
227d0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
227e0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d _shared_cache()]
227f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 . ^The.** [SQLI
22800 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
22810 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
22820 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
22830 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 onnection to not
22840 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 .** participate
22850 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 in [shared cache
22860 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 mode] even if i
22870 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a t is enabled..**
22880 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
22890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
228a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
228b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
228c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
228d0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
228e0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
228f0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
22900 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
22910 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
22920 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
22930 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 use. ^If the f
22940 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
22950 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
22960 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
22970 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
22980 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
22990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
229a0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a e filename is ":
229b0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 memory:", then a
229c0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
229d0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ary in-memory da
229e0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 tabase.** is cre
229f0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e ated for the con
22a00 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 nection. ^This
22a10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
22a20 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 se will vanish w
22a30 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 hen.** the datab
22a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
22a50 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 s closed. Futur
22a60 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
22a70 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 Lite might.** ma
22a80 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 ke use of additi
22a90 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c onal special fil
22aa0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 enames that begi
22ab0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 n with the ":" c
22ac0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 haracter..** It
22ad0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
22ae0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 hat when a datab
22af0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 ase filename act
22b00 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e ually does begin
22b10 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 with.** a ":" c
22b20 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f haracter you sho
22b30 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 uld prefix the f
22b40 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 ilename with a p
22b50 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a athname such as.
22b60 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 ** "./" to avoid
22b70 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a ambiguity..**.*
22b80 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
22b90 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
22ba0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
22bb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
22bc0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
22bd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
22be0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 ated. ^This pri
22bf0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 vate database wi
22c00 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ll be.** automat
22c10 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 ically deleted a
22c20 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 s soon as the da
22c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22c40 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
22c50 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
22c60 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 es in sqlite3_op
22c70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 en()]] <h3>URI F
22c80 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a ilenames</h3>.**
22c90 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c .** ^If [URI fil
22ca0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 ename] interpret
22cb0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
22cc0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 , and the filena
22cd0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 me argument.** b
22ce0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 egins with "file
22cf0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c :", then the fil
22d00 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 ename is interpr
22d10 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e eted as a URI. ^
22d20 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 URI.** filename
22d30 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
22d40 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 s enabled if the
22d50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
22d60 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 I] flag is.** se
22d70 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 t in the fourth
22d80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
22d90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f te3_open_v2(), o
22da0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 r if it has.** b
22db0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 een enabled glob
22dc0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b ally using the [
22dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
22de0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 I] option with t
22df0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
22e00 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 onfig()] method
22e10 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 or by the [SQLIT
22e20 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 E_USE_URI] compi
22e30 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a le-time option..
22e40 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 ** As of SQLite
22e50 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 version 3.7.7, U
22e60 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 RI filename inte
22e70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 rpretation is tu
22e80 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 rned off.** by d
22e90 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 efault, but futu
22ea0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
22eb0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 QLite might enab
22ec0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a le URI filename.
22ed0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f ** interpretatio
22ee0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 n by default. S
22ef0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d ee "[URI filenam
22f00 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f es]" for additio
22f10 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
22f20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 on..**.** URI fi
22f30 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 lenames are pars
22f40 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 ed according to
22f50 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 RFC 3986. ^If th
22f60 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 e URI contains a
22f70 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 n.** authority,
22f80 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 then it must be
22f90 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 either an empty
22fa0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 string or the st
22fb0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 ring .** "localh
22fc0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 ost". ^If the au
22fd0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 thority is not a
22fe0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
22ff0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 r "localhost", a
23000 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 n .** error is r
23010 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 eturned to the c
23020 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 aller. ^The frag
23030 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f ment component o
23040 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 f a URI, if .**
23050 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f present, is igno
23060 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 red..**.** ^SQLi
23070 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 te uses the path
23080 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 component of th
23090 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d e URI as the nam
230a0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 e of the disk fi
230b0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 le.** which cont
230c0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 ains the databas
230d0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 e. ^If the path
230e0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f begins with a '/
230f0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a ' character, .**
23100 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 then it is inte
23110 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 rpreted as an ab
23120 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 solute path. ^If
23130 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e the path does n
23140 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 ot begin .** wit
23150 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 h a '/' (meaning
23160 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
23170 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f ity section is o
23180 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
23190 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 URI).** then the
231a0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 path is interpr
231b0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 eted as a relati
231c0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f ve path. .** ^(O
231d0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 n windows, the f
231e0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f irst component o
231f0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 f an absolute pa
23200 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 th .** is a driv
23210 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 e specification
23220 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a (e.g. "C:").)^.*
23230 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 *.** [[core URI
23240 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
23250 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 ]].** The query
23260 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
23270 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 RI may contain p
23280 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 arameters that a
23290 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a re interpreted.*
232a0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 * either by SQLi
232b0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 te itself, or by
232c0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d a [VFS | custom
232d0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
232e0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ion]..** SQLite
232f0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e and its built-in
23300 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 [VFSes] interpr
23310 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 et the.** follow
23320 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 ing query parame
23330 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ters:.**.** <ul>
23340 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 .** <li> <b>vf
23350 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 s</b>: ^The "vfs
23360 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 " parameter may
23370 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 be used to speci
23380 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a fy the name of.*
23390 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 * a VFS obje
233a0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 ct that provides
233b0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
233c0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
233d0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 that should.**
233e0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 be used to ac
233f0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
23400 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 e file on disk.
23410 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ^If this option
23420 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 is set to.**
23430 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
23440 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
23450 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
23460 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 ^Specifying an
23470 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 unknown.** V
23480 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 FS is an error.
23490 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
234a0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
234b0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e d the vfs option
234c0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 is.** prese
234d0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 nt, then the VFS
234e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
234f0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 e option takes p
23500 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a recedence over.*
23510 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 * the value
23520 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f passed as the fo
23530 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
23540 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
23550 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
23560 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e > <b>mode</b>: ^
23570 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 (The mode parame
23580 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
23590 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 o either "ro", "
235a0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 rw",.** "rwc
235b0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 ", or "memory".
235c0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 Attempting to se
235d0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 t it to any othe
235e0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 r value is.**
235f0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a an error)^. .*
23600 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 * ^If "ro" i
23610 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
23620 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
23630 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
23640 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 d-only .** a
23650 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 ccess, just as i
23660 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
23670 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 EN_READONLY] fla
23680 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 g had been set i
23690 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 n the .** th
236a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
236b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
236c0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 ). ^If the mode
236d0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
236e0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 .** "rw", t
236f0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
23700 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
23710 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e ead-write (but n
23720 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 ot create) .**
23730 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 access, as if
23740 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
23750 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 DWRITE (but not
23760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
23770 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 TE) had .**
23780 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 been set. ^Value
23790 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 "rwc" is equiva
237a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
237b0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c both .** SQL
237c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
237d0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 TE and SQLITE_OP
237e0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 EN_CREATE. ^If
237f0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
23800 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f is.** set to
23810 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 "memory" then a
23820 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 pure [in-memory
23830 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 database] that
23840 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 never reads.**
23850 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f or writes fro
23860 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 m disk is used.
23870 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 ^It is an error
23880 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c to specify a val
23890 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 ue for.** th
238a0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
238b0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 that is less re
238c0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 strictive than t
238d0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 hat specified by
238e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 .** the flag
238f0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 s passed in the
23900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
23910 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
23920 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
23930 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a i> <b>cache</b>:
23940 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 ^The cache para
23950 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
23960 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 to either "shar
23970 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 ed" or.** "p
23980 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e rivate". ^Settin
23990 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 g it to "shared"
239a0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
239b0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a o setting the.**
239c0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
239d0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 _SHAREDCACHE bit
239e0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 in the flags ar
239f0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f gument passed to
23a00 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f .** sqlite3_
23a10 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 open_v2(). ^Sett
23a20 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 ing the cache pa
23a30 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 rameter to "priv
23a40 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 ate" is .**
23a50 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
23a60 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 tting the SQLITE
23a70 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
23a80 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e HE bit..** ^
23a90 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
23aa0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
23ab0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 the "cache" par
23ac0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e ameter is presen
23ad0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 t in.** a UR
23ae0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 I filename, its
23af0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 value overrides
23b00 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 any behavior req
23b10 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e uested by settin
23b20 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f g.** SQLITE_
23b30 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
23b40 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e E or SQLITE_OPEN
23b50 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 _SHAREDCACHE fla
23b60 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c g..**.** <li> <
23b70 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 b>psow</b>: ^The
23b80 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 psow parameter
23b90 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 indicates whethe
23ba0 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 r or not the.**
23bb0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f [powersafe o
23bc0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 verwrite] proper
23bd0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 ty does or does
23be0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 not apply to the
23bf0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 .** storage
23c00 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 media on which t
23c10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
23c20 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 resides..**.**
23c30 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c <li> <b>nolock<
23c40 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b /b>: ^The nolock
23c50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
23c60 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 boolean query pa
23c70 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 rameter.** w
23c80 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 hich if set disa
23c90 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e bles file lockin
23ca0 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f g in rollback jo
23cb0 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 urnal modes. Th
23cc0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 is.** is use
23cd0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e ful for accessin
23ce0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 g a database on
23cf0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 a filesystem tha
23d00 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 t does not.**
23d10 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e support lockin
23d20 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 g. Caution: Da
23d30 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
23d40 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 n might result i
23d50 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 f two.** or
23d60 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 more processes w
23d70 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 rite to the same
23d80 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e database and an
23d90 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a y one of those.*
23da0 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 * processes
23db0 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a uses nolock=1..*
23dc0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d *.** <li> <b>im
23dd0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 mutable</b>: ^Th
23de0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 e immutable para
23df0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
23e00 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 an query.**
23e10 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
23e20 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
23e30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
23e40 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 is stored on.**
23e50 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 read-only me
23e60 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 dia. ^When immu
23e70 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 table is set, SQ
23e80 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
23e90 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 t the.** dat
23ea0 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f abase file canno
23eb0 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 t be changed, ev
23ec0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 en by a process
23ed0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 with higher.**
23ee0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e privilege, an
23ef0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 d so the databas
23f00 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 e is opened read
23f10 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f -only and all lo
23f20 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 cking.** and
23f30 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f change detectio
23f40 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 n is disabled.
23f50 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 Caution: Setting
23f60 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a the immutable.*
23f70 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f * property o
23f80 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
23f90 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 e that does in f
23fa0 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 act change can r
23fb0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 esult.** in
23fc0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 incorrect query
23fd0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b results and/or [
23fe0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 SQLITE_CORRUPT]
23ff0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 errors..** S
24000 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
24010 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
24020 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 ]..** .**
24030 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 </ul>.**.** ^Spe
24040 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
24050 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 wn parameter in
24060 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e the query compon
24070 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 ent of a URI is
24080 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e not an.** error.
24090 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
240a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
240b0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 t understand add
240c0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a itional query.**
240d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 parameters. Se
240e0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 e "[query parame
240f0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 ters with specia
24100 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c l meaning to SQL
24110 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 ite]" for.** add
24120 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
24130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 ion..**.** [[URI
24140 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
24150 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c es]] <h3>URI fil
24160 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f ename examples</
24170 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 h3>.**.** <table
24180 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 border="1" alig
24190 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 n=center cellpad
241a0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c ding=5>.** <tr><
241b0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 th> URI filename
241c0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a s <th> Results.*
241d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
241e0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
241f0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
24200 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
24210 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
24220 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c directory..** <
24230 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
24240 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c me/fred/data.db<
24250 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 br>.**
24260 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 file:///home/fre
24270 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a d/data.db <br> .
24280 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
24290 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d ://localhost/hom
242a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
242b0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 br> <td> .**
242c0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 Open the d
242d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 atabase file "/h
242e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
242f0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 "..** <tr><td> f
24300 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 ile://darkstar/h
24310 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
24320 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
24330 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 An error. "da
24340 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 rkstar" is not a
24350 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 recognized auth
24360 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ority..** <tr><t
24370 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 d style="white-s
24380 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a pace:nowrap"> .*
24390 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
243a0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 ///C:/Documents%
243b0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 20and%20Settings
243c0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 /fred/Desktop/da
243d0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 ta.db.** <td
243e0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 > Windows only:
243f0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
24400 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 ata.db" on fred'
24410 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 s desktop on dri
24420 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 ve.** C
24430 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 :. Note that the
24440 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e %20 escaping in
24450 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 this example is
24460 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a not strictly .*
24470 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 * neces
24480 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 sary - space cha
24490 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 racters can be u
244a0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a sed literally.**
244b0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 in URI
244c0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c filenames..** <
244d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
244e0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 a.db?mode=ro&cac
244f0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 he=private <td>
24500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
24510 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 n file "data.db"
24520 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
24530 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 directory for re
24540 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a ad-only access..
24550 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 ** Rega
24560 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
24570 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d r or not shared-
24580 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e cache mode is en
24590 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 abled by.**
245a0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 default, us
245b0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 e a private cach
245c0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 e..** <tr><td> f
245d0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
245e0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d ata.db?vfs=unix-
245f0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 dotfile <td>.**
24600 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
24610 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
24620 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 ata.db". Use the
24630 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e special VFS "un
24640 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 ix-dotfile".**
24650 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 that use
24660 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 s dot-files in p
24670 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 lace of posix ad
24680 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a visory locking..
24690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
246a0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 :data.db?mode=re
246b0 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 adonly <td> .**
246c0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
246d0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 r. "readonly" is
246e0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 not a valid opt
246f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 ion for the "mod
24700 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a e" parameter..**
24710 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 </table>.**.**
24720 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c ^URI hexadecimal
24730 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
24740 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 s (%HH) are supp
24750 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 orted within the
24760 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 path and.** que
24770 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
24780 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 a URI. A hexade
24790 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
247a0 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f uence consists o
247b0 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 f a.** percent s
247c0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c ign - "%" - foll
247d0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 owed by exactly
247e0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 two hexadecimal
247f0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 digits .** speci
24800 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 fying an octet v
24810 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 alue. ^Before th
24820 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 e path or query
24830 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a components of a.
24840 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 ** URI filename
24850 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c are interpreted,
24860 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 they are encode
24870 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e d using UTF-8 an
24880 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 d all .** hexade
24890 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
248a0 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 uences replaced
248b0 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 by a single byte
248c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
248d0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ** corresponding
248e0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 octet. If this
248f0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 process generate
24900 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 s an invalid UTF
24910 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 -8 encoding,.**
24920 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
24930 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
24940 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
24950 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
24960 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
24970 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
24980 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
24990 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
249a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
249b0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
249c0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
249d0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
249e0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
249f0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
24a00 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
24a10 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
24a20 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
24a30 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
24a40 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
24a50 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
24a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
24a70 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
24a80 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 2()..**.** <b>No
24a90 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 te to Windows Ru
24aa0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e ntime users:</b>
24ab0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 The temporary
24ac0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 directory must b
24ad0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 e set.** prior t
24ae0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 o calling sqlite
24af0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
24b00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
24b10 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f Otherwise, vario
24b20 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 us.** features t
24b30 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 hat require the
24b40 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 use of temporary
24b50 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e files may fail.
24b60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
24b70 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 [sqlite3_temp_d
24b80 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c irectory].*/.SQL
24b90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
24ba0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
24bb0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
24bc0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
24bd0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
24be0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
24bf0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
24c00 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
24c10 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c handle */.);.SQL
24c20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
24c30 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
24c40 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
24c50 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
24c60 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
24c70 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
24c80 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
24c90 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
24ca0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
24cb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
24cc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
24cd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
24ce0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
24cf0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
24d00 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
24d10 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
24d20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
24d30 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
24d40 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
24d50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
24d60 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
24d70 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
24d80 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
24d90 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
24da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24db0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
24dc0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
24dd0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
24de0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
24df0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
24e00 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
24e10 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
24e20 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
24e30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
24e40 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
24e50 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
24e60 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
24e70 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
24e80 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
24e90 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
24ea0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
24eb0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
24ec0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
24ed0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
24ee0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
24ef0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
24f00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
24f10 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
24f20 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
24f30 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
24f40 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
24f50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
24f60 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
24f70 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
24f80 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
24f90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
24fa0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
24fb0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
24fc0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
24fd0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
24fe0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
24ff0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
25000 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
25010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
25020 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
25030 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
25040 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
25050 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
25060 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
25070 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
25080 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
25090 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
250a0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
250b0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
250c0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
250d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
250e0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
250f0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
25100 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
25110 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
25120 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
25130 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
25140 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
25150 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
25160 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
25170 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
25180 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
25190 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
251a0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
251b0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
251c0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
251d0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
251e0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
251f0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
25200 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
25210 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
25220 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
25230 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
25240 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
25250 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
25260 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
25270 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
25280 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
25290 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
252a0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
252b0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
252c0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
252d0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
252e0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
252f0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
25300 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
25310 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
25320 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
25330 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
25340 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
25350 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
25360 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
25370 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
25380 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
25390 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
253a0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
253b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
253c0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
253d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
253e0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
253f0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
25400 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
25410 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
25420 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
25430 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
25440 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
25450 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
25460 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
25470 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
25480 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
25490 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
254a0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
254b0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
254c0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
254d0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
254e0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
254f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
25500 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
25510 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
25520 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
25530 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
25540 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
25550 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
25560 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
25570 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
25580 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
25590 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
255a0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 sirable..*/.SQLI
255b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
255c0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 r *sqlite3_uri_p
255d0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 arameter(const c
255e0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 har *zFilename,
255f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 const char *zPar
25600 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 am);.SQLITE_API
25610 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f int sqlite3_uri_
25620 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 boolean(const ch
25630 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 ar *zFile, const
25640 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 char *zParam, i
25650 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 nt bDefault);.SQ
25660 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
25670 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 _int64 sqlite3_u
25680 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 ri_int64(const c
25690 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 har*, const char
256a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
256b0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 );.../*.** CAPI3
256c0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 REF: Error Codes
256d0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a And Messages.**
256e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
256f0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 _errcode() inter
25700 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
25710 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 numeric [result
25720 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 code] or.** [ex
25730 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
25740 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 de] for the most
25750 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 recent failed s
25760 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
25770 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 l.** associated
25780 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
25790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 connection]. If
257a0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c a prior API cal
257b0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 l failed.** but
257c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
257d0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 API call succeed
257e0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ed, the return v
257f0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c alue from.** sql
25800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
25810 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 s undefined. ^T
25820 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
25830 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a ded_errcode().**
25840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
25850 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 e same except th
25860 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 at it always ret
25870 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 urns the .** [ex
25880 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
25890 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 de] even when ex
258a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
258b0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 des are.** disab
258c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
258d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
258e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 and sqlite3_err
258f0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 msg16() return E
25900 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a nglish-language.
25910 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 ** text that des
25920 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
25930 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d , as either UTF-
25940 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 8 or UTF-16 resp
25950 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d ectively..** ^(M
25960 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
25970 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
25980 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
25990 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a d internally..**
259a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
259b0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
259c0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 o worry about fr
259d0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 eeing the result
259e0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
259f0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d e error string m
25a00 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 ight be overwrit
25a10 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ten or deallocat
25a20 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 ed by.** subsequ
25a30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 ent calls to oth
25a40 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
25a50 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e ace functions.)^
25a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
25a70 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 te3_errstr() int
25a80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
25a90 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 he English-langu
25aa0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 age text.** that
25ab0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b describes the [
25ac0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 result code], as
25ad0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d UTF-8..** ^(Mem
25ae0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
25af0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
25b00 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
25b10 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e internally.** an
25b20 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 d must not be fr
25b30 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 eed by the appli
25b40 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 cation)^..**.**
25b50 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 When the seriali
25b60 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
25b70 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 ode] is in use,
25b80 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a it might be the.
25b90 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 ** case that a s
25ba0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 econd error occu
25bb0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 rs on a separate
25bc0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 thread in betwe
25bd0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f en.** the time o
25be0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f f the first erro
25bf0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 r and the call t
25c00 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 o these interfac
25c10 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 es..** When that
25c20 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 happens, the se
25c30 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 cond error will
25c40 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 be reported sinc
25c50 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 e these.** inter
25c60 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 faces always rep
25c70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ort the most rec
25c80 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 ent result. To
25c90 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 avoid.** this, e
25ca0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f ach thread can o
25cb0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 btain exclusive
25cc0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 use of the [data
25cd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
25ce0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e D.** by invokin
25cf0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
25d00 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 _enter]([sqlite3
25d10 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 _db_mutex](D)) b
25d20 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a efore beginning.
25d30 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 ** to use D and
25d40 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 invoking [sqlite
25d50 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 3_mutex_leave]([
25d60 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
25d70 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 ](D)) after.** a
25d80 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ll calls to the
25d90 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 interfaces liste
25da0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c d here are compl
25db0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 eted..**.** If a
25dc0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c n interface fail
25dd0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 s with SQLITE_MI
25de0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 SUSE, that means
25df0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a the interface.*
25e00 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e * was invoked in
25e10 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 correctly by the
25e20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 application. I
25e30 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 n that case, the
25e40 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 .** error code a
25e50 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f nd message may o
25e60 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 r may not be set
25e70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
25e80 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
25e90 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
25ea0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
25eb0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
25ec0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
25ed0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
25ee0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
25ef0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 qlite3_errmsg(sq
25f00 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f lite3*);.SQLITE_
25f10 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
25f20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
25f30 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
25f40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
25f50 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 r *sqlite3_errst
25f60 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 r(int);../*.** C
25f70 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 API3REF: SQL Sta
25f80 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
25f90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 KEYWORDS: {prep
25fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 ared statement}
25fb0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
25fc0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 ents}.**.** An i
25fd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
25fe0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
25ff0 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 s a single SQL s
26000 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 tatement..** Thi
26010 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 s object is vari
26020 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 ously known as a
26030 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 "prepared state
26040 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 ment" or a.** "c
26050 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
26060 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 ement" or simply
26070 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 as a "statement
26080 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 "..**.** The lif
26090 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 e of a statement
260a0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d object goes som
260b0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 ething like this
260c0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
260d0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 <li> Create the
260e0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
260f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
26100 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 ()] or a related
26110 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f .** functio
26120 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 n..** <li> Bind
26130 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 values to [host
26140 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e parameters] usin
26150 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
26160 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 nd_*().** i
26170 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c nterfaces..** <l
26180 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 i> Run the SQL b
26190 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
261a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f e3_step()] one o
261b0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
261c0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 <li> Reset the
261d0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
261e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
261f0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a ] then go back.*
26200 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 * to step 2
26210 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 . Do this zero
26220 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
26230 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 * <li> Destroy t
26240 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
26250 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
26260 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a e()]..** </ol>.*
26270 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f *.** Refer to do
26280 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 cumentation on i
26290 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 ndividual method
262a0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 s above for addi
262b0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
262c0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ation..*/.typede
262d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
262e0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
262f0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
26300 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
26310 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 mits.**.** ^(Thi
26320 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
26330 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 ws the size of v
26340 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 arious construct
26350 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a s to be limited.
26360 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 ** on a connecti
26370 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e on by connection
26380 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 basis. The fir
26390 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
263a0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
263b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f connection] who
263c0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 se limit is to b
263d0 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 e set or queried
263e0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
263f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e parameter is on
26400 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 e of the [limit
26410 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 categories] that
26420 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 define a.** cla
26430 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 ss of constructs
26440 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 to be size limi
26450 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 ted. The third
26460 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
26470 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f .** new limit fo
26480 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 r that construct
26490 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 .)^.**.** ^If th
264a0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 e new limit is a
264b0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
264c0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 , the limit is u
264d0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 nchanged..** ^(F
264e0 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 or each limit ca
264f0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 tegory SQLITE_LI
26500 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 MIT_<i>NAME</i>
26510 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
26520 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
26530 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
26540 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
26550 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 e by a C preproc
26560 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c essor macro call
26570 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 ed.** [limits |
26580 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 SQLITE_MAX_<i>NA
26590 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 ME</i>]..** (The
265a0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 "_LIMIT_" in th
265b0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 e name is change
265c0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e d to "_MAX_".))^
265d0 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f .** ^Attempts to
265e0 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
265f0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
26600 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
26610 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
26620 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
26630 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a rd upper bound..
26640 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 **.** ^Regardles
26650 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
26660 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 not the limit wa
26670 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a s changed, the .
26680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ** [sqlite3_limi
26690 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 t()] interface r
266a0 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 eturns the prior
266b0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 value of the li
266c0 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 mit..** ^Hence,
266d0 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 to find the curr
266e0 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c ent value of a l
266f0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 imit without cha
26700 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d nging it,.** sim
26710 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 ply invoke this
26720 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 interface with t
26730 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
26740 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a er set to -1..**
26750 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d .** Run-time lim
26760 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 its are intended
26770 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c for use in appl
26780 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 ications that ma
26790 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 nage.** both the
267a0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 ir own internal
267b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 database and als
267c0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 o databases that
267d0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a are controlled.
267e0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 ** by untrusted
267f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
26800 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 . An example ap
26810 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 plication might
26820 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 be a.** web brow
26830 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
26840 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
26850 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
26860 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
26870 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
26880 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
26890 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
268a0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
268b0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
268c0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
268d0 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
268e0 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
268f0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
26900 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
26910 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
26920 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
26930 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
26940 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
26950 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
26960 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
26970 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
26980 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
26990 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
269a0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
269b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
269c0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
269d0 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
269e0 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
269f0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
26a00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
26a10 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
26a20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
26a30 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
26a40 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
26a50 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
26a60 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
26a70 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
26a80 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
26a90 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
26aa0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
26ab0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
26ac0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
26ad0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
26ae0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
26af0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
26b00 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
26b10 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 tegories.** KEYW
26b20 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 ORDS: {limit cat
26b30 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 egory} {*limit c
26b40 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
26b50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
26b60 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
26b70 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
26b80 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
26b90 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
26ba0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
26bb0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
26bc0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
26bd0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
26be0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
26bf0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
26c00 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
26c10 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
26c20 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
26c30 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
26c40 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
26c50 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
26c60 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
26c70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26c80 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
26c90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26ca0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
26cb0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
26cc0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 r table row, in
26cd0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a bytes.<dd>)^.**.
26ce0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26cf0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e T_SQL_LENGTH]] ^
26d00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
26d10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 T_SQL_LENGTH</dt
26d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
26d30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 imum length of a
26d40 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
26d50 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 in bytes.</dd>)
26d60 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26d70 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 _LIMIT_COLUMN]]
26d80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
26d90 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
26da0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26db0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
26dc0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
26dd0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
26de0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
26df0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
26e00 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
26e10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
26e20 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
26e30 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
26e40 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
26e50 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
26e60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26e70 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e T_EXPR_DEPTH]] ^
26e80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
26e90 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
26ea0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
26eb0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
26ec0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
26ed0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
26ee0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
26ef0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
26f00 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 OUND_SELECT]] ^(
26f10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
26f20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
26f30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26f40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
26f50 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f of terms in a co
26f60 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 mpound SELECT st
26f70 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a atement.</dd>)^.
26f80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26f90 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e IMIT_VDBE_OP]] ^
26fa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
26fb0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
26fc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26fd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
26fe0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
26ff0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
27000 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
27010 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
27020 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 L statement. Th
27030 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 is limit is not
27040 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 currently.** enf
27050 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 orced, though th
27060 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 at might be adde
27070 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 d in some future
27080 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 release of.** S
27090 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a QLite.</dd>)^.**
270a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
270b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d IT_FUNCTION_ARG]
270c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
270d0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
270e0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 G</dt>.** <dd>Th
270f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
27100 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e of arguments on
27110 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 a function.</dd
27120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
27130 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
27140 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 D]] ^(<dt>SQLITE
27150 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
27160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
27170 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
27180 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 f [ATTACH | atta
27190 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e ched databases].
271a0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b )^</dd>.**.** [[
271b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
271c0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
271d0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
271e0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
271f0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
27200 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
27210 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
27220 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
27230 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 ent to the [LIKE
27240 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f ] or.** [GLOB] o
27250 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e perators.</dd>)^
27260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
27270 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
27280 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 UMBER]].** ^(<dt
27290 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
272a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
272b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
272c0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 ximum index numb
272d0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d er of any [param
272e0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 eter] in an SQL
272f0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a statement.)^.**.
27300 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
27310 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d T_TRIGGER_DEPTH]
27320 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
27330 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
27340 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
27350 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
27360 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f of recursion fo
27370 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e r triggers.</dd>
27380 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27390 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
273a0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 HREADS]] ^(<dt>S
273b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
273c0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a ER_THREADS</dt>.
273d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
273e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 um number of aux
273f0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 iliary worker th
27400 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e reads that a sin
27410 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 gle.** [prepared
27420 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 statement] may
27430 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a start.</dd>)^.**
27440 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
27450 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
27460 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
27470 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
27480 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
27490 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 SQL_LENGTH
274a0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
274b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
274c0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 _COLUMN
274d0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 2.#de
274e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
274f0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 T_EXPR_DEPTH
27500 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
27510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27520 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
27530 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 CT 4.#
27540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
27550 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 MIT_VDBE_OP
27560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
27570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
27580 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
27590 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 G 6
275a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
275b0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 LIMIT_ATTACHED
275c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
275d0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
275e0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
275f0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 ERN_LENGTH
27600 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
27610 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
27620 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 _NUMBER
27630 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
27640 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
27650 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
27660 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
27670 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
27680 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 _THREADS
27690 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 11../*.** CAP
276a0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
276b0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
276c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
276d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
276e0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f mpiler}.**.** To
276f0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
27700 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 query, it must f
27710 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 irst be compiled
27720 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 into a byte-cod
27730 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 e.** program usi
27740 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 ng one of these
27750 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
27760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
27770 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
27780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
27790 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
277a0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 om a.** prior su
277b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
277c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
277d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
277e0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
277f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
27800 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 The database c
27810 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
27820 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f ot have been clo
27830 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 sed..**.** The s
27840 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 econd argument,
27850 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 "zSql", is the s
27860 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
27870 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 ompiled, encoded
27880 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 .** as either UT
27890 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 F-8 or UTF-16.
278a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
278b0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 are() and sqlite
278c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 3_prepare_v2().*
278d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 * interfaces use
278e0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 UTF-8, and sqli
278f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 te3_prepare16()
27900 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
27910 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 are16_v2().** us
27920 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
27930 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 ^If the nByte ar
27940 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 gument is less t
27950 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a han zero, then z
27960 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
27970 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
27980 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
27990 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e ^If nByte is non
279a0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
279b0 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 it is the maximu
279c0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 m.** number of
279d0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 bytes read from
279e0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 zSql. ^When nBy
279f0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
27a00 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 ve, the.** zSql
27a10 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 string ends at e
27a20 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 ither the first
27a30 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 '\000' or '\u000
27a40 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 0' character or.
27a50 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 ** the nByte-th
27a60 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 byte, whichever
27a70 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 comes first. If
27a80 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 the caller knows
27a90 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 .** that the sup
27aa0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 plied string is
27ab0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 nul-terminated,
27ac0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 then there is a
27ad0 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d small.** perform
27ae0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 ance advantage t
27af0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 o be gained by p
27b00 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 assing an nByte
27b10 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a parameter that.*
27b20 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 * is equal to th
27b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
27b40 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 s in the input s
27b50 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 tring <i>includi
27b60 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 ng</i>.** the nu
27b70 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 l-terminator byt
27b80 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 es as this saves
27b90 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 SQLite from hav
27ba0 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 ing to.** make a
27bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 copy of the inp
27bc0 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ut string..**.**
27bd0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e ^If pzTail is n
27be0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
27bf0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
27c00 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
27c10 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
27c20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
27c30 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
27c40 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
27c50 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
27c60 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
27c70 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
27c80 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
27c90 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
27ca0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
27cb0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
27cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 ed..**.** ^*ppSt
27cd0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
27ce0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
27cf0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
27d00 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
27d10 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
27d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
27d30 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 ep()]. ^If ther
27d40 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
27d50 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
27d60 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 to NULL. ^If t
27d70 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
27d80 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
27d90 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
27da0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
27db0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
27dc0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
27dd0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
27de0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
27df0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
27e00 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
27e10 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
27e20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
27e30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
27e40 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
27e50 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
27e60 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
27e70 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
27e80 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 ULL..**.** ^On s
27e90 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 uccess, the sqli
27ea0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 te3_prepare() fa
27eb0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 mily of routines
27ec0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
27ed0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 OK];.** otherwis
27ee0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
27ef0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
27f00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
27f10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
27f20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
27f30 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
27f40 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
27f50 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
27f60 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
27f70 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
27f80 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
27f90 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
27fa0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
27fb0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
27fc0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
27fd0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 .** ^In the "v2"
27fe0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
27ff0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
28000 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
28010 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
28020 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
28030 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
28040 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
28050 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
28060 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
28070 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
28080 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
28090 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
280a0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
280b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
280c0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
280d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
280e0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
280f0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
28100 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
28110 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
28120 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
28130 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
28140 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
28150 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
28160 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
28170 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
28180 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 again. As many
28190 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 as [SQLITE_MAX_S
281a0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 CHEMA_RETRY].**
281b0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 retries will occ
281c0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 ur before sqlite
281d0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 3_step() gives u
281e0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e p and returns an
281f0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e error..** </li>
28200 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
28210 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
28220 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
28230 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
28240 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
28250 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
28260 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
28270 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
28280 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 ]. ^The legacy
28290 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
282a0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
282b0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
282c0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
282d0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
282e0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
282f0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
28300 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 ion would have t
28310 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
28320 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
28330 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 _reset()].** in
28340 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
28350 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
28360 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
28370 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
28380 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
28390 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
283a0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
283b0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
283c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
283d0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
283e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
283f0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c the specific val
28400 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 ue bound to [par
28410 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 ameter | host pa
28420 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
28430 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
28440 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
28450 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 the choice of q
28460 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 uery plan for a
28470 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 statement,.** th
28480 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
28490 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
284a0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
284b0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 d, as if there h
284c0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 ad been .** a sc
284d0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 hema change, on
284e0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 the first [sqli
284f0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
28500 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 following any c
28510 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 hange.** to the
28520 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
28530 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
28540 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 f that [paramete
28550 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 r]. .** ^The spe
28560 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 cific value of W
28570 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 HERE-clause [par
28580 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e ameter] might in
28590 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 fluence the .**
285a0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
285b0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 plan if the para
285c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 meter is the lef
285d0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 t-hand side of a
285e0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 [LIKE].** or [G
285f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 LOB] operator or
28600 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
28610 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f r is compared to
28620 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 an indexed colu
28630 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 mn.** and the [S
28640 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 QLITE_ENABLE_STA
28650 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 T3] compile-time
28660 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
28670 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 ed..** </li>.**
28680 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ol>.*/.SQLITE_
28690 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
286a0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
286b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
286c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
286d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
286e0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
286f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
28700 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
28710 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
28720 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
28730 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
28740 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
28750 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
28760 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
28770 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
28780 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
28790 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
287a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
287b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
287c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
287d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
287e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
287f0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
28800 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
28810 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
28820 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
28830 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
28840 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
28850 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
28860 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
28870 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
28880 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
28890 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
288a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
288b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
288c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
288d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
288e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
288f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
28900 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
28910 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
28920 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 l */.);.SQLITE_A
28930 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
28940 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
28950 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
28960 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
28970 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
28980 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
28990 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
289a0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
289b0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
289c0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
289d0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
289e0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
289f0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
28a00 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
28a10 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
28a20 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
28a30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
28a40 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
28a50 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
28a60 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
28a70 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
28a80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
28a90 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 prepare16_v2(.
28aa0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
28ab0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
28ac0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
28ad0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
28ae0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
28af0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
28b00 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
28b10 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
28b20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
28b30 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
28b40 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
28b50 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
28b60 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
28b70 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
28b80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
28b90 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
28ba0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
28bb0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
28bc0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a f zSql */.);../*
28bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
28be0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 trieving Stateme
28bf0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 nt SQL.**.** ^Th
28c00 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
28c10 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
28c20 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
28c30 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
28c40 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
28c50 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
28c60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28c70 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
28c80 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
28c90 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
28ca0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
28cb0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
28cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28cd0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
28ce0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
28cf0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c *sqlite3_sql(sql
28d00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
28d10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
28d20 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
28d30 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
28d40 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
28d50 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 abase.**.** ^The
28d60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
28d70 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
28d80 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
28d90 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
28da0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
28db0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
28dc0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
28dd0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
28de0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
28df0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
28e00 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
28e10 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
28e20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
28e30 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
28e40 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
28e50 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
28e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
28e70 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
28e80 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
28e90 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
28ea0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
28eb0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
28ec0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
28ed0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
28ee0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
28ef0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
28f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
28f10 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
28f20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28f30 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
28f40 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
28f50 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
28f60 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
28f70 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
28f80 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
28f90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
28fa0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
28fb0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
28fc0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
28fd0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
28fe0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
28ff0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
29000 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
29010 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
29020 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
29030 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
29040 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
29050 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
29060 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
29070 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
29080 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
29090 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
290a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
290b0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
290c0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
290d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
290e0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
290f0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
29100 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
29110 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
29120 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
29130 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
29140 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
29150 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
29160 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
29170 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
29180 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
29190 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
291a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
291b0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
291c0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
291d0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
291e0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
291f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
29200 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
29210 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
29220 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
29230 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
29240 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
29250 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
29260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
29270 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
29280 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 readonly(sqlite3
29290 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
292a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
292b0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 Determine If A P
292c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
292d0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 t Has Been Reset
292e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
292f0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
29300 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
29310 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
29320 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 o) if the.** [pr
29330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29340 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 ] S has been ste
29350 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e pped at least on
29360 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 ce using .** [sq
29370 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 lite3_step(S)] b
29380 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 ut has not run t
29390 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 o completion and
293a0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 /or has not .**
293b0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 been reset using
293c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
293d0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 S)]. ^The sqlit
293e0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a e3_stmt_busy(S).
293f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
29400 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 urns false if S
29410 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
29420 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 r. If S is not
29430 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a .** NULL point
29440 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 er and is not a
29450 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
29460 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 id [prepared sta
29470 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
29480 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 t, then the beha
29490 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
294a0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
294b0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a ndesirable..**.*
294c0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
294d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 can be used in
294e0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c combination [sql
294f0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 ite3_next_stmt()
29500 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 ].** to locate a
29510 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ll prepared stat
29520 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
29530 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 d with a databas
29540 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e e .** connection
29550 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 that are in nee
29560 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 d of being reset
29570 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 . This can be u
29580 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d sed,.** for exam
29590 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 ple, in diagnost
295a0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 ic routines to s
295b0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 earch for prepar
295c0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ed .** statement
295d0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 s that are holdi
295e0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e ng a transaction
295f0 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 open..*/.SQLITE
29600 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
29610 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 _stmt_busy(sqlit
29620 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
29630 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
29640 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
29650 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 lue Object.** KE
29660 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
29670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29680 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
29690 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
296a0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
296b0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
296c0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
296d0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
296e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
296f0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
29700 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
29710 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
29720 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
29730 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
29740 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f es. ^Values sto
29750 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
29760 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
29770 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
29780 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
29790 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
297a0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
297b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
297c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
297d0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
297e0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
297f0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
29800 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
29810 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
29820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
29830 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
29840 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
29850 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
29860 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
29870 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
29880 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
29890 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
298a0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
298b0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
298c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
298d0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
298e0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
298f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
29900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
29910 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
29920 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
29930 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
29940 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
29950 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 x is held. An i
29960 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
29970 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
29980 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
29990 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
299a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
299b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
299c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
299d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
299e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
299f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
29a00 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
29a10 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
29a20 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
29a30 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
29a40 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
29a50 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
29a60 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
29a70 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
29a80 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
29a90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
29aa0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
29ab0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
29ac0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
29ad0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
29ae0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
29af0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
29b00 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
29b10 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
29b20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
29b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
29b40 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
29b50 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
29b60 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
29b70 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
29b80 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
29b90 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
29ba0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
29bb0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
29bc0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
29bd0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
29be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29bf0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
29c00 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
29c10 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
29c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
29c30 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
29c40 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
29c50 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
29c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
29c70 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
29c80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
29c90 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
29ca0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
29cb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
29cc0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
29cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
29ce0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
29cf0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
29d00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
29d10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
29d20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
29d30 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
29d40 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
29d50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
29d60 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
29d70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
29d80 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
29d90 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
29da0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
29db0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
29dc0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
29dd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
29de0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
29df0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
29e00 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
29e10 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
29e20 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
29e30 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
29e40 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
29e50 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
29e60 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
29e70 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
29e80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
29e90 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
29ea0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
29eb0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
29ec0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
29ed0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
29ee0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
29ef0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
29f00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
29f10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
29f20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
29f30 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
29f40 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
29f50 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
29f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
29f70 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
29f80 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
29f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
29fa0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
29fb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
29fc0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
29fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
29fe0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
29ff0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
2a000 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
2a010 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
2a020 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
2a030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2a040 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
2a050 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
2a060 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
2a070 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
2a080 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2a090 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
2a0a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
2a0b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
2a0c0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
2a0d0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
2a0e0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
2a0f0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
2a100 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
2a110 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 binding}.**.**
2a120 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 ^(In the SQL sta
2a130 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 tement text inpu
2a140 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
2a150 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
2a160 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
2a170 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
2a180 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b replaced by a [
2a190 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 parameter] that
2a1a0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 matches one of f
2a1b0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 ollowing.** temp
2a1c0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c lates:.**.** <ul
2a1d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 >.** <li> ?.**
2a1e0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c <li> ?NNN.** <l
2a1f0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> :VVV.** <li>
2a200 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 @VVV.** <li>
2a210 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a $VVV.** </ul>.**
2a220 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c .** In the templ
2a230 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 ates above, NNN
2a240 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e represents an in
2a250 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a teger literal,.*
2a260 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 * and VVV repres
2a270 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d ents an alphanum
2a280 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e eric identifier.
2a290 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 )^ ^The values
2a2a0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
2a2b0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
2a2c0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
2a2d0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
2a2e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
2a2f0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
2a300 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
2a310 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
2a320 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
2a330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
2a340 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2a350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2a360 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
2a370 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
2a380 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
2a390 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
2a3a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
2a3b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2a3c0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
2a3d0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 riants..**.** ^T
2a3e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2a3f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
2a400 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
2a410 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
2a420 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 ** ^The leftmost
2a430 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
2a440 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
2a450 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d . ^When the sam
2a460 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
2a470 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
2a480 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
2a490 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
2a4a0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
2a4b0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
2a4c0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
2a4d0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
2a4e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 e..** ^The index
2a4f0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
2a500 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
2a510 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
2a520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2a530 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2a540 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
2a550 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 red. ^The index
2a560 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
2a570 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
2a580 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
2a590 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 * ^The NNN value
2a5a0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
2a5b0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 1 and the [sqli
2a5c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
2a5d0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 parameter [SQLIT
2a5e0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
2a5f0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c _NUMBER] (defaul
2a600 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a t value: 999)..*
2a610 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
2a620 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
2a630 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
2a640 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
2a650 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 ** ^If the third
2a660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
2a670 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2a680 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
2a690 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 d_text16().** or
2a6a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2a6b0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ob() is a NULL p
2a6c0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 ointer then the
2a6d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a6e0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 .** is ignored a
2a6f0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c nd the end resul
2a700 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 t is the same as
2a710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 sqlite3_bind_nu
2a720 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e ll()..**.** ^(In
2a730 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
2a740 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
2a750 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
2a760 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
2a770 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2a780 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
2a790 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
2a7a0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
2a7b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
2a7c0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
2a7d0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
2a7e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
2a7f0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 acters.)^.** ^If
2a800 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2a810 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2a820 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 _bind_text() or
2a830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a840 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 t16().** is nega
2a850 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c tive, then the l
2a860 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
2a870 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 ing is.** the nu
2a880 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 mber of bytes up
2a890 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
2a8a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
2a8b0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 * If the fourth
2a8c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2a8d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
2a8e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
2a8f0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 en.** the behavi
2a900 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
2a910 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 .** If a non-neg
2a920 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 ative fourth par
2a930 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 ameter is provid
2a940 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 ed to sqlite3_bi
2a950 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 nd_text().** or
2a960 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2a970 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 t16() or sqlite3
2a980 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 _bind_text64() t
2a990 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 hen.** that para
2a9a0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 meter must be th
2a9b0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a e byte offset.**
2a9c0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
2a9d0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 erminator would
2a9e0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 occur assuming t
2a9f0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e he string were N
2aa00 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 UL.** terminated
2aa10 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 . If any NUL ch
2aa20 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 aracters occur a
2aa30 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c t byte offsets l
2aa40 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 ess than .** the
2aa50 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f value of the fo
2aa60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2aa70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e hen the resultin
2aa80 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 g string value w
2aa90 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 ill.** contain e
2aaa0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 mbedded NULs. T
2aab0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 he result of exp
2aac0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 ressions involvi
2aad0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 ng strings.** wi
2aae0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 th embedded NULs
2aaf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2ab00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 *.** ^The fifth
2ab10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
2ab20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 BLOB and string
2ab30 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 binding interfac
2ab40 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 es.** is a destr
2ab50 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 uctor used to di
2ab60 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
2ab70 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 B or.** string a
2ab80 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 fter SQLite has
2ab90 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
2aba0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 . ^The destruct
2abb0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 or is called.**
2abc0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
2abd0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 e BLOB or string
2abe0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c even if the cal
2abf0 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 l to bind API fa
2ac00 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ils..** ^If the
2ac10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 fifth argument i
2ac20 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c s.** the special
2ac30 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 value [SQLITE_S
2ac40 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c TATIC], then SQL
2ac50 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
2ac60 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 the.** informat
2ac70 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 ion is in static
2ac80 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 , unmanaged spac
2ac90 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e e and does not n
2aca0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e eed to be freed.
2acb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
2acc0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 h argument has t
2acd0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 he value [SQLITE
2ace0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 _TRANSIENT], the
2acf0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 n.** SQLite make
2ad00 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 s its own privat
2ad10 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 e copy of the da
2ad20 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 ta immediately,
2ad30 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 before.** the sq
2ad40 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
2ad50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a outine returns..
2ad60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 **.** ^The sixth
2ad70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
2ad80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
2ad90 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f () must be one o
2ada0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 f.** [SQLITE_UTF
2adb0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
2adc0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 6], [SQLITE_UTF1
2add0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 6BE], or [SQLITE
2ade0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 _UTF16LE].** to
2adf0 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f specify the enco
2ae00 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 ding of the text
2ae10 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 in the third pa
2ae20 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 rameter. If.**
2ae30 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 the sixth argume
2ae40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 nt to sqlite3_bi
2ae50 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e nd_text64() is n
2ae60 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a ot one of the.**
2ae70 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 allowed values
2ae80 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 shown above, or
2ae90 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f if the text enco
2aea0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
2aeb0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e t.** from the en
2aec0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 coding specified
2aed0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 by the sixth pa
2aee0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 rameter, then th
2aef0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 e behavior.** is
2af00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2af10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2af20 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 ind_zeroblob() r
2af30 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 outine binds a B
2af40 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 LOB of length N
2af50 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 that.** is fille
2af60 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 d with zeroes.
2af70 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 ^A zeroblob uses
2af80 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 a fixed amount
2af90 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 of memory.** (ju
2afa0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f st an integer to
2afb0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 hold its size)
2afc0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
2afd0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 g processed..**
2afe0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e Zeroblobs are in
2aff0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 tended to serve
2b000 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 as placeholders
2b010 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a for BLOBs whose.
2b020 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 ** content is la
2b030 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e ter written usin
2b040 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c g.** [sqlite3_bl
2b050 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
2b060 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
2b070 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 routines..** ^A
2b080 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 negative value f
2b090 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 or the zeroblob
2b0a0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 results in a zer
2b0b0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a o-length BLOB..*
2b0c0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 *.** ^If any of
2b0d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2b0e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 _*() routines ar
2b0f0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 e called with a
2b100 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2b110 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 for the [prepare
2b120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 d statement] or
2b130 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 with a prepared
2b140 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 statement for wh
2b150 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ich.** [sqlite3_
2b160 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e step()] has been
2b170 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 called more rec
2b180 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 ently than [sqli
2b190 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a te3_reset()],.**
2b1a0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 then the call w
2b1b0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
2b1c0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 TE_MISUSE]. If
2b1d0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 any sqlite3_bind
2b1e0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 _().** routine i
2b1f0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 s passed a [prep
2b200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2b210 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 that has been fi
2b220 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 nalized, the.**
2b230 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
2b240 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
2b250 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 harmful..**.**
2b260 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f ^Bindings are no
2b270 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 t cleared by the
2b280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2b290 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e )] routine..** ^
2b2a0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
2b2b0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
2b2c0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
2b2d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2b2e0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 ind_* routines r
2b2f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
2b300 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 ] on success or
2b310 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
2b320 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 e] if anything g
2b330 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b oes wrong..** ^[
2b340 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d SQLITE_TOOBIG] m
2b350 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 ight be returned
2b360 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 if the size of
2b370 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
2b380 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 .** exceeds limi
2b390 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 ts imposed by [s
2b3a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 qlite3_limit]([S
2b3b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
2b3c0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 TH]) or.** [SQLI
2b3d0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a TE_MAX_LENGTH]..
2b3e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 ** ^[SQLITE_RANG
2b3f0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 E] is returned i
2b400 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a f the parameter.
2b410 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 ** index is out
2b420 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c of range. ^[SQL
2b430 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 ITE_NOMEM] is re
2b440 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 turned if malloc
2b450 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 () fails..**.**
2b460 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2b470 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b480 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
2b490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b4a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
2b4b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
2b4c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2b4d0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2b4e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2b4f0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 bind_blob(sqlite
2b500 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2b510 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e nst void*, int n
2b520 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2b530 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b540 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
2b550 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2b560 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2b570 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
2b580 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2b590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2b5a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2b5b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2b5c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
2b5d0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
2b5e0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
2b5f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2b600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
2b610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b620 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 nt, int);.SQLITE
2b630 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2b640 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
2b650 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b660 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2b670 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2b680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2b690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2b6a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2b6b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
2b6c0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
2b6d0 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 tmt*,int,const c
2b6e0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 har*,int,void(*)
2b6f0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
2b700 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2b710 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
2b720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2b730 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
2b740 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
2b750 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2b760 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2b770 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 text64(sqlite3_s
2b780 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2b790 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f char*, sqlite3_
2b7a0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
2b7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b7c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c void(*)(void*),
2b7d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 unsigned char e
2b7e0 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 ncoding);.SQLITE
2b7f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2b800 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
2b810 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b820 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
2b830 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
2b840 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
2b850 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
2b860 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b870 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
2b880 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
2b890 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
2b8a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f s.**.** ^This ro
2b8b0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 utine can be use
2b8c0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
2b8d0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 mber of [SQL par
2b8e0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 ameters].** in a
2b8f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b900 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 ment]. SQL para
2b910 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e meters are token
2b920 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
2b930 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a "?", "?NNN", ":
2b940 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 AAA", "$AAA", or
2b950 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 "@AAA" that ser
2b960 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f ve as.** placeho
2b970 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 lders for values
2b980 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 that are [sqlit
2b990 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
2b9a0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 ound].** to the
2b9b0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 parameters at a
2b9c0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a later time..**.*
2b9d0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 * ^(This routine
2b9e0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e actually return
2b9f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2ba00 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 he largest (righ
2ba10 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 tmost).** parame
2ba20 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 ter. For all for
2ba30 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 ms except ?NNN,
2ba40 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 this will corres
2ba50 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e pond to the.** n
2ba60 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 umber of unique
2ba70 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 parameters. If
2ba80 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
2ba90 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 e ?NNN form are
2baa0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d used,.** there m
2bab0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ay be gaps in th
2bac0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 e list.)^.**.**
2bad0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2bae0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
2baf0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
2bb00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2bb10 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2bb20 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2bb30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2bb40 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
2bb50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2bb60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2bb70 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ter_count(sqlite
2bb80 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2bb90 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
2bba0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 Of A Host Parame
2bbb0 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ter.**.** ^The s
2bbc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2bbd0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
2bbe0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2bbf0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
2bc00 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
2bc10 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
2bc20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2bc30 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
2bc40 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
2bc50 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
2bc60 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
2bc70 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
2bc80 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
2bc90 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
2bca0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
2bcb0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
2bcc0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
2bcd0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
2bce0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
2bcf0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
2bd00 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
2bd10 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
2bd20 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
2bd30 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
2bd40 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
2bd50 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
2bd60 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
2bd70 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
2bd80 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
2bd90 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
2bda0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
2bdb0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
2bdc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
2bdd0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
2bde0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
2bdf0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
2be00 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
2be10 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
2be20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
2be30 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
2be40 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
2be50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
2be60 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
2be70 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
2be80 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
2be90 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
2bea0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
2beb0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
2bec0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
2bed0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
2bee0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
2bef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2bf00 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
2bf10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2bf20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2bf30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2bf40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2bf50 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2bf60 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
2bf70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2bf80 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
2bf90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2bfa0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2bfb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2bfc0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2bfd0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
2bfe0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
2bff0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
2c000 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
2c010 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 e.**.** ^Return
2c020 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
2c030 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
2c040 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e ven its name. ^
2c050 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
2c060 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
2c070 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
2c080 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
2c090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
2c0a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c0b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2c0c0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 . ^A zero.** is
2c0d0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
2c0e0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
2c0f0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 er is found. ^T
2c100 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
2c110 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
2c120 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
2c130 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
2c140 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
2c150 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
2c160 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
2c170 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
2c180 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
2c190 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2c1a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2c1b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2c1c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2c1d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2c1e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2c1f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c200 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2c210 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2c220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2c230 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
2c240 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
2c250 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
2c260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2c270 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
2c280 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
2c290 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
2c2a0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
2c2b0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
2c2c0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
2c2d0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
2c2e0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
2c2f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c300 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
2c310 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2c320 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
2c330 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
2c340 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
2c350 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
2c360 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 L..*/.SQLITE_API
2c370 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 int sqlite3_cle
2c380 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
2c390 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
2c3a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
2c3b0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
2c3c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
2c3d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2c3e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
2c3f0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
2c400 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
2c410 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2c420 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
2c430 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
2c440 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
2c450 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
2c460 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
2c470 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
2c480 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
2c490 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
2c4a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2c4b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
2c4c0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2c4d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2c4e0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
2c4f0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2c500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2c510 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
2c520 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
2c530 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2c540 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
2c550 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
2c560 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
2c570 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
2c580 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
2c590 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2c5a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
2c5b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
2c5c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2c5d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
2c5e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2c5f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
2c600 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2c610 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
2c620 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2c630 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
2c640 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
2c650 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
2c660 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
2c670 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2c680 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
2c690 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
2c6a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2c6b0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
2c6c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
2c6d0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
2c6e0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
2c6f0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
2c700 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
2c710 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2c720 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
2c730 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
2c740 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2c750 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
2c760 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
2c770 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2c780 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
2c790 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
2c7a0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
2c7b0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
2c7c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2c7d0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
2c7e0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
2c7f0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
2c800 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
2c810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2c820 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
2c830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
2c840 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
2c850 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
2c860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
2c870 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
2c880 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
2c890 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
2c8a0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
2c8b0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
2c8c0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
2c8d0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
2c8e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
2c8f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
2c900 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
2c910 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
2c920 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
2c930 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
2c940 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
2c950 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
2c960 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
2c970 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
2c980 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
2c990 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
2c9a0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
2c9b0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
2c9c0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
2c9d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
2c9e0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
2c9f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2ca00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2ca10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
2ca20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2ca30 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 N);.SQLITE_API c
2ca40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2ca50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2ca60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2ca70 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int N);../*.** C
2ca80 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 API3REF: Source
2ca90 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 Of Data In A Que
2caa0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 ry Result.**.**
2cab0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2cac0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
2cad0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
2cae0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2caf0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
2cb00 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
2cb10 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
2cb20 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
2cb30 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
2cb40 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2cb50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
2cb60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
2cb70 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
2cb80 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
2cb90 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
2cba0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
2cbb0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
2cbc0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
2cbd0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
2cbe0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
2cbf0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
2cc00 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
2cc10 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
2cc20 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
2cc30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2cc40 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
2cc50 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2cc60 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
2cc70 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
2cc80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
2cc90 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
2cca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
2ccb0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
2ccc0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
2ccd0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
2cce0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
2ccf0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
2cd00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2cd10 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
2cd20 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
2cd30 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
2cd40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
2cd50 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
2cd60 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
2cd70 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
2cd80 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
2cd90 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
2cda0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
2cdb0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
2cdc0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2cdd0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
2cde0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2cdf0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
2ce00 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
2ce10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ce20 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
2ce30 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2ce40 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
2ce50 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
2ce60 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
2ce70 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
2ce80 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
2ce90 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
2cea0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
2ceb0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
2cec0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
2ced0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
2cee0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
2cef0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2cf00 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
2cf10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2cf20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
2cf30 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
2cf40 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
2cf50 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
2cf60 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
2cf70 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
2cf80 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
2cf90 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
2cfa0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
2cfb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2cfc0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
2cfd0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
2cfe0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
2cff0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
2d000 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
2d010 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
2d020 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
2d030 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
2d040 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
2d050 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
2d060 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
2d070 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
2d080 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
2d090 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
2d0a0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
2d0b0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
2d0c0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
2d0d0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
2d0e0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
2d0f0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
2d100 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
2d110 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
2d120 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
2d130 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
2d140 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
2d150 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
2d160 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
2d170 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
2d180 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
2d190 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2d1a0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
2d1b0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
2d1c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
2d1d0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
2d1e0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
2d1f0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
2d200 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
2d210 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2d220 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2d230 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
2d240 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2d250 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
2d260 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
2d270 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
2d280 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
2d290 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
2d2a0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
2d2b0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
2d2c0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
2d2d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2d2e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2d2f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2d300 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
2d310 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2d320 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2d330 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2d340 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2d350 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2d360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d370 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2d380 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
2d390 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2d3a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2d3b0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2d3c0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2d3d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d3e0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
2d3f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2d400 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2d410 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2d420 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
2d430 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2d440 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2d450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2d460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
2d470 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
2d480 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
2d490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2d4a0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
2d4b0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
2d4c0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 lt.**.** ^(The f
2d4d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
2d4e0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
2d4f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 atement]..** If
2d500 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 this statement i
2d510 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 s a [SELECT] sta
2d520 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e tement and the N
2d530 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
2d540 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 .** returned res
2d550 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 ult set of that
2d560 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 [SELECT] is a ta
2d570 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 ble column (not
2d580 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
2d590 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 or subquery) th
2d5a0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 en the declared
2d5b0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
2d5c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 e.** column is r
2d5d0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 eturned.)^ ^If
2d5e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
2d5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2d600 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
2d610 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2d620 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
2d630 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
2d640 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 d..** ^The retur
2d650 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
2d660 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
2d670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 ed..**.** ^(For
2d680 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 example, given t
2d690 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
2d6a0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 ma:.**.** CREATE
2d6b0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 TABLE t1(c1 VAR
2d6c0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 IANT);.**.** and
2d6d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
2d6e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
2d6f0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 ompiled:.**.** S
2d700 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 ELECT c1 + 1, c1
2d710 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 FROM t1;.**.**
2d720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
2d730 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
2d740 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
2d750 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 or the second re
2d760 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 sult.** column (
2d770 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
2d780 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
2d790 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
2d7a0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a olumn (i==0).)^.
2d7b0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
2d7c0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
2d7d0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f ime typing. ^So
2d7e0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
2d7f0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
2d800 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
2d810 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
2d820 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
2d830 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
2d840 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
2d850 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
2d860 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
2d870 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
2d880 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
2d890 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
2d8a0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
2d8b0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 tic. ^Type.** i
2d8c0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
2d8d0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c h individual val
2d8e0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 ues, not with th
2d8f0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 e containers.**
2d900 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f used to hold tho
2d910 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 se values..*/.SQ
2d920 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2d930 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
2d940 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c umn_decltype(sql
2d950 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2d960 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2d970 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2d980 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
2d990 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2d9a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2d9b0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
2d9c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2d9d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
2d9e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d9f0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
2da00 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
2da10 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
2da20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2da30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2da40 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
2da50 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
2da60 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
2da70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2da80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2da90 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
2daa0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
2dab0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
2dac0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
2dad0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
2dae0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
2daf0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
2db00 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
2db10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2db20 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
2db30 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
2db40 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
2db50 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
2db60 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
2db70 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
2db80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2db90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2dba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2dbb0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
2dbc0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2dbd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2dbe0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2dbf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
2dc00 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
2dc10 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
2dc20 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2dc30 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
2dc40 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
2dc50 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
2dc60 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
2dc70 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
2dc80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 ed..**.** ^In th
2dc90 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2dca0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ce, the return v
2dcb0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 alue will be eit
2dcc0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 her [SQLITE_BUSY
2dcd0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f ],.** [SQLITE_DO
2dce0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 NE], [SQLITE_ROW
2dcf0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ], [SQLITE_ERROR
2dd00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 ], or [SQLITE_MI
2dd10 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 SUSE]..** ^With
2dd20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2dd30 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f ce, any of the o
2dd40 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 ther [result cod
2dd50 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e es] or.** [exten
2dd60 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2dd70 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
2dd80 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a ned as well..**.
2dd90 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 ** ^[SQLITE_BUSY
2dda0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2ddb0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2ddc0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 was unable to a
2ddd0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 cquire the.** da
2dde0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 tabase locks it
2ddf0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 needs to do its
2de00 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 job. ^If the st
2de10 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f atement is a [CO
2de20 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 MMIT].** or occu
2de30 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e rs outside of an
2de40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
2de50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 ction, then you
2de60 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a can retry the.**
2de70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 statement. If
2de80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2de90 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 not a [COMMIT]
2dea0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 and occurs withi
2deb0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 n an.** explicit
2dec0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
2ded0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
2dee0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
2def0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
2df00 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
2df10 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d * ^[SQLITE_DONE]
2df20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2df30 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
2df40 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2df50 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
2df60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2df70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2df80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
2df90 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
2dfa0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
2dfb0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
2dfc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2dfd0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
2dfe0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
2dff0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
2e000 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
2e010 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 ^If the SQL sta
2e020 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 tement being exe
2e030 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e cuted returns an
2e040 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 y data, then [SQ
2e050 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 LITE_ROW].** is
2e060 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
2e070 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
2e080 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f data is ready fo
2e090 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
2e0a0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 the.** caller. T
2e0b0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
2e0c0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 accessed using
2e0d0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 the [column acce
2e0e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a ss functions]..*
2e0f0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2e100 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e is called again
2e110 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 to retrieve the
2e120 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 next row of dat
2e130 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 a..**.** ^[SQLIT
2e140 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
2e150 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
2e160 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
2e170 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
2e180 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
2e190 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
2e1a0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
2e1b0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
2e1c0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
2e1d0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
2e1e0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
2e1f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2e200 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
2e210 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 ^With the legacy
2e220 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
2e230 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
2e240 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
2e250 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
2e260 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
2e270 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
2e280 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
2e290 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
2e2a0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
2e2b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2e2c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
2e2d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2e2e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 statement]. ^I
2e2f0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
2e300 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 face,.** the mor
2e310 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
2e320 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
2e330 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 d directly by sq
2e340 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a lite3_step()..**
2e350 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
2e360 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SE] means that t
2e370 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 he this routine
2e380 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 was called inapp
2e390 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 ropriately..** P
2e3a0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 erhaps it was ca
2e3b0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 lled on a [prepa
2e3c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
2e3d0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 hat has.** alrea
2e3e0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 dy been [sqlite3
2e3f0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
2e400 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 lized] or on one
2e410 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 that had.** pre
2e420 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
2e430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2e440 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
2e450 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a . Or it could.*
2e460 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 * be the case th
2e470 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 at the same data
2e480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2e490 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 is being used by
2e4a0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 two or.** more
2e4b0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
2e4c0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 ame moment in ti
2e4d0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c me..**.** For al
2e4e0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 l versions of SQ
2e4f0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 Lite up to and i
2e500 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e ncluding 3.6.23.
2e510 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 1, a call to.**
2e520 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2e530 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 ] was required a
2e540 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 fter sqlite3_ste
2e550 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 p() returned any
2e560 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 thing.** other t
2e570 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2e580 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 before any subs
2e590 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f equent invocatio
2e5a0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n of.** sqlite3_
2e5b0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 step(). Failure
2e5c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 to reset the pr
2e5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e5e0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 using .** [sqli
2e5f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 te3_reset()] wou
2e600 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ld result in an
2e610 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2e620 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 return from.** s
2e630 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2e640 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f But after versio
2e650 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 n 3.6.23.1, sqli
2e660 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
2e670 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
2e680 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
2e690 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
2e6a0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
2e6b0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
2e6c0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
2e6d0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
2e6e0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
2e6f0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
2e700 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
2e710 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
2e720 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
2e730 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
2e740 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
2e750 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
2e760 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
2e770 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
2e780 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
2e790 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
2e7a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
2e7b0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
2e7c0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
2e7d0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
2e7e0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
2e7f0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2e800 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
2e810 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
2e820 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
2e830 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
2e840 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
2e850 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
2e860 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
2e870 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2e880 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
2e890 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
2e8a0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
2e8b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2e8c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2e8d0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
2e8e0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
2e8f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
2e900 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
2e910 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
2e920 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
2e930 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
2e940 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
2e950 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
2e960 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
2e970 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
2e980 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
2e990 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
2e9a0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
2e9b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
2e9c0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2e9d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2e9e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2e9f0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
2ea00 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
2ea10 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
2ea20 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2ea30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ea40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
2ea50 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
2ea60 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2ea70 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
2ea80 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
2ea90 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2eaa0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
2eab0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2eac0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2ead0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2eae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 int sqlite3_ste
2eaf0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 p(sqlite3_stmt*)
2eb00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2eb10 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c F: Number of col
2eb20 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 umns in a result
2eb30 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 set.**.** ^The
2eb40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2eb50 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 nt(P) interface
2eb60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2eb70 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2eb80 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 the.** current
2eb90 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c row of the resul
2eba0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 t set of [prepar
2ebb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2ebc0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 .** ^If prepared
2ebd0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 statement P doe
2ebe0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c s not have resul
2ebf0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 ts ready to retu
2ec00 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 rn.** (via calls
2ec10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2ec20 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 _column_int | sq
2ec30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 lite3_column_*()
2ec40 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 ] of.** interfac
2ec50 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 es) then sqlite3
2ec60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
2ec70 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 eturns 0..** ^Th
2ec80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2ec90 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2eca0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 also returns 0 i
2ecb0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f P is a NULL po
2ecc0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 inter..** ^The s
2ecd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2ece0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 t(P) routine ret
2ecf0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 urns 0 if the pr
2ed00 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a evious call to.*
2ed10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d * [sqlite3_step]
2ed20 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 (P) returned [SQ
2ed30 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 LITE_DONE]. ^Th
2ed40 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2ed50 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 ount(P).** will
2ed60 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 return non-zero
2ed70 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c if previous call
2ed80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2ed90 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a p](P) returned.*
2eda0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 * [SQLITE_ROW],
2edb0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 except in the ca
2edc0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d se of the [PRAGM
2edd0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 A incremental_va
2ede0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 cuum].** where i
2edf0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
2ee00 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 zero since each
2ee10 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 step of that mu
2ee20 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 lti-step.** prag
2ee30 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c ma returns 0 col
2ee40 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a umns of data..**
2ee50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2ee60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2ee70 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 unt()].*/.SQLITE
2ee80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2ee90 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
2eea0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2eeb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2eec0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
2eed0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 atatypes.** KEYW
2eee0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 ORDS: SQLITE_TEX
2eef0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 T.**.** ^(Every
2ef00 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
2ef10 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
2ef20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
2ef30 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
2ef40 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
2ef50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2ef60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
2ef70 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
2ef80 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
2ef90 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
2efa0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
2efb0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a LL.** </ul>)^.**
2efc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
2efd0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f nts are codes fo
2efe0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 r each of those
2eff0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 types..**.** Not
2f000 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 e that the SQLIT
2f010 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 E_TEXT constant
2f020 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e was also used in
2f030 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2f040 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 2.** for a compl
2f050 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 etely different
2f060 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 meaning. Softwa
2f070 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 re that links ag
2f080 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 ainst both.** SQ
2f090 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 Lite version 2 a
2f0a0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
2f0b0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 n 3 should use S
2f0c0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 QLITE3_TEXT, not
2f0d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e .** SQLITE_TEXT.
2f0e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
2f0f0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 TE_INTEGER 1.#d
2f100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f efine SQLITE_FLO
2f110 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 AT 2.#define
2f120 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 SQLITE_BLOB
2f130 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2f140 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 _NULL 5.#ifd
2f150 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2f160 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 undef SQLITE_TE
2f170 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e XT.#else.# defin
2f180 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 e SQLITE_TEXT
2f190 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 3.#endif.#defi
2f1a0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 ne SQLITE3_TEXT
2f1b0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 3../*.** CAP
2f1c0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 I3REF: Result Va
2f1d0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 lues From A Quer
2f1e0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b y.** KEYWORDS: {
2f1f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2f200 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
2f210 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
2f220 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 rm the "result s
2f230 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a et" interface..*
2f240 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
2f250 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
2f260 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
2f270 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
2f280 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
2f290 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
2f2a0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 query. ^In ever
2f2b0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 y case the first
2f2c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2f2d0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
2f2e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2f2f0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 ment] that is be
2f300 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 ing evaluated (t
2f310 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2f320 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 *].** that was r
2f330 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 eturned from [sq
2f340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2f350 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
2f360 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 s variants).** a
2f370 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 nd the second ar
2f380 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
2f390 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
2f3a0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
2f3b0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c rmation.** shoul
2f3c0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e d be returned. ^
2f3d0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2f3e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
2f3f0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e t set has the in
2f400 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e dex 0..** ^The n
2f410 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2f420 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 in the result c
2f430 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
2f440 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2f450 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2f460 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
2f470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
2f480 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
2f490 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
2f4a0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
2f4b0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
2f4c0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
2f4d0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
2f4e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
2f4f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
2f500 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
2f510 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
2f520 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
2f530 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2f540 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
2f550 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
2f560 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
2f570 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
2f580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2f590 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
2f5a0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
2f5b0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
2f5c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2f5d0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
2f5e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2f5f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
2f600 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
2f610 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
2f620 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
2f630 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
2f640 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
2f650 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
2f660 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2f670 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
2f680 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
2f690 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f6a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2f6b0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
2f6c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
2f6d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
2f6e0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
2f6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2f700 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
2f710 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
2f720 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
2f730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2f740 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f column_type() ro
2f750 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2f760 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e.** [SQLITE_INT
2f770 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 EGER | datatype
2f780 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e code] for the in
2f790 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a itial data type.
2f7a0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
2f7b0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 column. ^The r
2f7c0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
2f7d0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2f7e0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
2f7f0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
2f800 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
2f810 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
2f820 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
2f830 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
2f840 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2f850 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2f860 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
2f870 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
2f880 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
2f890 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
2f8a0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
2f8b0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
2f8c0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
2f8d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
2f8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2f8f0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
2f900 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
2f910 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2f920 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
2f930 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
2f940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2f950 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
2f960 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2f970 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2f980 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2f990 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 or UTF-8 string
2f9a0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
2f9b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2f9c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
2f9d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2f9e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
2f9f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
2fa00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2fa10 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 t is a UTF-16 st
2fa20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2fa30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2fa40 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2fa50 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2fa60 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 8 and then retur
2fa70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2fa80 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
2fa90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e he result is a n
2faa0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 umeric value the
2fab0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2fac0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a _bytes() uses.**
2fad0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
2fae0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
2faf0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
2fb00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e UTF-8 string an
2fb10 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
2fb20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2fb30 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
2fb40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fb50 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
2fb60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fb70 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 bytes() returns
2fb80 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 zero..**.** ^If
2fb90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2fba0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 BLOB or UTF-16 s
2fbb0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
2fbc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2fbd0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 tes16().** routi
2fbe0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
2fbf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2fc00 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
2fc10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2fc20 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 e result is a UT
2fc30 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e F-8 string, then
2fc40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fc50 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 bytes16() conver
2fc60 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2fc70 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 to UTF-16 and t
2fc80 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
2fc90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
2fca0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fcb0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
2fcc0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
2fcd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2fce0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 6() uses.** [sql
2fcf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
2fd00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
2fd10 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
2fd20 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 16 string and re
2fd30 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2fd40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2fd50 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2fd60 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2fd70 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2fd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2fd90 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 s16() returns ze
2fda0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 ro..**.** ^The v
2fdb0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
2fdc0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2fdd0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a n_bytes()] and .
2fde0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2fdf0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f mn_bytes16()] do
2fe00 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 not include the
2fe10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2fe20 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 s at the end.**
2fe30 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 of the string.
2fe40 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 ^For clarity: th
2fe50 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
2fe60 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
2fe70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
2fe80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f and [sqlite3_co
2fe90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 lumn_bytes16()]
2fea0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f are the number o
2feb0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
2fec0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 e string, not th
2fed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
2fee0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 acters..**.** ^S
2fef0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
2ff00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2ff10 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c n_text() and sql
2ff20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2ff30 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 16(),.** even em
2ff40 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 pty strings, are
2ff50 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
2ff60 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 minated. ^The r
2ff70 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 eturn.** value f
2ff80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 rom sqlite3_colu
2ff90 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 mn_blob() for a
2ffa0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
2ffb0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2ffc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f er..**.** ^The o
2ffd0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
2ffe0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
2fff0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e n_value()] is an
30000 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
30010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30020 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 object. An unpr
30030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
30040 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 value object.**
30050 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
30060 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 with [sqlite3_b
30070 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ind_value()] and
30080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
30090 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 _value()]..** If
300a0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 the [unprotecte
300b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
300c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
300d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
300e0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
300f0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f is used in any o
30100 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 ther way, includ
30110 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 ing calls.** to
30120 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
30130 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
30140 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
30150 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 lue_text()],.**
30160 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 or [sqlite3_valu
30170 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e e_bytes()], then
30180 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
30190 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
301a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
301b0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 attempt to conv
301c0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 ert the value wh
301d0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e ere appropriate.
301e0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c ^For.** exampl
301f0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e e, if the intern
30200 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
30210 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 n is FLOAT and a
30220 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 text result.**
30230 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 is requested, [s
30240 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
30250 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 )] is used inter
30260 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d nally to perform
30270 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 the.** conversi
30280 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 on automatically
30290 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 . ^(The followi
302a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 ng table details
302b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 the conversions
302c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 .** that are app
302d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lied:.**.** <blo
302e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 ckquote>.** <tab
302f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a le border="1">.*
30300 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 * <tr><th> Inter
30310 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e nal<br>Type <th>
30320 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 Requested<br>Ty
30330 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 pe <th> Convers
30340 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
30350 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
30360 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
30370 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c Result is 0.** <
30380 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
30390 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
303a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
303b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 .0.** <tr><td>
303c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 NULL <td> T
303d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 EXT <td> Resu
303e0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
303f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
30400 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
30410 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 BLOB <td> Re
30420 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
30430 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
30440 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
30450 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
30460 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 Convert from int
30470 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a eger to float.**
30480 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
30490 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 R <td> TEXT
304a0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
304b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e dering of the in
304c0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
304d0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
304e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
304f0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e ame as INTEGER->
30500 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
30510 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
30520 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
30530 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
30540 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
30550 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
30560 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
30570 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
30580 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
30590 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
305a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b BLOB <td> [
305b0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a CAST] to BLOB.**
305c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
305d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
305e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
305f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
30600 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
30610 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
30620 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c > [CAST] to REAL
30630 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
30640 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
30650 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
30660 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
30670 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
30680 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
30690 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
306a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
306b0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
306c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
306d0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 o REAL.** <tr><t
306e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
306f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
30700 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
30710 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
30720 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
30730 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
30740 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 *.** The table a
30750 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 bove makes refer
30760 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 ence to standard
30770 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 C library funct
30780 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 ions atoi().** a
30790 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 nd atof(). SQLi
307a0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c te does not real
307b0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e ly use these fun
307c0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 ctions. It has
307d0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 its.** own equiv
307e0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 alent internal r
307f0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 outines. The at
30800 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 oi() and atof()
30810 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 names are.** use
30820 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 d in the table f
30830 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 or brevity and b
30840 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 ecause they are
30850 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 familiar to most
30860 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 .** C programmer
30870 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
30880 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e at when type con
30890 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 versions occur,
308a0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
308b0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 d by prior.** ca
308c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
308d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 olumn_blob(), sq
308e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
308f0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 t(), and/or.** s
30900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30910 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e xt16() may be in
30920 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 validated..** Ty
30930 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 pe conversions a
30940 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c nd pointer inval
30950 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f idations might o
30960 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ccur.** in the f
30970 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a ollowing cases:.
30980 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
30990 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
309a0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 ontent is a BLOB
309b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
309c0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a umn_text() or.**
309d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
309e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
309f0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f called. A zero
30a00 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 -terminator migh
30a10 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 t.** need t
30a20 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 o be added to th
30a30 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a e string.</li>.*
30a40 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
30a50 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
30a60 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
30a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
30a80 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
30a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30aa0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
30ab0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
30ac0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
30ad0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
30ae0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c F-16.</li>.** <l
30af0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
30b00 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
30b10 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
30b20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
30b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
30b50 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
30b60 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
30b70 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
30b80 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c to UTF-8.</l
30b90 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
30ba0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 * ^Conversions b
30bb0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
30bc0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
30bd0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
30be0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
30bf0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
30c00 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
30c10 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
30c20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
30c30 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
30c40 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
30c50 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 nter references
30c60 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d will have been m
30c70 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 odified. Other
30c80 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 kinds.** of conv
30c90 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 ersion are done
30ca0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 in place when it
30cb0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 is possible, bu
30cc0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 t sometimes they
30cd0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 .** are not poss
30ce0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 ible and in thos
30cf0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f e cases prior po
30d00 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c inters are inval
30d10 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 idated..**.** Th
30d20 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 e safest and eas
30d30 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 iest to remember
30d40 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e policy is to in
30d50 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 voke these routi
30d60 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 nes.** in one of
30d70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 the following w
30d80 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ays:.**.** <ul>.
30d90 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
30da0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f column_text() fo
30db0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
30dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30dd0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
30de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
30df0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 b() followed by
30e00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30e10 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
30e20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
30e30 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c mn_text16() foll
30e40 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
30e50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
30e60 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
30e70 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f *.** In other wo
30e80 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 rds, you should
30e90 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c call sqlite3_col
30ea0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 umn_text(),.** s
30eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
30ec0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 ob(), or sqlite3
30ed0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
30ee0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 first to force
30ef0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e the result.** in
30f00 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 to the desired f
30f10 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f ormat, then invo
30f20 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ke sqlite3_colum
30f30 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
30f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30f50 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 ytes16() to find
30f60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
30f70 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 result. Do not
30f80 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f mix calls.** to
30f90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30fa0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
30fb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
30fc0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a with calls to.**
30fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30fe0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 bytes16(), and d
30ff0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 o not mix calls
31000 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
31010 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 n_text16().** wi
31020 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 th calls to sqli
31030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31040 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ()..**.** ^The p
31050 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
31060 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
31070 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
31080 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 on occurs as.**
31090 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c described above,
310a0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 or until [sqlit
310b0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
310c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
310d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
310e0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 inalize()] is ca
310f0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f lled. ^The memo
31100 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f ry space used to
31110 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a hold strings.**
31120 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 and BLOBs is fr
31130 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c eed automaticall
31140 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 y. Do <b>not</b
31150 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 > pass the point
31160 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ers returned.**
31170 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
31180 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 lumn_blob()], [s
31190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
311a0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f xt()], etc. into
311b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
311c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 e()]..**.** ^(If
311d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
311e0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
311f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
31200 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
31210 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
31220 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
31230 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
31240 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
31250 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
31260 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
31270 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
31280 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
31290 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
312a0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
312b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
312c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
312d0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
312e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a QLITE_NOMEM].)^.
312f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
31300 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
31310 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
31320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31330 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
31340 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
31350 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
31360 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
31370 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
31380 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
31390 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
313a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
313b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
313c0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
313d0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 column_double(sq
313e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
313f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
31400 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
31410 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
31420 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
31430 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 l);.SQLITE_API s
31440 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
31450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
31460 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
31470 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
31480 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
31490 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
314a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
314b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
314c0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
314d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
314e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
314f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
31500 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31510 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
31520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31530 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
31540 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
31550 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
31560 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f _value *sqlite3_
31570 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
31580 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
31590 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
315a0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
315b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
315c0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
315d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
315e0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 inalize() functi
315f0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 on is called to
31600 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 delete a [prepar
31610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
31620 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
31630 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ecent evaluation
31640 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e of the statemen
31650 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f t encountered no
31660 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 errors.** or if
31670 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
31680 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 s never been eva
31690 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c luated, then sql
316a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
316b0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 returns.** SQLIT
316c0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d E_OK. ^If the m
316d0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
316e0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 ation of stateme
316f0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 nt S failed, the
31700 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e n.** sqlite3_fin
31710 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 alize(S) returns
31720 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 the appropriate
31730 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
31740 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 .** [extended er
31750 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
31760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 ^The sqlite3_fi
31770 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e nalize(S) routin
31780 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
31790 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
317a0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 ing.** the life
317b0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 cycle of [prepar
317c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a ed statement] S:
317d0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 .** before state
317e0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 ment S is ever e
317f0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a valuated, after.
31800 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 ** one or more c
31810 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
31820 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 _reset()], or af
31830 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 ter any call.**
31840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
31850 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f ()] regardless o
31860 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
31870 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
31880 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 as.** completed
31890 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a execution..**.**
318a0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 ^Invoking sqlit
318b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e e3_finalize() on
318c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
318d0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
318e0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 -op..**.** The a
318f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
31900 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b finalize every [
31910 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31920 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 nt] in order to
31930 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 avoid.** resourc
31940 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 e leaks. It is
31950 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 a grievous error
31960 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 for the applica
31970 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 tion to try to u
31980 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 se.** a prepared
31990 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
319a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e it has been fin
319b0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 alized. Any use
319c0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a of a prepared.*
319d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 * statement afte
319e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
319f0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 nalized can resu
31a00 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
31a10 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 and.** undesirab
31a20 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 le behavior such
31a30 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e as segfaults an
31a40 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f d heap corruptio
31a50 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
31a60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e int sqlite3_fin
31a70 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
31a80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
31a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
31aa0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
31ab0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
31ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
31ad0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
31ae0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
31af0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
31b00 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
31b10 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
31b20 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
31b30 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
31b40 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e executed..** ^An
31b50 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
31b60 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
31b70 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
31b80 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
31b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
31ba0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
31bb0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
31bc0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
31bd0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
31be0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
31bf0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
31c00 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
31c10 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
31c20 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
31c30 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
31c40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31c50 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 ment] S.** back
31c60 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
31c70 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
31c80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
31c90 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
31ca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
31cb0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
31cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
31cd0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 ent] S returned
31ce0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
31cf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a [SQLITE_DONE],.*
31d00 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 * or if [sqlite3
31d10 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
31d20 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
31d30 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
31d40 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 then [sqlite3_re
31d50 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
31d60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
31d70 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
31d80 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
31d90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
31da0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
31db0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31dc0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
31dd0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b error, then.** [
31de0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
31df0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 ] returns an app
31e00 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
31e10 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
31e20 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
31e30 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
31e40 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
31e50 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 he values.** of
31e60 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e any [sqlite3_bin
31e70 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d d_blob|bindings]
31e80 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 on the [prepare
31e90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
31ea0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
31eb0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 t sqlite3_reset(
31ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
31ed0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
31ee0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 I3REF: Create Or
31ef0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 Redefine SQL Fu
31f00 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f nctions.** KEYWO
31f10 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 RDS: {function c
31f20 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
31f30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
31f40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31f50 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
31f60 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
31f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31f80 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
31f90 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 s}.**.** ^These
31fa0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
31fb0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
31fc0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
31fd0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
31fe0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
31ff0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
32000 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
32010 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
32020 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
32030 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
32040 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
32050 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
32060 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
32070 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
32080 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
32090 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
320a0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
320b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
320c0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
320d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
320e0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
320f0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
32100 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
32110 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
32120 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
32130 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
32140 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
32150 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
32160 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
32170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
32180 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
32190 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
321a0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
321b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
321c0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
321d0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
321e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
321f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
32200 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
32210 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
32220 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
32230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
32240 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
32250 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
32260 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
32270 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
32280 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
32290 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
322a0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
322b0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
322c0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
322d0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
322e0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
322f0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
32300 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
32310 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
32320 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
32330 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
32340 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
32350 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
32360 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
32370 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
32380 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
32390 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
323a0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
323b0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
323c0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
323d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
323e0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
323f0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
32400 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
32410 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
32420 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
32430 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
32440 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
32450 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
32460 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
32470 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
32480 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
32490 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
324a0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
324b0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
324c0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
324d0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
324e0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
324f0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
32500 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
32510 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
32520 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
32530 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
32540 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
32550 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
32560 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
32570 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
32580 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
32590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
325a0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
325b0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
325c0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
325d0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
325e0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 s. The applicat
325f0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 ion should set t
32600 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f his parameter to
32610 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
32620 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 6LE] if the func
32630 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
32640 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 ion invokes .**
32650 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
32660 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e ext16le()] on an
32670 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 input, or [SQLI
32680 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 TE_UTF16BE] if t
32690 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
326a0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 tion invokes [sq
326b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
326c0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16be()] on an in
326d0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 put, or.** [SQLI
326e0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 TE_UTF16] if [sq
326f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32700 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 16()] is used, o
32710 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a r [SQLITE_UTF8].
32720 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e ** otherwise. ^
32730 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e The same SQL fun
32740 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
32750 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
32760 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 times using.**
32770 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 different prefer
32780 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
32790 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 gs, with differe
327a0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
327b0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 ns for.** each e
327c0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 ncoding..** ^Whe
327d0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
327e0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
327f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
32800 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
32810 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
32820 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
32830 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
32840 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
32850 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
32860 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
32870 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 parameter may op
32880 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 tionally be ORed
32890 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
328a0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 TERMINISTIC].**
328b0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 to signal that t
328c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c he function will
328d0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
328e0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 he same result g
328f0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 iven.** the same
32900 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 inputs within a
32910 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
32920 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c ement. Most SQL
32930 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a functions are.*
32940 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e * deterministic.
32950 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b The built-in [
32960 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 random()] SQL fu
32970 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 nction is an exa
32980 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e mple of a.** fun
32990 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f ction that is no
329a0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e t deterministic.
329b0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 The SQLite que
329c0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 ry planner is ab
329d0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d le to.** perform
329e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 additional opti
329f0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 mizations on det
32a00 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 erministic funct
32a10 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 ions, so use.**
32a20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 of the [SQLITE_D
32a30 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c ETERMINISTIC] fl
32a40 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ag is recommende
32a50 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 d where possible
32a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 ..**.** ^(The fi
32a70 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
32a80 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
32a90 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
32aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
32ab0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
32ac0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
32ad0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
32ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
32af0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a r_data()].)^.**.
32b00 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 ** ^The sixth, s
32b10 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 eventh and eight
32b20 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
32b30 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
32b40 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
32b50 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
32b60 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
32b70 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
32b80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
32b90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
32ba0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
32bb0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
32bc0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
32bd0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
32be0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
32bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d NULL pointers m
32c00 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
32c10 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
32c20 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
32c30 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 ers. ^An aggrega
32c40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
32c50 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
32c60 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
32c70 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
32c80 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 l and NULL point
32c90 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 er must be passe
32ca0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f d for xFunc. ^To
32cb0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
32cc0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
32cd0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
32ce0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e , pass NULL poin
32cf0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 ters for all thr
32d00 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 ee function.** c
32d10 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
32d20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 ^(If the ninth p
32d30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
32d40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
32d50 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 ion_v2() is not
32d60 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 NULL,.** then it
32d70 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 is destructor f
32d80 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
32d90 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
32da0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 .** The destruc
32db0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 tor is invoked w
32dc0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
32dd0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 is deleted, eit
32de0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 her by being.**
32df0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 overloaded or wh
32e00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
32e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
32e20 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 s.)^.** ^The des
32e30 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 tructor is also
32e40 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 invoked if the c
32e50 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
32e60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
32e70 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a n_v2() fails..**
32e80 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 ^When the destr
32e90 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f uctor callback o
32ea0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 f the tenth para
32eb0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 meter is invoked
32ec0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 , it.** is passe
32ed0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d d a single argum
32ee0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 ent which is a c
32ef0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 opy of the appli
32f00 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 cation data .**
32f10 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 pointer which wa
32f20 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 s the fifth para
32f30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
32f40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32f50 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 _v2()..**.** ^It
32f60 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
32f70 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
32f80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
32f90 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
32fa0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
32fb0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
32fc0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
32fd0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
32fe0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
32ff0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 or differing pr
33000 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
33010 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 odings. ^SQLite
33020 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
33030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
33040 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c that most closel
33050 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
33060 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
33070 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
33080 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 s used. ^A func
33090 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
330a0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e ion with a non-n
330b0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 egative.** nArg
330c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
330d0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e etter match than
330e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c a function impl
330f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a ementation with.
33100 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 ** a negative nA
33110 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e rg. ^A function
33120 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
33130 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
33140 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
33150 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
33160 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
33170 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
33180 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
33190 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
331a0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e ifferent. .** ^
331b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
331c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
331d0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
331e0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
331f0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
33200 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
33210 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
33220 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
33230 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
33240 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
33250 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e d UTF16..**.** ^
33260 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
33270 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
33280 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
33290 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
332a0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
332b0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
332c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
332d0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
332e0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
332f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
33300 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
33310 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
33320 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
33330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
33340 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
33350 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
33360 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
33370 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
33380 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
33390 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
333a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
333b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
333c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
333d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
333e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
333f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
33400 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
33410 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
33420 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
33430 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
33440 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
33450 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
33460 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
33470 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
33480 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
33490 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
334a0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
334b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
334c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
334d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
334e0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a ,. const void *
334f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
33500 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
33510 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
33520 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
33530 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
33540 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
33550 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
33560 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
33570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33580 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
33590 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
335a0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
335b0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c context*).);.SQL
335c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
335d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
335e0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ion_v2(. sqlite
335f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
33600 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
33610 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
33620 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
33630 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
33640 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
33650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33660 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33670 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
33680 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
33690 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
336a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
336b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
336c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a ite3_context*),.
336d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
336e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a )(void*).);../*.
336f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 ** CAPI3REF: Tex
33700 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a t Encodings.**.*
33710 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
33720 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 define integer
33730 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 codes that repre
33740 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 sent the various
33750 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e .** text encodin
33760 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 gs supported by
33770 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 SQLite..*/.#defi
33780 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 ne SQLITE_UTF8
33790 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
337a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c ne SQLITE_UTF16L
337b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 E 2.#defi
337c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 ne SQLITE_UTF16B
337d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 E 3.#defi
337e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
337f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
33800 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
33810 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
33820 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
33830 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
33840 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 Deprecated */.#d
33850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
33860 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
33870 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
33880 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
33890 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
338a0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 3REF: Function F
338b0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lags.**.** These
338c0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 constants may b
338d0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 e ORed together
338e0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
338f0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 LITE_UTF8 | pref
33900 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
33910 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 ing] as the four
33920 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
33930 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
33940 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b e_function()], [
33950 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33960 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 unction16()], or
33970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
33980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
33990 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
339a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
339b0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a TIC 0x800../*
339c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
339d0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
339e0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
339f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
33a00 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
33a10 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
33a20 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
33a30 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
33a40 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
33a50 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
33a60 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
33a70 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
33a80 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
33a90 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
33aa0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
33ab0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
33ac0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
33ad0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
33ae0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
33af0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
33b00 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
33b10 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
33b20 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 tell you what t
33b30 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
33b40 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
33b50 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
33b60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
33b70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
33b80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
33b90 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
33ba0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 xt*);.SQLITE_API
33bb0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
33bc0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
33bd0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
33be0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
33bf0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
33c00 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
33c10 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 transfer_binding
33c20 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
33c30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b sqlite3_stmt*);
33c40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
33c50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
33c60 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
33c70 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
33c80 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
33c90 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
33ca0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
33cb0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
33cc0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
33cd0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
33ce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
33cf0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f alarm(void(*)(vo
33d00 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 id*,sqlite3_int6
33d10 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 4,int),.
33d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
33d30 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 id*,sqlite3_int6
33d40 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 4);.#endif../*.*
33d50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
33d60 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 ining SQL Functi
33d70 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c on Parameter Val
33d80 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d ues.**.** The C-
33d90 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 language impleme
33da0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 ntation of SQL f
33db0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
33dc0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 regates uses.**
33dd0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 this set of inte
33de0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 rface routines t
33df0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 o access the par
33e00 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e ameter values on
33e10 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e .** the function
33e20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a or aggregate..*
33e30 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 *.** The xFunc (
33e40 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 for scalar funct
33e50 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 ions) or xStep (
33e60 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 for aggregates)
33e70 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
33e80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33e90 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
33ea0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33eb0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
33ec0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 * define callbac
33ed0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ks that implemen
33ee0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
33ef0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 ons and aggregat
33f00 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 es..** The 3rd p
33f10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 arameter to thes
33f20 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 e callbacks is a
33f30 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
33f40 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 ers to.** [prote
33f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
33f60 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 ue] objects. Th
33f70 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 ere is one [sqli
33f80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
33f90 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 t for.** each pa
33fa0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 rameter to the S
33fb0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 QL function. Th
33fc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
33fd0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 used to.** extr
33fe0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 act values from
33ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
34000 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a ue] objects..**.
34010 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
34020 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 s work only with
34030 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
34040 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34050 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ts..** Any attem
34060 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 pt to use these
34070 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b routines on an [
34080 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
34090 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 te3_value].** ob
340a0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 ject results in
340b0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
340c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 or..**.** ^These
340d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a routines work j
340e0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 ust like the cor
340f0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 responding [colu
34100 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
34110 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 ons].** except t
34120 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e hat these routin
34130 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 es take a single
34140 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
34150 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34160 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 t.** pointer ins
34170 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 tead of a [sqlit
34180 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 e3_stmt*] pointe
34190 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 r and an integer
341a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a column number..
341b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
341c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
341d0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 ) interface extr
341e0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 acts a UTF-16 st
341f0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e ring.** in the n
34200 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 ative byte-order
34210 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 of the host mac
34220 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 hine. ^The.** s
34230 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34240 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 t16be() and sqli
34250 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34260 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a le() interfaces.
34270 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 ** extract UTF-1
34280 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 6 strings as big
34290 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 -endian and litt
342a0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 le-endian respec
342b0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 tively..**.** ^(
342c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
342d0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
342e0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
342f0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
34300 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
34310 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
34320 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
34330 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
34340 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
34350 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
34360 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
34370 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
34380 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
34390 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
343a0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
343b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
343c0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
343d0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
343e0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
343f0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
34400 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
34410 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
34420 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
34430 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
34440 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
34450 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
34460 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
34470 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
34480 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a returned.)^.**.
34490 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
344a0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
344b0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
344c0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
344d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
344e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
344f0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
34500 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
34510 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
34520 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
34530 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
34540 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
34550 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
34560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
34570 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
34580 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
34590 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
345a0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
345b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
345c0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
345d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
345e0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
345f0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
34600 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
34610 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
34620 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
34630 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
34640 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 ameters..*/.SQLI
34650 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
34660 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
34670 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
34680 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34690 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 I int sqlite3_va
346a0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 lue_bytes(sqlite
346b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
346c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
346d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
346e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
346f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 .SQLITE_API doub
34700 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le sqlite3_value
34710 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
34720 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
34730 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
34740 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
34750 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34760 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
34770 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
34780 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
34790 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
347a0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
347b0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
347c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
347d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
347e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
347f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
34800 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 e_text16(sqlite3
34810 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34820 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
34830 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
34840 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
34850 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
34860 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
34870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
34880 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 xt16be(sqlite3_v
34890 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
348a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
348b0 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 alue_type(sqlite
348c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
348d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
348e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
348f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
34900 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
34910 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
34920 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
34930 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 Context.**.** I
34940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
34950 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 f aggregate SQL
34960 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 functions use th
34970 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f is.** routine to
34980 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
34990 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 for storing the
349a0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 ir state..**.**
349b0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
349c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
349d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
349e0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 N) routine is ca
349f0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 lled .** for a p
34a00 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 articular aggreg
34a10 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 ate function, SQ
34a20 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 Lite.** allocate
34a30 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a s N of memory, z
34a40 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d eroes out that m
34a50 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
34a60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
34a70 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 to the new memor
34a80 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e y. ^On second an
34a90 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
34aa0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
34ab0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
34ac0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
34ad0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
34ae0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a tion instance,.*
34af0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 * the same buffe
34b00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 r is returned.
34b10 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 Sqlite3_aggregat
34b20 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e e_context() is n
34b30 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 ormally.** calle
34b40 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
34b50 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 invocation of th
34b60 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b e xStep callback
34b70 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a and then one.**
34b80 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 last time when
34b90 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
34ba0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ack is invoked.
34bb0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 ^(When no rows
34bc0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 match.** an aggr
34bd0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 egate query, the
34be0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 xStep() callbac
34bf0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 k of the aggrega
34c00 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 te function.** i
34c10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
34c20 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e never called an
34c30 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 d xFinal() is ca
34c40 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 lled exactly onc
34c50 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 e..** In those c
34c60 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 ases, sqlite3_ag
34c70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
34c80 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 ) might be calle
34c90 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 d for the.** fir
34ca0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 st time from wit
34cb0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a hin xFinal().)^.
34cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34cd0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
34ce0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
34cf0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c e returns a NULL
34d00 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 pointer .** whe
34d10 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 n first called i
34d20 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e f N is less than
34d30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
34d40 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 o or if a memory
34d50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 .** allocate err
34d60 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a or occurs..**.**
34d70 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ^(The amount of
34d80 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 space allocated
34d90 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 by sqlite3_aggr
34da0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
34db0 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 N) is.** determi
34dc0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 ned by the N par
34dd0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 ameter on first
34de0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e successful call.
34df0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a Changing the.*
34e00 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 * value of N in
34e10 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
34e20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 to sqlite3_aggre
34e30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 gate_context() w
34e40 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d ithin.** the sam
34e50 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
34e60 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 tion instance wi
34e70 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 ll not resize th
34e80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
34e90 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 cation.)^ Withi
34ea0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c n the xFinal cal
34eb0 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 lback, it is cus
34ec0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a tomary to set.**
34ed0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f N=0 in calls to
34ee0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
34ef0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
34f00 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 so that no .** p
34f10 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 ointless memory
34f20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 allocations occu
34f30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 r..**.** ^SQLite
34f40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
34f50 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 rees the memory
34f60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a allocated by .**
34f70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
34f80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 te_context() whe
34f90 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 n the aggregate
34fa0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e query concludes.
34fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
34fc0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
34fd0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 be a copy of the
34fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
34ff0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 text | SQL funct
35000 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 ion context] tha
35010 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 t is the first p
35020 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
35030 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e he xStep or xFin
35040 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 al callback rout
35050 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ine that impleme
35060 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 nts the aggregat
35070 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a e.** function..*
35080 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
35090 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
350a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
350b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
350c0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
350d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
350e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
350f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
35100 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
35110 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
35120 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
35130 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
35140 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
35150 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
35160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35170 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
35180 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
35190 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
351a0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
351b0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
351c0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
351d0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
351e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
351f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
35200 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
35210 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35220 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
35230 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
35240 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
35250 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
35260 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35270 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
35280 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
35290 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
352a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
352b0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 h.** the applica
352c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
352d0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
352e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
352f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 void *sqlite3_us
35300 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f er_data(sqlite3_
35310 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
35320 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
35330 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
35340 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
35350 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35360 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
35370 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
35380 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
35390 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
353a0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
353b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
353c0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
353d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
353e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
353f0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
35400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35410 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
35420 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
35430 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
35440 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
35450 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
35460 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
35470 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 PI sqlite3 *sqli
35480 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
35490 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
354a0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
354b0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
354c0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
354d0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 a.**.** These fu
354e0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 nctions may be u
354f0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 sed by (non-aggr
35500 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 egate) SQL funct
35510 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
35520 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
35530 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
35540 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
35550 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
35560 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
35570 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
35580 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
35590 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
355a0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
355b0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
355c0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
355d0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
355e0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
355f0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a . An example.**
35600 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d of where this m
35610 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 ight be useful i
35620 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 s in a regular-e
35630 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 xpression matchi
35640 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ng.** function.
35650 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
35660 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
35670 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
35680 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a an be stored as.
35690 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f ** metadata asso
356a0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
356b0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 pattern string.
356c0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e .** Then as lon
356d0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e g as the pattern
356e0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 string remains
356f0 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 the same,.** the
35700 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
35710 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
35720 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
35730 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
35740 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
35750 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a e function..**.*
35760 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
35770 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
35780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
35790 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
357a0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
357b0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
357c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
357d0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
357e0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
357f0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
35800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
35810 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
35820 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f ^If there is no
35830 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
35840 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
35850 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
35860 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 nt, this sqlite3
35870 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _get_auxdata() i
35880 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 nterface.** retu
35890 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
358a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
358b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
358c0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 ta(C,N,P,X) inte
358d0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 rface saves P as
358e0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
358f0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
35900 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
35910 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35920 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 nction. ^Subseq
35930 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
35940 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
35950 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e data(C,N) return
35960 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 P from the most
35970 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 recent.** sqlit
35980 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
35990 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 ,N,P,X) call if
359a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
359b0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a still valid or.*
359c0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 * NULL if the me
359d0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 tadata has been
359e0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 discarded..** ^A
359f0 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 fter each call t
35a00 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
35a10 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 xdata(C,N,P,X) w
35a20 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 here X is not NU
35a30 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 LL,.** SQLite wi
35a40 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
35a50 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
35a60 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 n X with paramet
35a70 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 er P exactly.**
35a80 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d once, when the m
35a90 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 etadata is disca
35aa0 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 rded..** SQLite
35ab0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 is free to disca
35ac0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 rd the metadata
35ad0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 at any time, inc
35ae0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 luding: <ul>.**
35af0 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f <li> when the co
35b00 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 rresponding func
35b10 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 tion parameter c
35b20 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c hanges, or.** <l
35b30 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 i> when [sqlite3
35b40 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
35b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
35b60 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 ] is called for
35b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 the.** SQL
35b80 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a statement, or.**
35b90 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 <li> when sqlit
35ba0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
35bb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 is invoked agai
35bc0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 n on the same pa
35bd0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c rameter, or.** <
35be0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f li> during the o
35bf0 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f riginal sqlite3_
35c00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 set_auxdata() ca
35c10 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 ll when a memory
35c20 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 .** alloca
35c30 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
35c40 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a s. </ul>)^.**.**
35c50 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 Note the last b
35c60 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 ullet in particu
35c70 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 lar. The destru
35c80 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 ctor X in .** sq
35c90 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
35ca0 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 a(C,N,P,X) might
35cb0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 be called immed
35cc0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 iately, before t
35cd0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 he.** sqlite3_se
35ce0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
35cf0 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 rface even retur
35d00 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 ns. Hence sqlit
35d10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
35d20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 .** should be ca
35d30 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e lled near the en
35d40 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f d of the functio
35d50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
35d60 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 and the.** func
35d70 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
35d80 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d ion should not m
35d90 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 ake any use of P
35da0 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 after.** sqlite
35db0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
35dc0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e has been called.
35dd0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 .**.** ^(In prac
35de0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
35df0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
35e00 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
35e10 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ls for.** functi
35e20 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 on parameters th
35e30 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 at are compile-t
35e40 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 ime constants, i
35e50 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c ncluding literal
35e60 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b .** values and [
35e70 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 parameters] and
35e80 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 expressions comp
35e90 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 osed from the sa
35ea0 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 me.)^.**.** Thes
35eb0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 e routines must
35ec0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
35ed0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
35ee0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 n which.** the S
35ef0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
35f00 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
35f10 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
35f20 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
35f30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35f40 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
35f50 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
35f60 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
35f70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
35f80 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
35f90 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
35fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35fb0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
35fc0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
35fd0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
35fe0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
35ff0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
36000 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
36010 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
36020 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
36030 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
36040 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
36050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
36060 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 lob()]. ^If the
36070 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
36080 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
36090 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
360a0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
360b0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
360c0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
360d0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
360e0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
360f0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
36100 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 yed. ^The.** SQ
36110 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
36120 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
36130 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
36140 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
36150 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
36160 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
36170 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
36180 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
36190 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
361a0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
361b0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
361c0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
361d0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
361e0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
361f0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
36200 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f ++ compilers..*/
36210 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
36220 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
36230 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
36240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36250 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
36260 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
36270 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
36280 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
36290 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
362a0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
362b0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
362c0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
362d0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
362e0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 Function.**.** T
362f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
36300 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
36310 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
36320 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
36330 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
36340 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
36350 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
36360 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36370 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
36380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36390 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
363a0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
363b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
363c0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
363d0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
363e0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
363f0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
36400 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
36410 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
36420 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
36430 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
36440 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
36450 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
36460 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
36470 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
36480 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
36490 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
364a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
364b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
364c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
364d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
364e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
364f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36500 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
36510 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
36520 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
36530 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
36540 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
36550 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
36560 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
36570 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
36580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
36590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
365a0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
365b0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
365c0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
365d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
365e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
365f0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
36600 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
36610 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
36620 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
36630 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
36640 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
36650 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
36660 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
36670 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
36680 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
36690 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
366a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
366b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
366c0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
366d0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
366e0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
366f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
36700 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36710 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
36720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36730 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
36740 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
36750 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
36760 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
36770 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
36780 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
36790 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 he string pointe
367a0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 d to by the.** 2
367b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
367c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
367d0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 rror() or sqlite
367e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
367f0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 ().** as the tex
36800 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 t of an error me
36810 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 ssage. ^SQLite
36820 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
36830 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
36840 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
36850 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36860 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 () as UTF-8. ^SQ
36870 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
36880 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
36890 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
368a0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
368b0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
368c0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
368d0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
368e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
368f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
36900 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
36910 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
36920 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
36930 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
36940 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
36950 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
36960 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
36970 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
36980 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
36990 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
369a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
369b0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
369c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
369d0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
369e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
369f0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
36a00 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
36a10 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
36a20 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
36a30 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
36a40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e or message..** ^
36a50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36a60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
36a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36a80 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 ror16().** routi
36a90 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 nes make a priva
36aa0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 te copy of the e
36ab0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
36ac0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 t before.** they
36ad0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c return. Hence,
36ae0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
36af0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f ction can deallo
36b00 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 cate or.** modif
36b10 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 y the text after
36b20 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 they return wit
36b30 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 hout harm..** ^T
36b40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36b50 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 t_error_code() f
36b60 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 unction changes
36b70 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a the error code.*
36b80 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 * returned by SQ
36b90 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 Lite as a result
36ba0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 of an error in
36bb0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 a function. ^By
36bc0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
36bd0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
36be0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 QLITE_ERROR. ^A
36bf0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
36c00 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
36c10 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
36c20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36c30 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
36c40 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
36c50 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
36c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36c70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36c80 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
36c90 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
36ca0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
36cb0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
36cc0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
36cd0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c or BLOB is too l
36ce0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ong to represent
36cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36d00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36d10 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 r_nomem() interf
36d20 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
36d30 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
36d40 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
36d50 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 g that a memory
36d60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
36d70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
36d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
36d90 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
36da0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
36db0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
36dc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36dd0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36de0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
36df0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
36e00 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
36e10 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
36e20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
36e30 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 sult_int64() int
36e40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
36e50 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
36e60 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
36e70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36e80 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 ion to be the 64
36e90 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
36ea0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
36eb0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
36ec0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
36ed0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36ee0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 t_null() interfa
36ef0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
36f00 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
36f10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36f20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36f30 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a to be NULL..**.*
36f40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
36f50 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 esult_text(), sq
36f60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
36f70 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 t16(),.** sqlite
36f80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
36f90 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
36fa0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
36fb0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
36fc0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
36fd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
36fe0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36ff0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
37000 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
37010 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
37020 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
37030 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
37040 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
37050 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
37060 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
37070 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
37080 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 ively..** ^The s
37090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
370a0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 xt64() interface
370b0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
370c0 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 value of an.**
370d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
370e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
370f0 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 be a text string
37100 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a in an encoding.
37110 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ** specified by
37120 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c the fifth (and l
37130 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 ast) parameter,
37140 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e which must be on
37150 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f e.** of [SQLITE_
37160 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
37170 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 TF16], [SQLITE_U
37180 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c TF16BE], or [SQL
37190 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a ITE_UTF16LE]..**
371a0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 ^SQLite takes t
371b0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
371c0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
371d0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
371e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
371f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
37200 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
37210 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 aces..** ^If the
37220 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
37230 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
37240 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
37250 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
37260 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
37270 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
37280 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
37290 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
372a0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
372b0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
372c0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
372d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
372e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
372f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
37300 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 ** is non-negati
37310 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 ve, then as many
37320 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
37330 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 acters) of the t
37340 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ext.** pointed t
37350 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 o by the 2nd par
37360 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e ameter are taken
37370 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 as the applicat
37380 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 ion-defined.** f
37390 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 unction result.
373a0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
373b0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 meter is non-neg
373c0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a ative, then it.*
373d0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 * must be the by
373e0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 te offset into t
373f0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
37400 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
37410 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 or would.** appe
37420 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ar if the string
37430 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 where NUL termi
37440 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
37450 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
37460 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 cur.** in the st
37470 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f ring at a byte o
37480 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 ffset that is le
37490 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 ss than the valu
374a0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 e of the 3rd.**
374b0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
374c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
374d0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 ring will contai
374e0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 n embedded NULs
374f0 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c and the.** resul
37500 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
37510 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 operating on st
37520 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 rings with embed
37530 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
37540 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 fined..** ^If th
37550 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
37560 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
37570 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
37580 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
37590 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
375a0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
375b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
375c0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
375d0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
375e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
375f0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
37600 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
37610 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
37620 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
37630 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
37640 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
37650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37660 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
37670 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
37680 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
37690 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
376a0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
376b0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
376c0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
376d0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
376e0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
376f0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
37700 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
37710 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
37720 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
37730 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
37740 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
37750 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
37760 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
37770 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
37780 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
37790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
377a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
377b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
377c0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
377d0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
377e0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
377f0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
37800 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
37810 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
37820 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
37830 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
37840 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
37850 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
37860 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
37870 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
37880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37890 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
378a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
378b0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
378c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
378d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
378e0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
378f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
37900 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
37910 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
37920 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
37930 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
37940 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
37950 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
37960 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
37970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
37980 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
37990 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
379a0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
379b0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
379c0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
379d0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
379e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
379f0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
37a00 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
37a10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
37a20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
37a30 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
37a40 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
37a50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37a70 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
37a80 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
37a90 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
37aa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
37ab0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
37ac0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
37ad0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
37ae0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
37af0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
37b00 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
37b10 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
37b20 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
37b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
37b40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
37b50 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
37b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
37b70 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
37b80 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
37b90 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
37ba0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
37bb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
37bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
37bd0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
37be0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
37bf0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
37c00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
37c10 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 ult_blob64(sqlit
37c20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 e3_context*,cons
37c30 74 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f t void*,sqlite3_
37c40 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 uint64,void(*)(v
37c50 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
37c60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
37c70 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
37c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37c90 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f double);.SQLITE_
37ca0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
37cb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
37cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37cd0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
37ce0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
37cf0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37d00 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
37d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
37d20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 t void*, int);.S
37d30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
37d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
37d50 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
37d60 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
37d70 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
37d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37d90 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 or_nomem(sqlite3
37da0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
37db0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
37dc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37dd0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
37de0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 ntext*, int);.SQ
37df0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
37e00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
37e10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37e20 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
37e30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
37e40 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
37e50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37e60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
37e70 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
37e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
37e90 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ull(sqlite3_cont
37ea0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
37eb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
37ec0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
37ed0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
37ee0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
37ef0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
37f00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
37f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37f20 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f ext64(sqlite3_co
37f30 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
37f40 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
37f50 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 64,.
37f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
37f70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 oid(*)(void*), u
37f80 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 nsigned char enc
37f90 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 oding);.SQLITE_A
37fa0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
37fb0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 result_text16(sq
37fc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37fd0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
37fe0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
37ff0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
38000 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
38010 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 t_text16le(sqlit
38020 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
38030 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
38040 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
38050 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
38060 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38070 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 xt16be(sqlite3_c
38080 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
38090 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
380a0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
380b0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
380c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
380d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
380e0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
380f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
38100 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
38110 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
38120 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
38130 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
38140 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
38150 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
38160 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 nces.**.** ^Thes
38170 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c e functions add,
38180 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 remove, or modi
38190 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d fy a [collation]
381a0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
381b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
381c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
381d0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 ecified as the f
381e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
381f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
38200 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 f the collation
38210 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
38220 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
38230 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
38240 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
38250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
38260 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
38270 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
38280 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
38290 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 r for sqlite3_cr
382a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
382b0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f ()..** ^Collatio
382c0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d n names that com
382d0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 pare equal accor
382e0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 ding to [sqlite3
382f0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 _strnicmp()] are
38300 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 .** considered t
38310 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 o be the same na
38320 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 me..**.** ^(The
38330 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 third argument (
38340 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 eTextRep) must b
38350 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
38360 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a stants:.** <ul>.
38370 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
38380 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b UTF8],.** <li> [
38390 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
383a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
383b0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c _UTF16BE],.** <l
383c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
383d0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
383e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
383f0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NED]..** </ul>)^
38400 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 .** ^The eTextRe
38410 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 p argument deter
38420 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 mines the encodi
38430 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 ng of strings pa
38440 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ssed.** to the c
38450 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
38460 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c n callback, xCal
38470 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b lback..** ^The [
38480 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e SQLITE_UTF16] an
38490 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f d [SQLITE_UTF16_
384a0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 ALIGNED] values
384b0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 for eTextRep.**
384c0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f force strings to
384d0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e be UTF16 with n
384e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
384f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
38500 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
38510 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 value for eText
38520 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e Rep forces strin
38530 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f gs to begin.** o
38540 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 n an even byte a
38550 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ddress..**.** ^T
38560 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
38570 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 nt, pArg, is an
38580 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
38590 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 pointer that is
385a0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 passed.** throu
385b0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 gh as the first
385c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
385d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
385e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a on callback..**.
385f0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
38600 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 gument, xCallbac
38610 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 k, is a pointer
38620 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 to the collating
38630 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d function..** ^M
38640 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e ultiple collatin
38650 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 g functions can
38660 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 be registered us
38670 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ing the same nam
38680 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 e but.** with di
38690 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 fferent eTextRep
386a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
386b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
386c0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e whichever.** fun
386d0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 ction requires t
386e0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
386f0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 of data transfor
38700 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 mation..** ^If t
38710 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 he xCallback arg
38720 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 ument is NULL th
38730 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 en the collating
38740 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
38750 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 deleted. ^When
38760 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 all collating fu
38770 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 nctions having t
38780 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 he same name